계약: Core 지원 정보와 Seal 호환 확인

이 계약은 v0.1.8의 Core 0.1.8·Seal 0.1.23에 적용한다. 아래 지원 정보 예시는 그 배포판의 것이며, Seal 0.1.26과 run-rules/6은 §10, 현재 Seal과 run-rules/7은 §11에서 다룬다. 지원 정보 조회는 v0.1.3에서 도입했으며 이전 배포판 v0.1.2에는 이 명령이 없다. 업데이트 뒤에도 실제 실행 파일의 지원 정보를 확인하며 버전 숫자만으로 호환성을 판단하지 않는다. Spec은 Core 설치나 이 조회 없이 문서를 작성한다.

1. 목표 없는 조회#

ha capabilities --format json

--format 생략 시에도 JSON을 출력한다. 목표 인수와 JSON 이외의 형식은 받지 않는다. 이 실행 파일이 지원하는 내용을 stdout에 JSON 객체 하나와 줄바꿈으로 출력한다. 목표·저장소·설정·실행 기록을 열거나 바꾸지 않고, Git·검사·모델 프로세스도 시작하지 않는다. 같은 바이너리의 조회 내용은 현재 시각이나 작업 폴더에 따라 달라지지 않는다.

종료 코드는 성공 0, 잘못된 인수 64, 출력 실패 70이다. 구 Core의 알 수 없는 명령 종료 64는 조회 미지원이며, 버전 출력 성공으로 대신 통과시키지 않는다. 다른 실패·시간 초과·읽을 수 없는 출력도 지원 확인 성공이 아니다.

{
  "schema": "ha-capabilities/v1",
  "ha_version": "0.1.8",
  "supported_rules": ["run-rules/1", "run-rules/2", "run-rules/3", "run-rules/4", "run-rules/5"],
  "default_rules": "run-rules/3",
  "formats": {
    "criteria": ["legacy", "nested/1"],
    "check_declaration": ["check-declaration/v1", "check-adapter/v1"],
    "check_result": ["check-result/v1"],
    "check_evidence": ["check-evidence/v1"],
    "finding": ["run-finding/v1"],
    "decision_history": ["decision-history/v1"],
    "timing": ["timing/v1"],
    "assurance_tier": ["light", "standard", "strict"],
    "core_requirements": ["core-requirements/v1"],
    "review_gate": ["review-gate/v1"]
  },
  "features": [
    "estimate/v1", "dirty-preflight/v1", "baseline-safe-copy/v1",
    "structured-change-results/v1", "budget-change/v1",
    "post-completion-findings/v1", "decision-history/v1", "run-timing/v1",
    "test-authority/v1", "reported-wait/v1", "preapproved-runs/v1",
    "error-recovery/v1", "command-time-limits/v1", "runner-adapters/v1",
    "report/v1", "doctor/v1", "auto-budget/v1", "core-requirements/v1",
    "review-gate/v1"
  ]
}

선택적이라고 적은 formats.timing, formats.assurance_tier, formats.core_requirements, formats.review_gate를 뺀 위 필드는 모두 필수다. 목록은 중복 없는 문자열 배열이며 각 문자열은 비어 있지 않다. 빈 형식·기능 목록은 해당 지원이 없다는 뜻이다. 중복 JSON 키, 잘못된 타입, 필수 정보 누락, 손상·뒤에 붙은 JSON은 해석 불가다. 같은 schema의 추가 필드·새 목록 항목은 허용하되 소비자가 아는 필수 지원을 대신하지 않는다.

시간 보기를 지원하는 Core는 formats.timing에 timing/v1, features에 run-timing/v1을 제공한다(실행 기록 §1.2, §2.2). 측정값은 판정·예산에 쓰이지 않으므로 이 확장은 새 시작이나 기존 목표의 재개·검사·예산·발견 작업의 요구에 추가되지 않는다. 지원이 없는 Core에서도 일반 실행은 그대로이고, 시간 보기만 쓸 수 없다.

