사용 안내

한국어 · English

목표를 고치거나, 대화가 끊긴 뒤 이어 가거나, Seal이 묻는 것에 답하거나, 완료 보고를 읽을 때 찾아보는 문서입니다. 처음이라면 Jaekit 이해하기와 README의 첫 작업 맡기기를 먼저 읽으세요. 앞쪽 여섯 절은 목표 하나를 맡기고 끝까지 가는 순서대로 명령 보내기, 목표를 고치거나 이어 가기, Seal이 묻는 것과 검토 순서, 완료 보고 읽기, 남는 파일, 문제 해결을 다룹니다. 그 뒤의 절은 보고·검토 gate·비용·예산 같은 동작을 더 자세히 알고 싶을 때 읽습니다.

Jaekit이 왜 이렇게 동작하는지는 Jaekit 이해하기에, 설치·업데이트·제거는 설치 안내에 있습니다.

명령 보내기#

아래 명령은 터미널이 아니라 에이전트 대화에 보냅니다. <요청>은 하고 싶은 일로, <goal>은 Spec이 알려 준 목표 폴더 이름으로 바꿉니다.

Codex에서는 $를 입력하고 Jaekit에서 설치한 spec:spec 또는 seal:seal을 고른 뒤 요청을 이어 씁니다.

@Spec은 플러그인 언급입니다. 목표 문서만 쓰는 Spec의 지침을 명확히 선택하려면 위의 스킬 호출을 사용합니다. 플러그인 언급만으로 같은 지침이 선택된다는 보장이 없습니다.

에이전트도 Spec을 부를 수 있습니다. "이거 jaekit으로 해줘"처럼 Jaekit이나 목표 문서로 일하자고 할 때와, 검토 지적이 요구사항을 바꿔야만 풀릴 때입니다. 이때 Spec은 Proposed-By: agent 줄이 있는 Draft 문서나 amendments/ 아래의 수정안 문서를 쓰고 받아들일지 묻습니다. 평범한 구현 요청이나 버그 제보에는 부르지 않습니다. 누가 불렀든 Ready와 구현 시작은 사용자의 말로만 일어납니다.

목표를 고치거나 이어 가기#

보고를 읽고 답하거나 수정을 요청하면 같은 문서를 고칩니다. Spec은 목표와 범위, 완료 조건을 docs/specs/<goal>/SPEC.md에 바로 저장하고, 쓴 내용과 스스로 정한 결정·출처를 보고한 뒤 멈춥니다.

"구현까지 해줘"라고 함께 말해도 목표 문서만 씁니다. Spec이 제안한 결정은 사용자가 받아들이거나 그 목표의 구현을 요청하면 사용자의 결정이 됩니다.

같은 동작을 다루는 목표가 이미 있는데 작성 대상을 정하지 않았다면, Spec은 새 목표로 쓸지 기존 목표를 고칠지 먼저 묻습니다.

• Status: Draft: 결과를 바꾸는 결정이 남아 있으며 Spec이 질문합니다.
• Status: Ready: 문서가 준비됐다는 표시입니다. 그 자체로 구현을 시작하지 않습니다.
• Assurance:: 구현 담당이 받아야 하는 독립 검토의 정도입니다. light는 작은 수정, standard는 보통의 변경, strict는 공개 계약·저장 데이터·권한·구성 요소 사이 경계를 바꾸는 목표에 씁니다. Spec이 등급을 제안하고 이유를 보고합니다. 다른 등급을 원하면 "strict로 해줘"처럼 말합니다.

결과를 바꾸는 결정이 남지 않으면 Spec은 보고 끝에 지금 구현할지 따로 묻고 목표 경로와 등급을 함께 알립니다. 그 질문에 "응"이라고 답하면 구현이 시작됩니다. 답에 수정 요청을 함께 적으면("응, 그런데 AC-2는 빼줘") Spec이 먼저 문서를 고치고 다시 묻습니다. 구현 시작 명령도 계속 쓸 수 있습니다. Seal에는 시작 명령 대신 docs/specs/<goal> 구현해줘라고 말해도 됩니다. 작업 중에는 매 단계 승인하지 않고, 결과를 바꾸는 결정이나 사람이 직접 확인해야 하는 항목에 답합니다.

대화가 끊겼다면 같은 프로젝트 폴더의 새 대화에서 다음과 같이 보냅니다. Seal이 저장된 목표·계획·진행 기록과 현재 상태를 확인하고 남은 일을 이어 갑니다.

docs/specs/<goal> 이어서 해줘

Seal의 시작 전 확인과 검토 순서#

Seal은 시작하기 전에 미리 알 수 있는 결정을 한 번에 묻고, 작업 중에는 새로 생긴 질문만 묻습니다. 아래는 언제 무엇을 묻는지와, 검토 등급에 따라 독립 검토가 어떤 순서로 붙는지입니다.

시작 전에 묻는 것#

• 예산 질문은 한 번. 요청에 예산이 없으면 Seal이 PLAN에 검증 실행: 자동을 씁니다. 산정 값이 미리 승인한 상한 안이면 묻지 않고 시작하고, 넘으면 산정 값과 상한을 보이며 한 번 묻습니다.
  • 답한 숫자가 PLAN에 들어가고, 같은 PLAN에 같은 질문을 다시 하지 않습니다.
  • Seal은 ha.json을 쓰거나 고치지 않습니다.
• 시작 전 환경 점검. 검사가 브라우저·DB·컨테이너·외부 서비스를 쓰면 Seal이 PLAN의 ## 실행 환경에 적고, baseline을 기록하기 전과 재개 뒤 첫 검사 전에 ha doctor를 돌립니다. 사용 불가인 도구는 한 질문으로 모아 묻고, 권한이나 설정을 스스로 넓히지 않습니다.
• 시작 전 질문은 한 메시지로. Seal 0.1.23부터는 baseline을 기록하기 전에, 목표 문서·계획·프로젝트 지침·코드를 읽어 미리 알 수 있고 사용자의 말이 필요한 결정을 모아 한 메시지로 묻습니다. 물을 것이 없으면 아무것도 묻지 않고 바로 일합니다.
  • 보호 경로의 파일을 바꾸는 계획, 요청이 허락하지 않은 기존 시험의 변경, 목표 문서와 코드가 어긋나 보이는 곳, 쓸 수 없는 도구, 승인이 필요한 예산이 그런 예입니다.
  • 질문마다 추천을 앞에 둔 선택지와 답이 바꾸는 것을 밝힙니다.
  • 사용자 확인으로만 충족할 조건이 있으면 그 조건과 끝에 무엇을 확인해 달라고 할지도 같은 메시지에서 알립니다.
  • 계획이 새로 만들 시험·검사 파일은 처음부터 바꿀 수 있는 경로에 들어가므로 나중에 범위 확인을 묻지 않습니다.

작업 중에 묻는 것과 보고#

• 시작 뒤 질문은 생길 때. 검토에서 나온 requirement-question이나 라운드 상한처럼 미리 알 수 없던 질문은 생겼을 때 묻고, 같은 때 기다리는 질문은 한 메시지로 묻습니다. 끝에 필요한 사용자 확인도 결과가 생긴 뒤 한 메시지로 모아 묻습니다.
  • 권한 밖의 변경이나 검사를 약하게 하는 변경은 미리 물었다는 것만으로 확인되지 않습니다.
  • 미리 받은 답은 그 답이 허락한 변경을 commit한 뒤 그 답을 인용해 확인으로 기록하고, 그 변경을 다시 묻지 않습니다.
  • 확인한 내용이 그 뒤 다시 바뀌면 새 변경이라 다시 묻습니다.
• 다섯 줄 보고. 0.1.20 이상으로 시작한 목표의 PROGRESS.md는 ha report를 씁니다. ## 현재 맨 위에는 ha report의 도장이 그대로 들어가고, Seal이 시각을 손으로 적지 않습니다.
  • ## 완료 보고는 맨 위 다섯 줄(바뀐 것, 확인한 것, 직접 볼 것, 남은 한계, 다음 행동)을 먼저 읽고, 그 아래에서 완료 기록과 Seal의 판단 문장을 봅니다. 0.1.24 이상으로 시작해 완료한 목표에서는 판단 문장이 ## 검수 요약에 있습니다.
  • 한국어로 요청하면 --lang ko로 만듭니다.

검토 등급에 따른 순서#

SPEC의 Assurance: 줄에 따라 독립 검토 단계가 정해집니다. 검토의 방법은 Spar가, 시점과 지적 처리는 Seal이 정합니다.

누적 라운드는 목표의 base commit부터 마지막 head까지 전체를 다시 보는 candidate 라운드입니다. 독립 검토를 받는 목표에서 Seal은 이 라운드가 열린 defect·requirement-question 없이 끝난 뒤에만 ha done을 실행합니다.

• 프로젝트 지침(AGENTS.md 등)이 더 많은 검토를 요구하면 그쪽을 따르고 완료 보고에 적습니다.
• 줄이 없는 목표는 이전처럼 선택된 보증 정책을 따릅니다.
• 완료 뒤 원격 리뷰를 반영해 달라고 하면 reopen, 수정, 누적 라운드, 낡은 검사의 재기록, ha done 순으로 진행합니다.

완료 보고 읽기#

먼저 바뀐 결과와 무엇을 확인했는지 읽습니다. 완료 보고는 대화와 목표 폴더의 PROGRESS.md에 남습니다.