목표 문서의 Assurance: 줄(목표 문서 §2.5)을 읽고 검증하는 Core는 formats.assurance_tier에 light, standard, strict를 제공한다. v0.1.7 이후 배포판(위 예시는 v0.1.8)에는 이 항목이 있고 v0.1.6 이하 배포판에는 없다. 등급은 구현 담당이 받을 검토의 범위를 정한다. run-rules/4 이하로 시작한 목표에서는 판정, ha status와 ha done의 출력, 예산이 등급 때문에 바뀌지 않고, run-rules/5로 시작한 standard·strict 목표는 기록된 검토 gate가 완료 조건이 된다(§9). 줄은 SPEC.md의 일부이므로 목표 digest에 들어가고, 올바른 줄이 있으면 ha lint 성공 출력에 assurance tier: <등급> 줄이 더해지며, 형식이 틀린 줄은 다른 lint 오류처럼 ha start와 ha check를 막는다(목표 문서 §2.5, 실행 묶음 §8). 그래서 이 항목은 새 시작이나 기존 목표의 재개·검사·예산·발견 작업의 요구에 더하지 않는다. 항목이 없는 Core는 줄을 검증하지 않을 뿐이고 일반 실행은 그대로다. 이 항목의 이름은 ha status의 assurance 필드(근거 표시, 항상 local)와 섞이지 않도록 따로 정했다.

기능의 상세 의미는 실행 기록, 결과 계약, 목표 문서에 따른다. 지원 정보는 독립 인증이나 코드 무결성 증명이 아니다.

2. Seal 0.1.17의 소비 계약#

호환 확인은 상태를 바꾸는 작업 전에 수행한다. 실제 사용할 실행 파일의 절대 경로를 확정하고 그 경로로 조회한다. 성공한 실행 파일과 이후 사용할 Core가 달라지면 이전 확인을 재사용하지 않는다. PATH의 다른 파일, 다른 세션의 결과, 버전 문자열만으로 대체하지 않는다. 확인 뒤에도 경로·바이너리가 바뀌었으면 다시 확인한다. 조회는 자동 설치·권한 확대·목표 또는 기록 변경의 권한을 주지 않는다.

에이전트는 위 JSON을 아래 표와 직접 비교할 수 있다. Python이나 별도 호환 검사 프로그램은 Seal의 필수 의존성이 아니다.

새 시작에서 모르는 기본 규칙이나 이전 기본 규칙으로 조용히 대체하지 않는다. 기존 목표는 기본 시작 규칙을 적용하지 않는다. 예를 들어 기본이 미래 /4여도 저장된 /2와 요청에 필요한 지원이 있다면 기존 /2의 확인은 통과할 수 있다. 새 /3 지원 때문에 /1·/2 목표나 기록을 변환하거나 결과 선언을 추가하도록 요구하지 않는다.

조회 미지원·실패, 필수 정보 누락·해석 불가, 필요한 규칙·형식·기능 부족이면 확인한 대상과 이유를 알리고 새 시작·재개 등 상태 변경 전에 멈춘다. 구버전이면 설치 안내를 안내하되 자동 설치·업데이트하거나 구규칙으로 우회하지 않는다.

Seal 0.1.20부터는 이 표를 손으로 대조하지 않는다. 새 시작은 skill 폴더의 core-requirements.json(§8)에 필요한 지원을 선언하고 ha start --check-skill로 시작하므로, 빠진 지원이 있으면 Core가 기록 없이 거부한다. 그 선언에는 위 새 시작의 요구와 함께 report/v1, doctor/v1, auto-budget/v1, core-requirements/v1, formats.core_requirements의 core-requirements/v1, formats.assurance_tier의 light·standard·strict가 들어 있다. Seal 0.1.21의 선언은 규칙을 run-rules/5로 바꾸고 §9의 review-gate/v1 기능과 formats.review_gate를 더한다. 기존 목표는 각 명령이 저장된 규칙을 계산하거나 66으로 거부하며, Seal은 그 거부와 실행 파일을 보고하고 멈춘다. 실행 파일 절대 경로의 재확인은 하지 않는다. 기록의 줄마다 ha_version이 남고 ha status가 그것을 보인다.

호환 확인은 입력 lint, 저장 기록의 무결성, 사용자 구현 권한, 완료 판정을 대신하지 않는다. 이 표의 확인은 Seal이 한다. Core는 skill이 §8의 선언을 두면 ha start --skill에서 그 선언을 이 실행 파일의 지원 정보와 대조해 빠진 지원이 있으면 기록 없이 시작을 거부하고, 선언이 없는 skill의 시작은 그대로 받는다. 직접 Core를 사용하는 미선언 /3 change는 기존처럼 실제 시도를 기록하고 unknown으로 분류할 수 있다. 일반 maintain·manual·task 검사는 구조화 change 계약으로 강제 이전하지 않는다.

3. 선택적 결정적 소비 도구#

Python 3가 이미 있다면 Seal에 포함된 check_core.py로 같은 계약을 확인할 수 있다. 도구가 없거나 Python을 쓰지 않는 경우에도 위 계약을 직접 소비할 수 있다.

python3 <seal-skill>/scripts/check_core.py --ha <실제 Core 경로> --operation start
python3 <seal-skill>/scripts/check_core.py --ha <실제 Core 경로> --operation resume --goal <기존 목표>

Seal 0.1.20의 도구는 start에서 core-requirements.json의 요구를 모두 확인한다. 그래서 같은 실행 파일에 대해 새 시작을 호환이라고 판단하면 ha start --check-skill의 요구 확인도 거부하지 않는다. resume·check·budget·finding·history의 판단은 그대로다.

--ha는 기본 ha이며 PATH에서 처음 찾은 실행 파일을 사용한다. --operation은 start(기본), resume, check, budget, finding이다. start에는 목표를 받지 않고 나머지 요청에는 기존 목표를 받는다. 기존 목표의 첫 start, 기록의 schema와 SPEC 형식 선택자를 읽으며 실제 기록 무결성 검증은 Core에 남긴다.

도구는 symlink를 해소한 절대 경로로 한 번 조회한다. 조회 전후 SHA-256이 다르면 거부한다. 성공 시 응답의 executable 경로를 실제 Core 호출에도 사용한다. 해시는 영구 캐시나 비협조 외부 프로세스에 대한 교체 방지 보증이 아니다.

stdout은 seal-core-compatibility/v1 JSON이다. compatible, reason, requested_executable, executable, sha256, ha_version, operation, rules, missing을 제공한다. 아직 확인하지 못한 값은 null이며, 원문 Core 출력·목표 내용·사용자 발화를 복사하지 않는다. 실행 파일 경로는 로컬 진단 정보이므로 공개 보고에 그대로 옮길 필요가 없다.

• 종료 0: 호환 확인 성공.
• 종료 2: 확인 거부. core_missing, query_unsupported, query_failed, query_timeout, binary_changed, unsupported_schema, invalid_capabilities, unsupported_default_rule, unsupported_stored_rule, unsupported_record_schema, unsupported_operation, missing_support, goal_unreadable, goal_record_oversized, goal_format_invalid 중 사유를 제공한다. 저장된 발견 줄이 계약 상한을 넘으면 goal_record_oversized, 읽을 수 없거나 손상된 기록은 goal_unreadable, 알 수 없는 기록 schema는 unsupported_record_schema다.
• 종료 64: 도구 인수 오류.

조회는 5초 후 중단하며 자동 재시도하지 않는다. 이 도구는 실제 시작·재개·검사·설치를 실행하거나 결과를 파일로 저장하지 않는다. 설치된 Codex·Claude가 이 지침을 실제로 따르는지는 별도 호스트 검증 대상이다.

4. 선택적 완료 뒤 발견 확장#

Core 0.1.4부터 완료 뒤 발견을 포함하며 formats.finding에 run-finding/v1, features에 post-completion-findings/v1을 제공한다. 위 v0.1.8 배포 예시에도 두 항목이 있다. v0.1.3 Core에는 이 확장이 없으므로 실제 지원 정보를 확인하며, 버전 숫자만으로 기능을 추정하지 않는다. 기존 시작·검사·예산 작업의 요구는 유지한다. 발견 입력과 조회에는 실제 실행 파일의 두 추가 지원, 저장된 규칙과 현재 조건 형식의 지원을 확인한다. 발견 작업만을 위해 실행 기능이나 /3 선언 지원을 요구하지 않는다.