검수 요약. 0.1.24 이상으로 시작한 목표에서는 완료 기록 뒤 ## 현재 바로 다음의 ## 검수 요약이 검수를 시작하는 곳입니다. 맨 위 줄에 완료 기록, 보증 등급, 충족한 필수 조건 수, 검토 gate 결과, 이 변경이 하는 일, 먼저 볼 것이 있고, 그 아래에 바뀐 동작과 파일, 범위 밖이나 기존 것을 바꾼 곳, 근거, 누가 정했나, 직접 볼 것, 보지 않은 것, 자세히가 이 순서로 옵니다. 해당하는 것이 없는 항목에는 없음을 쓰고, 목표를 다시 열어 완료를 다시 기록하면 새 완료 기록 기준으로 다시 씁니다. 사용자의 언어로 쓰고, 기록은 무엇인지를 먼저 쓰며, 항목마다 짧게 쓰고 seq는 보조로만 붙입니다. 검증 출력과 지적 원문은 옮기지 않고 지적은 ID, 한 줄 요약, 끝만 적습니다. Seal의 판단은 이 절에만 있고, ## 완료 보고에는 ha report 출력과 이 절을 가리키는 한 줄이 있습니다. 완료한 목표는 ## 검수 요약부터 읽습니다. 멈춘 목표와 그 전 Seal로 시작한 목표는 지금처럼 ## 완료 보고를 읽습니다.

• 필수 완료 조건은 검사 기록 또는 필요한 사용자 확인으로 충족돼야 합니다.
• 선택 조건은 완료를 막지 않으며 보고에서 구분합니다.
• 자동 검사는 에이전트가 작성합니다.

결과에 따라 할 일#

ha status / ha done의 결과에 따라 다음에 할 일을 확인합니다. 숫자는 종료 코드입니다. ha status의 complete만으로는 완료가 아닙니다. 출력에 완료 기록이 나오기 전까지는 Seal이 ha done으로 완료를 기록합니다.

flowchart LR
    S["ha status / ha done"] -->|complete · 0| R{"완료 기록이 있나요?"}
    R -->|"아직 없음"| D["Seal이 ha done 실행"]
    R -->|"seq N"| C["결과 확인"]
    S -->|incomplete · 1| I["Seal이 계속 작업하도록 두기"]
    S -->|needs_user · 2| U["질문에 답하기"]
    S -->|blocked · 3| B["원인을 해소한 뒤<br/>docs/specs/#lt;goal#gt;<br/>이어서 해줘 보내기"]
    S -->|budget_exhausted · 4| E["예산 결정"]
    S -->|"오류 · 64 이상"| X["오류 메시지를 읽고<br/>문제 해결 보기"]
    classDef you fill:#EEF1FE,stroke:#4F6CF7,color:#1B2559
    classDef sealStep fill:#FFF3E3,stroke:#C9761F,color:#4A2A06
    classDef record fill:#F1F3F5,stroke:#596579,color:#1F2328
    class S record
    class C,U,B,E,R,X you
    class I,D sealStep

64 이상은 작업 상태가 아니라 오류입니다. 64는 사용법 오류, 65는 시작하지 않은 목표나 끊긴 기록 같은 거절, 66은 Core가 지원하지 않는 규칙 버전, 70은 내부 오류입니다. 메시지를 읽고 문제 해결을 봅니다.

완료 근거와 재작업#

가정, 바뀐 검사, 남은 한계와 실제 결과를 함께 확인합니다. 완료의 근거는 ha done이 남긴 완료 기록입니다.

보증 수준 local은 그 컴퓨터에서 얻은 근거라는 뜻입니다. 같은 사용자 권한의 에이전트가 검사와 기록을 바꿀 수 있으므로 독립된 제3자의 검증을 뜻하지 않습니다.

자세한 확인 순서는 운영 안내에 있습니다.

빠진 것이 있으면 무엇을 고칠지 말합니다. Seal이 재작업 요청을 기록하고 다시 진행합니다. 목표 문서부터 바꿔야 한다면 Spec으로 고친 뒤, 별도로 계속하라고 요청합니다.

현재 Seal의 기본 결과는 로컬 변경과 commit(변경 이력을 저장한 단위)까지입니다. push·PR은 사용자가 직접 하거나 일반 에이전트에 별도로 요청할 수 있습니다. Jaekit은 독립된 검증 환경이나 무인 운영 기능을 제공하지 않습니다.

저장되는 파일#

목표와 기록은 docs/specs/<goal>/에서 확인합니다.