Seal 0.1.12에 포함된 선택형 도구는 --operation finding --goal <기존 목표>를 지원한다. 기존 목표에 run-finding/v1 줄이 있으면 resume·check·budget도 두 추가 지원을 요구한다. 도구는 알려진 줄 schema의 존재를 읽으며 해시·이력의 무결성은 Core가 검증한다. 알 수 없는 schema는 거부한다. 이전 설치의 도구에 새 인수가 있다고 가정하지 않으며, 실제 capability를 직접 확인하는 방법도 유효하다. 지원을 확인하지 못하면 새 발견 기록을 쓰지 않는다.

5. 선택적 판단 이력 확장#

판단 이력을 지원하는 Core는 formats.decision_history에 decision-history/v1, features에 decision-history/v1을 제공한다. 배포판 v0.1.5(ha 0.1.5)부터 이 확장을 제공하며 v0.1.4(ha 0.1.4)에는 없다. 이력의 등록과 조회에는 실제 실행 파일의 두 추가 지원, 저장된 시작 규칙과 현재 조건 형식의 지원을 확인한다. 판단 이력은 runs.jsonl 밖에 있으므로 이 확장은 새 시작이나 기존 목표의 재개·검사·예산·발견 작업의 요구에 추가되지 않는다. 지원이 없으면 이력을 쓰지 않고 기존 Markdown으로 인계한다.

Seal 0.1.13에 포함된 선택형 도구는 --operation history --goal <기존 목표>로 같은 확인을 한다. 이전 설치의 도구에 이 인수가 있다고 가정하지 않으며, 실제 capability를 직접 확인하는 방법도 유효하다.

현재 소스의 macOS·Linux 실행 파일과 Windows x64 로컬 후보는 두 판단 이력 항목을 같은 의미로 제공한다. Windows에서도 등록·재전송·정정·기본/current·list·두 방식의 show가 대상이며, 지원 정보만 있고 직접 호출은 일괄 미지원인 형태가 아니다. 이 기능 광고가 공개 Windows 릴리스나 Windows 11 설치·호스트 사용 인수를 뜻하지는 않는다. 플랫폼과 저장소 범위는 판단 이력 계약과 Windows 후보 안내에 따른다.

6. run-rules/4 기능#

run-rules/4를 지원하는 Core는 supported_rules에 run-rules/4, features에 test-authority/v1, reported-wait/v1, preapproved-runs/v1, error-recovery/v1, command-time-limits/v1을 함께 제공한다. default_rules는 run-rules/3 그대로다. 그래서 기본 규칙을 확인하는 이전 Seal과 배포·설치 식별은 바뀌지 않는다. 새 규칙은 ha start --rules run-rules/4로만 고른다. 다섯 기능의 의미는 실행 기록 §4.7이다.

Seal 0.1.16부터 확인 도구는 새 시작에서 이 규칙과 다섯 기능을 모두 요구하고 시작 규칙으로 run-rules/4를 낸다. 하나라도 없으면 기록 전에 거부한다. 저장 규칙이 /4인 목표의 재개·검사·횟수 상한 변경도 다섯 기능을 요구한다. /1·/2·/3 목표의 요구는 그대로다. /4를 지원하지 않는 Core는 그 목표를 66으로 거부하고 기록하지 않는다.

7. 러너 어댑터#

러너 어댑터를 지원하는 Core는 formats.check_declaration의 끝에 check-adapter/v1, features의 끝에 runner-adapters/v1을 더해 제공한다. 두 항목의 의미는 change 검사 결과 §5다. 기존 항목과 그 순서, default_rules는 그대로다.

어댑터는 선택이므로 이 확장은 새 시작이나 기존 목표의 재개·검사·예산·발견 작업의 요구에 추가되지 않는다. Seal과 호환 확인 도구의 요구도 그대로다. 실행자는 실제 실행 파일의 지원 정보에 두 항목이 모두 있을 때만 어댑터 선언을 쓴다. 지원이 없는 Core는 어댑터 선언을 알 수 없는 선언으로 보고 lint 문제(evidence_invalid)로 시작과 검사를 거부하며 기록하지 않는다. 그때는 참조 생산자나 전용 생산자를 쓴다.