• Git 추적: 프로젝트 정책에 따릅니다. 추적하는 프로젝트에서는 commit합니다. 비공개·ignore 정책이면 로컬에 보관하고 강제로 Git에 추가하지 않습니다.
• 공개 전송 전: commit은 로컬 이력 저장이며 공개 전송은 별도입니다. 기록에는 사용자 발화와 작업 경로가 들어갈 수 있으므로 공개 저장소에 보내기 전에 내용을 확인합니다.
• Jaekit의 정책: 이 저장소 자체의 비공개 docs/ 정책은 다른 프로젝트의 필수 설정이 아닙니다.
• 출력 원문: 검사 출력은 로컬에만 있으며 Git이 추적하지 않는 .git/ha/에 남습니다. .gitignore에 더할 것은 없습니다.
• Linked worktree: Git 이력을 공유하는 별도 작업 폴더에서는 git rev-parse --absolute-git-dir이 알려 주는 Git 폴더 아래 ha/에 출력이 있습니다.
• 출력 확인: 터미널에서 ha log <goal> <seq>를 실행합니다. 여기서 <goal>은 목표 경로, <seq>는 보고에 나온 기록 번호입니다.
• 실행 시간: ha timing <goal>로 어느 검사가 오래 걸렸는지, 시간 제한에 얼마나 가까웠는지 봅니다. 시간 보기(capability run-timing/v1)를 지원하는 Core가 필요하며 측정 세부 사항은 아래에 있습니다.
• 판단 이력: 지원 정보 decision-history/v1이 있으면 Seal이 선택 기능인 판단 이력에 요약과 근거, 정정 관계를 남길 수 있습니다. 현재 판단은 ha history <goal>, 한 사건의 근거와 앞뒤 관계는 ha history <goal> show <사건 ID>로 읽습니다.

문제 해결#

판단 이유와 재개 규칙은 운영 안내의 사용자 확인 및 막힘·예산 절에서 자세히 설명합니다.

사람용 보고와 도구 점검#

ha report <goal>은 목표의 상태를 다섯 줄로 요약합니다. 기본은 영어이고 --lang ko를 붙이면 한국어로 나옵니다. ha status와 같은 계산을 읽기만 하며 기록을 바꾸지 않습니다.

base commit이 없는 얕은 clone처럼 Git이 base와 HEAD를 비교할 수 없으면 다섯 줄만 보이고 70으로 끝납니다. 이때 다음 행동이 base를 받는 방법(예: git fetch --unshallow)을 알립니다.

요약 뒤에는 PROGRESS.md의 ## 현재에 옮겨 적을 도장(기록 head의 seq·hash, 기록 시각, 상태), 조건별 근거, 완료 범위, 충족되지 않은 조건의 원문 위치(ha log <goal> <seq>)가 이어집니다. 합성 예시:

바뀐 것: base 3c1f0a9e7b25 이후 실행 묶음 문서 밖에서 파일 2개, commit 2개
확인한 것: 필수 조건 2개 중 2개 충족(검사 기록 2개, 사용자 확인 0개); change 조건 1개 중 1개에 신선한 baseline
직접 볼 것: 없음
남은 한계: 보증 수준 local; 검사 작성자: 실행자
다음 행동: 없음; 완료 기록 seq 5이 유효하고 남은 할 일이 없음

검사에 필요한 도구를 미리 확인하려면 PLAN에 ## 실행 환경 절을 두고 한 줄에 도구 하나씩 - <이름>: `<점검 명령>` 형식으로 씁니다.

## 실행 환경
- 브라우저: `node scripts/probe-browser.mjs`
- 셸: `sh tests/env/plain.sh`

ha doctor <goal>은 이 점검 명령을 차례로 60초 제한으로 실행하고 도구마다 사용 가능 또는 사용 불가 (<이유>)를 보입니다. 사용 불가면 그 출력의 끝부분이 아래에 나옵니다. 시작 전에도 쓸 수 있고 기록·실행 횟수에는 아무것도 남지 않습니다. 형식이 틀린 줄은 파일과 줄을 알리고 아무 점검도 실행하지 않습니다. 이 절은 판정에 쓰이지 않습니다.

검토 gate (run-rules/5)#

v0.1.7부터 Seal(0.1.21 이상)은 새 목표를 ha start --rules run-rules/5로 시작합니다. run-rules/5는 run-rules/4의 자율 처리를 모두 그대로 두고, SPEC의 등급이 standard나 strict인 목표에 독립 검토의 기록을 완료 조건으로 더합니다. 그래서 run-rules/5로 시작한 standard·strict 목표는 기록된 Spar gate가 있어야 완료됩니다. light 목표, Assurance: 줄이 없는 목표, run-rules/4 이하로 시작한 목표에는 Spar가 필요 없습니다. 검토 없이 끝내려면 등급을 light로 낮추는 목표 문서 수정을 사용자가 정합니다(아래 목록).

설치된 ha가 run-rules/5나 Seal이 요구하는 다른 지원을 모르면, Seal은 기록 없이 멈추고 이전 규칙으로 물러나지 않습니다. 할 일은 그 지원을 갖춘 ha를 설치하는 것입니다.

• 누적 라운드가 열린 지적 없이 끝나면 Seal이 그 series의 라운드로 spar gate를 HEAD에 대해 만들고, ha note <goal> review --gate <file>로 gate 파일을 기록한 다음 ha done을 실행합니다. 기록에는 파일 digest와 판정에 필요한 요약만 남고 지적 원문은 남지 않습니다.
• gate가 없으면 review_missing, 검토 뒤 commit이 더 있으면 review_head_stale, 검토 뒤 목표 문서가 바뀌었거나 라운드가 목표 문서를 모두 받지 않았으면 review_docs_stale이 나오고 완료가 기록되지 않습니다. gate가 blocked·degraded이거나 열린 defect·requirement-question이 있을 때, code 라운드가 없을 때, strict인데 plan 라운드가 없을 때도 각자의 이유가 나옵니다. 사용자 확인이나 다른 note는 gate를 대신하지 않습니다.
• Spar를 쓸 수 없어 검토 없이 끝내려면, 사용자가 SPEC을 Assurance: light로 낮추는 수정을 정합니다. 그 뒤 confirm spec과 신선한 검사로 gate 없이 완료됩니다.
• light이거나 등급 줄이 없는 목표, 그리고 run-rules/1~run-rules/4로 시작한 목표는 지금처럼 gate 없이 판정합니다.

Seal 0.1.26은 위 시작 규칙을 대신해 새 목표를 ha start --rules run-rules/6 … --check-skill로 시작합니다. run-rules/6을 지원하는 Core가 필요하며, ha 0.1.8은 이를 지원하지 않습니다. 지원이 없으면 기록 없이 멈추고 이전 규칙으로 물러나지 않습니다. /6은 /5의 규칙 가운데 다음 네 판정만 바꿉니다.

• standard·strict 목표의 마지막 candidate 라운드(dry run 제외)는 시작 기록의 base_commit부터 검토해야 합니다. 다르면 review_base_mismatch가 gate seq와 두 base를 보이고 완료를 막습니다. fixes 라운드만 있어도 같은 이유가 나옵니다. 시작 base부터의 candidate 뒤에 fixes가 이어져도 되고, 그 사슬은 Spar가 확인합니다. reopen도 시작 base를 옮기지 않습니다.
• light이거나 등급 줄이 없는 목표는 완료 뒤 review note를 남겨도 다른 조건이 유효하면 완료 기록이 유지됩니다. standard·strict는 이전처럼 그 기록이 무효가 되어 새 gate로 다시 판정합니다.
• record_head가 앞선 줄의 hash이고 그 줄과 done 줄 사이에 발견 줄(run-finding/v1)만 있거나 아무 줄도 없으면, 그 done 줄은 판정한 줄입니다. record_head가 가리키는 줄 자체는 발견 줄이어도 됩니다. 모든 done 줄은 전체 기록에서 먼저 판정하므로, record_head가 판정하지 않은 줄을 가리켜도 판정한 줄이 될 수 있습니다. 그런 다음 판정하지 않은 done 줄은 완료 여부와 관계없이 상태 계산에서 없는 것으로 취급합니다. 완료 기록과 그 설명, 최신 done 줄, 예산 창, 경과 시간, 완료 뒤 구간, 예산 변경 거부가 모두 이에 따르며 상태·보고·비용·예산 변경은 같은 뷰를 씁니다. 앞의 기록도 다른 유효성 조건을 만족해야 하며, 판정했지만 다른 이유로 무효인 줄에서는 이전처럼 멈춥니다.
• 완료 done부터 다음 검사·baseline의 시작이나 완료가 아닌 done까지의 시간을 예산 경과에서 뺍니다. 둘 다 없으면 창의 마지막 예산 기록까지이고, 그 사이의 note와 발견 줄은 구간을 끝내지 않습니다. post_completion_seconds가 신고 대기·실행 구간과 겹치지 않는 추가 공제 초를 보이며, 상태·보고·비용은 같은 경과를 씁니다. 실행 횟수와 한도는 그대로이고, 완료 뒤 코드 재작업은 reopen으로 새 창을 엽니다.

run-rules/1~run-rules/5로 시작한 목표는 기존 판정을 유지하며 자동 이전하지 않습니다. 구간과 출력의 정확한 정의는 실행 기록 계약에 있습니다.

baseline 선택과 검사 동결 (run-rules/7)#

현재 Seal은 새 목표를 run-rules/7로 시작합니다. 지원하지 않는 Core에서는 기록 없이 멈추며 이전 규칙으로 물러나지 않습니다. 직접 실행하는 ha start의 기본 규칙은 run-rules/3 그대로이고, 이미 /1~/6으로 시작한 목표의 판정·출력·기록은 바뀌지 않습니다.