8. skill의 Core 요구 선언#

skill은 SKILL.md와 같은 폴더의 core-requirements.json에 자신에게 필요한 Core 지원을 선언할 수 있다. ha start --skill <SKILL.md>가 이 선언을 읽어 실행 파일의 지원 정보(§1의 ha capabilities와 같은 값)와 대조한다(실행 기록 §1.6). 지원하는 Core는 formats.core_requirements에 core-requirements/v1, features에 core-requirements/v1을 제공한다.

{
  "schema": "core-requirements/v1",
  "rules": ["run-rules/4"],
  "formats": {"criteria": ["legacy", "nested/1"], "check_result": ["check-result/v1"]},
  "features": ["estimate/v1", "test-authority/v1"]
}

• 목록은 비어 있지 않은 문자열의 배열이고 한 목록 안에서 값이 겹치지 않는다. formats는 그런 목록을 값으로 갖는 객체다. 빈 목록이나 없는 필드는 그 종류의 요구가 없다는 뜻이다. 단 formats의 키는 목록이 비어 있어도 그 키 자체를 요구한다.
• UTF-8 JSON 객체 하나이며 64 KiB 이하다. 맨 앞 BOM 하나는 허용한다. 필드 이름은 정확한 철자여야 하며 대소문자만 다른 이름도 모르는 필드다. 다른 schema 값, 모르는 필드, 중복 키, 뒤에 붙은 데이터, null, 잘못된 타입은 형식 위반이다. 대상이 없는 symlink나 폴더처럼 읽을 수 없는 항목도 거부한다.
• 빠진 항목이 있으면 항목마다 ha: missing Core support: <rules|formats.<키>|features> <값> (ha <버전>)을 보이고(formats의 키 자체가 없고 그 목록이 비어 있으면 값 없이 formats.<키>), 형식 위반이면 그 이유를 보이며, 둘 다 기록 없이 65로 끝난다. 모르는 값을 무시하고 시작하지 않는다.
• 선언 파일이 없는 skill과 --skill 없는 시작은 이 확인을 하지 않는다. Seal 0.1.20은 선언을 두고 --check-skill로 시작한다. 선언하지 않은 Seal 0.1.17~0.1.19는 지금처럼 시작하며, 그 Seal들의 §2 확인과 check_core.py는 추가된 항목을 허용하므로 같은 결론을 낸다.
• --check-skill은 선언을 필수로 한다. 이 기능 전의 Core(배포판 v0.1.6 등)는 이 플래그를 모르는 플래그로 64에 끝내고 기록하지 않으므로, 확인이 반드시 일어나야 하는 시작은 ha start <goal> --skill <SKILL.md> --check-skill 형식을 쓴다.
• 선언은 Core 지원의 요구일 뿐이다. 사용자 구현 권한, 입력 lint, 완료 판정을 대신하지 않는다.

auto-budget/v1은 PLAN 검증 실행: 자동의 시작 상한 산정을 제공한다는 뜻이다(실행 기록 §1.5). 두 기능은 선택이므로 §2 표의 새 시작이나 기존 목표의 재개·검사·예산·발견 작업의 요구에 더하지 않는다. skill이 쓰려면 §8의 선언에 적는다.

9. run-rules/5#

run-rules/5를 지원하는 Core는 supported_rules에 run-rules/5, formats.review_gate에 review-gate/v1, features에 review-gate/v1을 함께 제공한다. default_rules는 run-rules/3 그대로이고, 새 규칙은 ha start --rules run-rules/5로만 고른다. /5는 run-rules/4의 규칙을 모두 지키므로 §6의 다섯 기능도 함께 제공한다.