PLAN 조건표의 선택 baseline 열에 요구를 적은 change 조건만 baseline을 요구합니다. 빈 칸·—나 열이 없으면 요구하지 않습니다. 버그 수정·회귀·"X가 일어나지 않는다"·base에서 일부가 이미 충족된 조건처럼 거짓 통과 위험이 있는 조건을 고르고, 이유를 plan 라운드 전에 REVIEW에 적습니다. 표시하지 않은 change 조건도 검사 경로와 구조화 결과 계약은 필요하지만, base에도 있는 진입점에 묶을 필요 없이 새 함수의 시험에 연결할 수 있습니다.

필수 최소량은 표시한 필수 change × 2 + 표시하지 않은 필수 change + 필수 maintain입니다. manual은 0회입니다. 표시한 change 1개, 표시하지 않은 change 4개, maintain 3개가 모두 필수라면 최소 9회이고, 자동 상한은 max(50, ⌈9 × 1.5⌉) = 50입니다. 시작 전에는 ha estimate <goal> --rules run-rules/7로 이 값을 봅니다. 시작한 목표는 저장된 규칙을 쓰며 다른 --rules를 주면 거절합니다.

대상 없는 ha check <goal> --baseline은 표시한 change 조건만 고릅니다(표시한 선택 조건도 포함). 표시가 하나도 없으면 기록 없이 거절합니다. 표시하지 않은 조건을 직접 지정해 baseline을 실행할 수도 있고, 실제 실행은 예산에 셉니다. 그 baseline의 신선한 불리한 결과도 판정에 남습니다. 표시한 조건의 baseline은 검사 파일이 정해진 뒤 한 번 기록하도록 계획합니다. 검사 수정마다 기록하는 습관을 줄이자는 안내이며, 이미 낡은 근거를 신선하게 만드는 예외가 아닙니다.

/7에서 "baseline 전" 질문 모으기·ha doctor·strict의 plan 라운드는 baseline이 없는 목표에서도 현재 검사나 baseline 어느 쪽이든 첫 ha check 기록 전에 마칩니다. 시작 전에 알 수 있는 질문을 모으되, 물을 것이 없으면 바로 일합니다.

• 입력 실패인 대상 파일 없음, 손상된 입력, 시작하지 못하는 도구, 신호 종료는 통과가 아니다.
• baseline을 요구하지 않는 검사(maintain, EX-n, task 명령, 표시하지 않은 change 조건)는 입력 실패를 위반, 오류, 판정 불가 중 하나로 세어도 그것만으로 검사의 결함이 아니다. 위반으로 기록된 실패는 입력이 달라질 때까지 남는다.
• baseline을 요구하는 change 조건의 전용 생산자는 입력 실패를 위반으로 보고하지 않는다. 결과 계약이 허용하는 경우(예: missing: violation)는 예외이며 그 선택은 plan 라운드 전에, plan이 없으면 어떤 검토 라운드보다도 전에 REVIEW.md에 적는다.

baseline을 요구하는지는 규칙에 따라 읽습니다. run-rules/6까지는 모든 change 조건이 요구하고 /7은 표시한 조건만 요구합니다. 러너 어댑터는 입력 실패를 스스로 분류하며, 결과 계약의 분류와 입력 실패 표는 바뀌지 않습니다.

검사 동결 시점은 기록된 마지막 gate의 dry run이 아닌 라운드 중 strict의 첫 plan 라운드 또는 standard의 첫 candidate 라운드입니다. 조건표에서 검사 경로를 적은 모든 행의 경로에 있는 선언·생산자·시험·도우미·설정이 대상입니다. Seal은 동결 라운드 바로 뒤 ha note <goal> review --gate <file>로 gate와 그때 조건표의 검사 경로를 기록합니다. 동결 라운드에서 끝난 gate note가 없으면 뺀 검사 경로를 관측할 수 없고, 상태와 보고에 동결 때의 조건표가 기록되지 않음이 나옵니다.

동결 뒤 검사 파일을 고치면 commit하고 ha note <goal> check-change checks:<path> --reason "<지적 ID, 또는 조건과 이유>"로 까닭을 남깁니다. 검토 지적을 고친 변경이면 그 지적 ID를 씁니다. 까닭은 지금 blob에 묶이므로 파일을 다시 바꾸면 그 변경의 까닭도 다시 남깁니다. 다음 코드 검토 라운드에 바뀐 검사와 까닭을 함께 줍니다. 동결 전 변경에는 이 까닭이 필요 없고, 동결 뒤에도 검사 결함을 고칠 수 있습니다. 동결 표시는 자체로 완료를 막거나 plan-delta를 요구하지 않습니다.

ha status는 change 조건마다 baseline_required와 사람용 baseline required 줄을 보입니다. ha report의 확인한 것은 모든 change 조건 중 baseline을 요구한 수와 그중 신선한 baseline 수를 나눠 보입니다. 직접 볼 것에서 시작 뒤 뺀 baseline 표시, 동결 뒤 바뀐 검사 파일과 까닭, 까닭 없는 변경을 읽습니다. 뺀 경로에는 비교에 쓴 review note seq가 붙습니다. light나 기록된 gate가 없는 목표에는 동결 표시가 없고, 검수 요약의 ### 보지 않은 것에는 baseline 없이 충족한 change 조건을 적습니다. 실행 기록 계약 §4.10에 정확한 필드와 표시가 있습니다.

목표 하나의 비용 보기#

ha cost <goal>은 목표 하나가 검증과 검토에 들인 비용을 한 화면에 모읍니다. 기록을 읽기만 하고 아무것도 쓰지 않으며, 현재 시각을 읽지 않고 모델을 부르지 않습니다. Spar 검토 기록은 --series로 그 목표의 series 폴더를 가리킬 때만 읽습니다. 위치를 짐작하지 않으므로 series가 여럿이면 --series를 여러 번 씁니다.

ha cost docs/specs/<goal> --series docs/reviews/<goal>

• 종류와 크기: 등급, 규칙 버전, 필수·선택 조건 수, base 이후 바뀐 파일과 commit 수(ha report의 Changed와 같음), 유효한 완료 기록.
• 검증: 실행 수와 시간, 조건별 실행 수, 다시 기록한 실행마다 앞 기록과 달라진 입력(코드, 목표 문서, 검증 명령, 덧씌운 검사 파일). 달라진 입력이 없으면 앞 기록의 결과를 보입니다. 예산 창의 값은 ha status와 같습니다.
• 질문과 대기: 신고한 대기마다 물은 결정과 길이, Spar의 requirement-question과 그 답, 상한 연장, 리뷰어 waiver. 출처별로 세고 나열만 합니다. 범위·권한 결정인지 불필요한 재확인인지는 목록을 읽는 사람이 판단합니다.
• 검토 라운드와 지적: 단계별 라운드 수(상한에 센 라운드와 재실행), 리뷰어 시간, 분류·위치별 지적과 처리, fixes 라운드가 더한 줄(gate의 growth). --series가 없으면 주지 않았다고 보이고 0으로 보이지 않습니다.
• 토큰: 어느 기록에도 없어 "기록 없음"으로 보입니다.

--format json은 같은 값을 cost/v1 문서로 보이고, --lang ko는 표지와 문장만 바꿉니다. 형식과 각 값의 출처는 실행 기록 계약 §1.7에 있습니다.

견줄 때. 요약은 숫자만 보이고 다른 목표와 비교하거나 나아졌다고 말하지 않습니다. 목표끼리 견줄 때는 같은 등급, 비슷한 크기(조건 수, 바뀐 파일과 commit 수)의 목표를 나란히 놓으세요. 과정을 바꾸기 전과 뒤의 목표 몇 개를 견준 차이에는 목표마다 다른 내용과 우연이 섞여 있어, 그 차이는 바꾼 과정의 인과 효과가 아닙니다.

자동 예산#

PLAN의 ## 예산에 횟수를 숫자 대신 - 검증 실행: 자동으로 쓰면 ha start가 상한을 정합니다. 상한은 max(50, ⌈필수 최소량 × 1.5⌉)입니다. run-rules/6까지를 쓰는 필수 change가 34개인 목표는 최소량 68회, 상한 102회입니다. 경과 시간은 지금처럼 직접 씁니다. 숫자를 쓴 PLAN은 지금과 같습니다.

산정한 상한이 미리 승인한 상한 이하이면 묻지 않고 시작합니다. 미리 승인한 상한은 사용자 설정 폴더의 ha.json에 한 번 적어 둡니다. 폴더는 ~/.config/jaekit/이고, XDG_CONFIG_HOME이 설정되어 있으면 $XDG_CONFIG_HOME/jaekit/입니다. 파일이 없으면 상한은 50회입니다. 저장소 안의 파일은 이 상한을 정하지 못합니다. 이를 확인하려고 파일이 있으면 git worktree list -z로 작업 트리를 읽으므로 Git 2.36 이상이 필요합니다.

folder="${XDG_CONFIG_HOME:-$HOME/.config}/jaekit"
mkdir -p "$folder"
printf '{"preapproved_runs": 120}\n' > "$folder/ha.json"

홈은 환경 변수 HOME이 있으면 그 값이고, 없으면 Windows에서는 USERPROFILE입니다. Windows PowerShell에서는 같은 순서로 폴더를 골라 씁니다.