/5 목표에서 실행자는 Spar가 쓴 review-gate/v1 파일을 ha note <goal> review --gate <file>로 기록하고, SPEC의 Assurance: 등급이 standard나 strict이면 기록된 마지막 gate가 지금 HEAD와 목표 문서를 덮어야 완료된다. 기록 내용, 거부, 이유는 실행 기록 §4.8이다. Core는 gate 파일의 공개 형식만 읽고 Spar를 실행하거나 리뷰어·모델을 부르지 않는다.

Seal 0.1.21은 core-requirements.json(§8)에 run-rules/5, review-gate/v1 기능, formats.review_gate의 review-gate/v1을 선언하고 ha start <goal> --rules run-rules/5 … --check-skill로 시작한다. 확인 도구도 새 시작에서 이 셋을 요구하고 시작 규칙으로 run-rules/5를 내며, 하나라도 없으면 기록 전에 거부한다. review-gate/v1 기능을 제공하는 Core는 formats.review_gate의 review-gate/v1도 제공하므로, 저장 규칙이 /5인 목표의 재개·검사·횟수 상한 변경은 §6의 다섯 기능과 review-gate/v1 기능을 요구한다. /1~/4 목표의 요구는 그대로다. /5를 지원하지 않는 Core는 그 목표를 66으로 거부하고 기록하지 않는다.

10. run-rules/6#

run-rules/6을 지원하는 Core는 supported_rules에 run-rules/6을 더한다. 새 형식이나 기능 식별자는 더하지 않으며, /5의 형식·기능과 §6의 다섯 기능을 그대로 지원한다. default_rules는 run-rules/3이고, 직접 시작할 때는 ha start --rules run-rules/6으로 고른다. 이 규칙은 /5에서 검토 범위의 시작, 완료 뒤 review note, 판정하지 않은 done 줄, 완료 뒤 시간의 네 판정만 바꾼다(실행 기록 §4.9).

Seal 0.1.26의 core-requirements.json은 rules를 ["run-rules/6"]으로 바꾸고 Seal 0.1.21의 형식·기능 요구를 유지한다. 새 목표는 ha start <goal> --rules run-rules/6 … --check-skill로 시작한다. 확인 도구의 --operation start도 이 선언을 요구하므로, /6이나 다른 필수 지원이 없으면 기록 없이 거부하고 이전 규칙으로 물러나지 않는다. 위 v0.1.8의 ha 0.1.8은 /6을 지원하지 않는다.

기존 목표의 재개·검사·횟수 상한 변경은 저장된 규칙을 따른다. 저장 규칙이 /6이면 그 규칙과 /5에서 요구한 형식·기능 지원이 필요하고, /1~/5 목표의 요구와 판정은 바뀌지 않는다. /6을 지원하지 않는 Core는 그 목표를 계산하거나 기록하지 않고 66으로 끝난다. 설치나 업데이트는 기존 목표를 새 규칙으로 이전하지 않는다.

11. run-rules/7#

run-rules/7을 지원하는 Core는 supported_rules에 run-rules/1~run-rules/6과 함께 run-rules/7을 싣는다. 새 형식이나 기능 식별자는 더하지 않고 /6의 형식·기능 지원을 유지한다. default_rules는 run-rules/3 그대로이며, 직접 시작할 때는 ha start --rules run-rules/7로 고른다. /7은 PLAN에 표시한 change 조건만 baseline을 요구하며, 기본 baseline 선택·최소량·상태와 보고·검사 동결 표시를 바꾼다(실행 기록 §4.10).

현재 Seal은 core-requirements.json의 rules로 ["run-rules/7"]을 요구하고 ha start <goal> --rules run-rules/7 … --check-skill로 시작한다. /7이나 다른 필수 지원이 없으면 기록 없이 거부하고 이전 규칙으로 물러나지 않는다. 위 v0.1.8 예시의 ha 0.1.8은 /7을 지원하지 않는다. 이미 시작한 목표는 저장된 규칙을 유지하며, 지원 목록을 늘려도 이전 기록을 변환하지 않는다.

/7로 시작한 목표의 재개·검사·횟수 상한 변경도 저장된 규칙과 /6의 형식·기능 요구를 따른다. /7을 지원하지 않는 Core는 그 목표를 계산하거나 기록하지 않고 66으로 끝난다.