$folder = if ($env:XDG_CONFIG_HOME) { "$env:XDG_CONFIG_HOME\jaekit" } elseif ($env:HOME) { "$env:HOME\.config\jaekit" } else { "$env:USERPROFILE\.config\jaekit" }
New-Item -ItemType Directory -Force $folder | Out-Null
Set-Content -Path "$folder\ha.json" -Value '{"preapproved_runs": 120}'

ha estimate docs/specs/example이 시작 전에 같은 산정 값과 승인이 필요한지를 보입니다. 산정 값이 상한을 넘으면 ha start는 기록을 남기지 않고 다음처럼 멈춥니다.

ha: auto budget 102 runs (minimum 68 × 1.5, at least 50) exceeds the pre-approved limit 50 from default; the user's approval is needed: write the approved number in PLAN `검증 실행`, or have the user raise preapproved_runs in ~/.config/jaekit/ha.json

이때 사용자가 그 횟수를 승인하면 PLAN에 숫자로 적거나 ha.json의 preapproved_runs를 올립니다. 파일 형식이 틀렸거나 읽을 수 없으면 ha: pre-approved run limit: <경로>: <이유>로 멈추며 50회로 대신하지 않습니다. 이 상한은 시작할 때만 쓰입니다. 시작 뒤의 증액·재개 규칙은 그대로입니다. 정확한 규칙은 실행 기록 계약에 있습니다.

자율 처리 (run-rules/4)#

Seal 0.1.16부터 Core가 run-rules/4와 그 다섯 기능을 지원하면 새 목표를 ha start --rules run-rules/4로 시작합니다. Core의 기본 규칙은 그대로 run-rules/3이고, 이미 시작한 목표는 시작할 때의 규칙으로 계속 계산합니다. 새 규칙에서 Seal은 이미 받은 권한 안의 일을 다시 묻지 않습니다.

• 요청이 범위 안의 시험 변경을 허용하면 --test-authority로 그 해석을 남깁니다. 기존 시험을 고치거나 옮길 때는 ha note <goal> test-change로 어느 조건을 어떻게 확인하는지 남기고, 그러면 사용자 확인이 필요 없습니다. 약화하는 변경과 범위 밖의 변경은 지금처럼 확인을 묻습니다.
• 질문하고 답을 기다리는 동안은 ha note <goal> wait로 신고하고, 답 없이 계속하면 resume을 남깁니다. 신고한 대기만 예산의 경과 시간에서 빠집니다.
• 실행 상한을 미리 허락하면 ha budget <goal> --preapprove로 기록되고, 그 안에서는 Seal이 이유만으로 상한을 올립니다.
• 도구 설치처럼 실행 조건을 고쳐 오류 한도를 넘은 검사를 다시 볼 수 있으면 recover를 남깁니다. 조건·입력마다 두 번이며, 더 허락하려면 allow-recovery를 씁니다. 이전 실패는 그대로 남습니다.
• 오래 걸리는 검사는 PLAN의 ## 시간 제한 절에 2시간까지 제한을 정합니다. 이전 실행이 제한에 걸렸거나 가까웠으면 실행 전에 안내가 나옵니다.

검증 보고 형식#

Seal 0.1.10부터 도입된 보고 형식은 기존 검토·보고에서 다음 네 가지를 구분합니다.

• 기대 결과의 근거.
• 관측 경계.
• 시험 방법·대체 환경.
• 미확인 범위.

조건 그룹이 같은 설명을 참조할 수 있으며, 실제 수행과 예정은 다릅니다. 현재 배포판 v0.1.8의 Seal 0.1.23에도 포함되며 기존 목표 형식은 유지합니다.

자세한 보고 경계를 참고하세요.

배포판과 규칙#

현재 배포판 v0.1.8은 ha 0.1.8·spar 0.1.8·spec 0.1.13·seal 0.1.23·spar 플러그인 0.1.4 조합입니다. 기본 규칙은 /3이고, Seal은 0.1.16부터 새 목표를 run-rules/4로, 0.1.21부터 run-rules/5로 시작합니다. 실행 전 거부·횟수 추정, /3 결과 분류와 예산 정책이 적용됩니다. 기존 목표는 저장된 규칙을 유지합니다. 버전별 적용 범위를 확인합니다.

규칙(run-rules/N)은 ha가 목표의 기록을 계산하는 방식의 판입니다. 목표는 시작할 때의 규칙으로 끝까지 계산되므로, 새 ha가 나와도 진행 중인 목표의 의미는 바뀌지 않습니다.

Seal skill 본문은 약 4,600단어에서 2,200단어 이하로 줄었습니다. Seal 0.1.23은 시작 전 질문 규칙을 더하면서 상한을 2,300단어로 올렸습니다. 이전 Seal로 시작한 목표의 형식은 그런 목표를 이어 갈 때만 읽는 참고 문서(references/earlier-goals.md)로 옮겼고, 그 목표의 기록과 문서는 바꾸지 않습니다.