Contract: Execution bundle

한국어 · English

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

This document is the canonical definition of the execution bundle's files and fields. The execution bundle is Seal's output. The goal documents the execution bundle reads (Spec's output) are in goal-docs.md. The format of the run record (runs.jsonl) is in run-record.md.

The execution bundle holds one goal's changing plan and progress. It has one purpose: another agent, without the earlier conversation, must be able to read only this bundle and finish the work from what remains. Adding more documents is not the purpose.

1. Location and ownership#

docs/specs/<goal>/
  SPEC.md        목표 문서 진입점: 조건 ID, (선택) 작업 분해 제안 (Spec이 작성, 사용자 소유)
  <보조 문서>.md SPEC.md가 링크한 목표 문서 (Spec, 사용자 소유)
  amendments/    수정안 문서 (Spec이 작성, 사용자가 정하기 전까지 목표 밖, goal-docs.md §6.6)
  PLAN.md        조건표, 범위, task 목록, 예산
  REVIEW.md      실행 전 검토
  tasks/T001.md  task별 상세 (작은 목표는 PLAN.md 안에 합쳐도 된다)
  PROGRESS.md    현재 상태, task 상태, 타임라인, 계획 변경, 막힘, 완료 보고
  runs.jsonl     실행 기록 (`ha`만 덧붙인다)

Other files in the goal directory (verification scripts, fixtures and so on) are treated as code, not as bundle documents. They enter the freshness and scope checks as they are (run-record.md §2). Even when a file that affects verification sits in the goal directory, a change to it makes earlier results stale. Whether another goal's execution bundle files under the same parent enter the code state depends on the rules version (run-record.md §4.6). As an exception, the amendment documents in amendments/ are neither goal documents nor code. Even when SPEC.md links them, they are not part of the goal document set, and both this goal's and those of other goals under the same parent are left out of the code state whatever the rules version (goal-docs.md §6.6, run-record.md §2).

Every file is plain Markdown. Only the parts ha lint must read follow the table formats below. Other prose is free.

2. PLAN.md#

2.1 Condition table (## 조건표)#

The rules are as follows (ha lint checks them).

1. Every AC-n of the goal documents appears in the condition table exactly once. A missing ID, and an AC ID that is not in the goal documents, are errors. A condition without an ID in the goal documents is an error, and the executor tells the user instead of editing the goal documents.
2. Every condition has at least one task. Every task rests on a condition or on another task's prerequisite output. An orphan task is an error.
3. A change condition has a verification command and check paths. A maintain condition has a verification command. A manual condition has a reason.
4. To use the whole existing test suite as a preservation condition, add one maintain condition. When the goal documents have no such condition, add it as EX-n. EX-n is the executor's extra check, so it does not block the status. Behavior that must be preserved must be a required condition in the goal documents (goal-docs.md §2.3). When there is no such condition but you see behavior that must not break, ask the user in the pre-execution review (중요한 미결정, important open decisions, in §4).

An optional baseline column may be added at the end; the five-column table remains valid. In run-rules/7, 요구 in the baseline column means that the change condition requires a baseline. An empty cell, —, or no column means no baseline is required. Check paths and the structured result contract remain required for every change condition, marked or not.

| ID | 종류 | 검증 명령 | 검사 경로 | Task | baseline |
| --- | --- | --- | --- | --- | --- |
| AC-1 | change | `python3 checks/greeting.py` | checks/greeting.py | T001 | 요구 |
| AC-2 | change | `python3 checks/format.py` | checks/format.py | T001 | — |

요구 on a row other than change, or a value other than 요구, — or empty, is a baseline_marker lint problem. The column and lint apply regardless of rule version, but run-rules/1 through run-rules/6 ignore marks for judgment and keep their baseline requirement, default selection, minimum and output. /7 judges by the current PLAN's marks. The report in Run record §4.10 shows marks removed since the start.

2.1.1 Result contract (## 결과 계약)#

Link run-rules/3 change checks to the structured result contract. PLAN holds an ID | 선언 경로 table that maps each such change condition to a repository-relative JSON declaration path. Include the declaration and the producer and configuration files in the condition table's check paths as well. A plain nonzero exit alone is not an expected failure, and ordinary maintain, manual and task checks are not forced over to this contract. Existing /1 and /2 goals keep their earlier result semantics.

The declaration path may also point to a runner adapter declaration (check-adapter/v1) instead of a producer declaration (check-declaration/v1). Then each target is linked to one test that already exists, and the verification command is the runner command itself that uses go test -json … or JUnit XML. There are no producer files, so the check paths hold the declaration and the linked test files. The format, the output location ({HA_JUNIT_XML}) and the judgment are in §5 of change check results. Use it only when the actual executable's capabilities list check-adapter/v1.

2.1.2 Check inputs and observation#

These rules apply to checks written or changed from Seal 0.1.14 on. Which Seal version started the goal does not matter. They never require rewriting or converting an existing goal's checks, records, PROGRESS or REVIEW for this rule alone. They add no user confirmation, approval or question step. The executor applies the rules and judges whether to fix existing checks.

• What a check reads. Every check in the condition table (change, maintain, EX-n, task commands), and the producer, configuration and helper files its command runs or reads, judge only from the tree being checked and the external inputs the condition names. Do not put the goal's start or base commit, or any other fixed commit, into a check. The same goes for reading the base from the start record or Core output and using it. Do not judge by reading other commits, refs or objects of the repository. Examples are a diff against a past commit, a merge-base, a remote-tracking branch, a relative ref such as HEAD~n, a log range and another worktree. The general property is "a full clone and a history-less clone with the same tree give the same verdict". The history of a synthetic repository the check builds itself is not covered.
• Maintain conditions. A maintain condition observes the property the goal documents require (content, output, format, behavior) in the tree being checked. Confirming "no change since the base commit" in check code is not an observation of that property. When a path must not change at all, leave it outside 바꿀 수 있는 경로 (paths that may change). Core then reports changes committed since the base as out_of_scope, and only the user resolves them. A check can look at the property the file must keep, or compare the file with expected content written in a tracked check file.
• Change conditions and the baseline. A violation on the base commit is observed only by Core's baseline run. The baseline runs on a temporary worktree of the base commit with HEAD's check paths overlaid. Check code never imitates the baseline by checking out, reading or comparing the base commit. The same check observes the required property in the tree it runs on, so it gives a violation on the base and a pass after the change.
• When history itself is the condition. When a condition is about history or refs, such as a tag's type or a commit message format, the check reads only the range and refs the condition names. When that history is missing or cannot be read, the result is neither a violation nor a pass but an error or unobserved. A change check that produces a structured result writes that state in its result report. maintain, EX-n and task commands are recorded by exit code only, and every nonzero exit is recorded as a failure. So before ha check, the executor confirms that the named range and refs can be read. When they cannot, record no result. For a required condition or task, hold that condition and completion and continue independent work; when that is all the work left, record a block with cause environment. An EX-n check stays unobserved and does not block completion. This distinction is the same as the distinction in §4 among unobserved, environment error, skip and actual violation. Write in the pre-execution review why such a check is needed and the range it reads.
• Declared boundaries. A component the goal documents point to or intend to change may have declared its own scope or trust boundary. Examples are pinning to a specific version or release, preserving past verdicts, isolating imports and limited inputs. That declaration is current behavior, so keep it unless the goal documents explicitly say to change it. When the goal documents can be satisfied both by a reading that widens the component and by a reading that adds a separate component, choose the reading that keeps the declaration, leave it in the pre-execution review as an explicit assumption and repeat it in the report. Do not ask the user anew. When the goal documents explicitly say to change the component, keep new code inside the declared boundary. For example, a new import also goes through the same import boundary. When no reading satisfies both the declaration and the goal documents, follow the existing document-conflict rule.

2.1.3 Final candidate evidence#

These are planning rules, not a fixed order. The executor chooses the method and the order.

• While exploring, use narrow checks that fit what changed. Their results are working information, not evidence.
• Write in PLAN that the expensive full verification that completion needs is obtained once with ha check on the final candidate. Running the full verification for development and then again for the record on the same candidate is a cost to avoid.
• ha check runs each condition's command separately. When several required conditions need the same full regression, it is recommended that one condition owns that regression and the other conditions observe their own properties. This is a recommendation, not a required procedure. It only assigns the shared run; it does not drop or weaken a condition, and each condition needs its own recorded result.

2.2 Scope (## 범위)#

• 바꿀 수 있는 경로 (paths that may change): a list of globs. It is the basis of the scope check. Derive it from the SPEC's scope and non-goals, and write the SPEC section it rests on. Seal 0.1.23 or later puts the test and check files the plan will create, and their helper files, here from the start, so adding those files raises no scope question. Do not include paths the goal documents say must not change.
• 테스트 경로 (test paths): a list of globs treated as test definitions. It is the basis of the check for changes to existing test definitions. When it is empty, ha's defaults (tests/**, **/*_test.*, **/test_*.*, **/*.test.*, **/*.spec.*) are used.
• 유지할 동작 (behavior to keep): what must be kept, from the SPEC's non-goals and current behavior
• 다른 목표 실행 묶음 (other goals' execution bundles): optional. Add it only when this goal's checks read another goal's execution bundle files (PLAN.md, REVIEW.md, PROGRESS.md, runs.jsonl, tasks/) as input. The value is the single code span 검사 입력 (check input). Example: - 다른 목표 실행 묶음: `검사 입력` (이전 목표의 PROGRESS.md를 검사한다)
  • When it is declared, other goals' execution bundle files enter this goal's code state under run-rules/2 and run-rules/3 too. A change to those files alone makes earlier results stale, and changes to them also enter the scope check (run-record.md §4.6).
  • ha reads this declaration from PLAN as it is when computing the status and when recording. Added during the work, it applies from then on. Removed, it leaves other goals' execution bundles out again, and results that were stale because of them can become fresh again. Record adding or removing it as a plan change.
  • The item must start with exactly 다른 목표 실행 묶음:. When other words follow this name or the colon is missing, or the value is different or has no code span, it is the lint error other_bundles_invalid.
  • In a run-rules/1 goal, other goals' execution bundles are code already, so the result does not change.

Widening 바꿀 수 있는 경로 is a plan change. When the widened scope conflicts with the SPEC's non-goals or scope, however, it needs the user's decision.

2.3 Task list (## Task)#

A cycle in the dependencies is an error.

2.4 Budget (## 예산)#

• 검증 실행 (verification runs): the limit on the number of ha check runs within the budget window (baselines included). When the value is written exactly as 자동 (automatic), as in 검증 실행: 자동, ha start sets it to max(50, ⌈필수 최소량 × 1.5⌉) (the larger of 50 and the required minimum × 1.5, rounded up), and when that exceeds the pre-approved limit written in ha.json in the user configuration folder (50 without one), it refuses the start without a record. When the 검증 실행 item holds a number, that number is used (run-record.md §1.5)
• 경과 시간 (elapsed time): the limit on the time from the first record to the last record within the budget window. Write it like 4시간, 90분, 1시간 30분 or 2h30m. It is measured by record times, not by the current time. So it does not grow while you only query the status during a wait, but when a record is added to the same window after the wait, the waited time counts too. Time passing after completion does not cancel the completion (run-record.md §5)
• 비용 (cost): the limit, if it can be known. 미관측 (unobserved) when there is no means to observe it

The budget window starts at ha start or at the last reopen (the user's rework request). The Seal Skill sets the defaults. When the user sets values in the request, those values are used. When the user sets no budget, Seal 0.1.20 or later writes 검증 실행: 자동; when the start stops because it needs the user's approval, Seal asks once, showing the computed value and the pre-approved limit, and writes the number the user approved in 검증 실행. It does not ask the same question again for the same PLAN. Seal never writes or changes the pre-approved limit setting. A budget can be lowered before the start; raising it needs the user's decision. Editing PLAN during the work does not by itself change the limits. Under /3, ha budget changes the total run-count limit of the same window and keeps the usage and the time limit. An increase records the user's original words and context; a decrease records a reason. An explicit resume under /3 carries over the latest run-count limit. /1 and /2 keep the original limit and the existing resume meaning (run-record.md §5.2).

In /4, /5, /6 and /7 goals, user waits the executor reports are left out of the elapsed time, and within the pre-approved limit the user set with a quote, the executor raises the run-count limit for a reason alone (run-record.md §4.7).

2.5 Time limits (## 시간 제한)#

An optional section. It is read only in run-rules/4, run-rules/5, run-rules/6 and run-rules/7 goals; a goal started under other rules runs every command with 900 seconds even when this section exists. Write one per line in PLAN's ## 시간 제한 section, like - AC-3: 30분, - T002 명령 1: 20분 or - EX-4: 1시간 30분.

• A target is a condition ID that has a command (AC-n, EX-n), or a task and a command number (T002 명령 1, the command order in the task document's ## 완료 조건).
• A value is a positive integer with the unit 시간 (hours), 분 (minutes) or 초 (seconds), or a combination of them. The maximum is 7200 seconds (2 hours).
• A value over the maximum, a malformed value, a target that does not exist and a second declaration for the same target are the lint problem time_limit_invalid, so ha start and ha check refuse before running.
• A command without a declaration gets 900 seconds. The baseline runs with that condition's limit. The applied limit is part of the command digest, so after a limit changes, earlier results are not fresh (run-record.md §4.7).

2.6 Execution environment (## 실행 환경)#

An optional section. To confirm the tools that checks use before the start, put a ## 실행 환경 section in PLAN and write one tool per line in the form - <이름>: `<점검 명령>` (a name, a colon and the probe command). Example: - 브라우저: `node scripts/probe-browser.mjs`.

• The section's extent is the same as for other PLAN sections: from the heading line up to the next level-1 or level-2 heading outside a fenced code block. Blank lines are skipped, and every other line must be a list item in this form. A fenced code block in the section is not an item either, so it is a malformed line: ha doctor reports the opening line of each block (also separately for a block that immediately follows another).
• The name is the text before the first : with leading and trailing spaces removed. It cannot be empty or contain a backtick, and the same name is used only once.
• The probe command follows the same rules as the verification command of the condition table: one code span, no shell syntax, and quotes around words with spaces.
• Seal 0.1.20 or later lists the tools checks need (browser, database, container, external service and so on) in this section, and runs ha doctor before recording any baseline and before the first check after a resume. It gathers unusable tools into one question, never widens permissions or settings on its own, and keeps doing independent work while it waits.
• Before recording any baseline, Seal 0.1.23 or later gathers the decisions that can be known in advance from the goal documents, the plan, the project instructions and the code and that need the user's words, together with unusable tools and a budget that needs approval, and asks them in one message. When a condition can be met only by user confirmation, the same message names that condition and what the user will be asked to confirm at the end. When there is nothing to ask, it asks nothing.
• Only ha doctor reads this section. ha doctor runs each probe with a fixed 60-second limit, shows 사용 가능 (available) or 사용 불가 (unavailable) with the reason for each tool, and leaves nothing in the record, the run count or the execution bundle (run-record.md §1.4).
• A malformed line (environment_item_invalid), shell syntax (shell_syntax), an empty command (command_empty), a command that cannot be split into words (command_parse), a duplicate name (environment_name_duplicate) and a second ## 실행 환경 section (environment_section_duplicate) are reported only by ha doctor, with file and line, and then no probe runs. They are not lint errors: with or without the section, and whatever its content, the results of ha lint, ha start, ha check and ha status are the same.

3. tasks/T00n.md#

Groups in 읽을 자료

Use summaries only as a guide to the original. Write the document path and section with them, and never replace the original completion criteria with a summary. When a small goal merges its tasks into PLAN, put the same groups in the ## 읽을 자료 section of PLAN.md.

4. REVIEW.md#

The result of the pre-execution review. Passing the review means "ready to execute", not that the implementation is right.

Its subject differs from Spec's consistency check (goal-docs.md §3).

• Spec's consistency check: is the goal itself clear?
• Pre-execution review (this document): are the plan and the verification method for implementing that goal sufficient?

When the review finds a contradiction or ambiguity in the goal documents, do not edit the goal documents. Ask the user.

The split REVIEW form applies to goals started with seal 0.1.29 or later. A goal started with an earlier Seal keeps the REVIEW form it started with. An existing REVIEW.md is never rewritten into the split form.

Assurance tier and review order#

Seal 0.1.20 or later reads the SPEC's Assurance: line (goal-docs.md §2.5) and applies the independent review stages that match the tier. Spar decides how review runs (packet, reviewers, classification rules, stage caps); this contract decides only the timing and the disposition.

• standard: takes a candidate stage on the final candidate whose narrow checks pass, a fixes stage after the review-fix commits, and a cumulative round before ha done.
• strict: in addition to standard, takes a plan stage before recording any baseline. It reviews the plan and the check declarations, and the product's invariants and decision rules that this change introduces or alters (target identification, location resolution, retries, caps and so on).
• light: may skip independent review; when it does, it leaves the reason in REVIEW.md and the completion report. When it takes review, it follows the completion order below.
• A goal without the line follows the selected assurance policy. The assurance requirements of project instructions (AGENTS.md and the like) are a floor. The tier can only raise it, never lower it; when the two differ, follow the one that asks for more review, and write in the completion report the review each required and the one followed.
• When the tier changes during implementation and the user asks to continue, apply the changed tier. A stage that the raised tier requires but that was not taken is taken on the current head before completion, and the records of reviews already taken are not deleted.
• The cumulative round is a round that calls Spar's candidate stage again over the goal's base commit to the last head. A goal that needs independent review runs ha done only after the cumulative round ends with no open defect or requirement-question. A fixes round that saw only the fixes cannot replace it; when there were no fixes after the candidate round, that round is the cumulative round. When the cumulative round hits a cap, ask the user; never go past the cap or skip the round without the user's words.
• Every round receives all the user's decisions recorded before it that the goal documents do not hold: the user's answers that closed REVIEW.md ## 중요한 미결정 items, confirmations (confirm) and inputs (input) that quote the user's words, and the user's answers to a review's requirement-question. Each decision gives what it settles (the REVIEW.md item or the confirmation's target) as --decision and the recorded quote unchanged as --decision-quote. Round cap extensions, reviewer waivers and reopen are not passed. Decisions go to every round from the plan round to the cumulative round. Passing decisions applies to every round this Seal runs, whichever Seal started the goal.
• For each product invariant and decision rule the change introduces or alters, ## 독립 검토 lists the places that read or keep it: each place's repository path, and the name used there when it differs from the change's name. It includes places that keep the same invariant under another name, not only those found by name; when the change alters no invariant, it says so; and every round from the plan round to the cumulative round gets one --question per place, asking whether that place still keeps the invariant at head; the list adds places for reviewers to look at and never narrows what they read. The list of places applies to goals whose start record names seal 0.1.25 or later, and existing goals' REVIEW.md is never rewritten to the new form.
• When a contract or check about open-ended input (sentences, paths, names, formats and so on) is added or changed, the plan writes the supported input forms before the plan review. Those forms cannot be narrower than the input that a SPEC condition, a contract or a protected path requires; narrowing them is for the user to decide. Ask the user about an open-ended condition whose forms are not written.
• Seal decides the disposition of findings. Fix a defect or rebut it with evidence; ask the user about a requirement-question (without editing the goal documents); never fix an automatically deferred hardening without the user's words. A finding about input outside the supported forms is hardening; when it was classified as a defect, rebut it by citing where the contract wrote the supported forms.
• A standard or strict goal started with run-rules/5, run-rules/6 or run-rules/7, after the cumulative round, makes a spar gate for HEAD from that series' rounds, records it with ha note <goal> review --gate <file> and then runs ha done. The rounds get all goal documents as --criteria. When no gate is recorded, or the recorded gate is stale, Core does not record completion (run-record.md §4.8). When Spar is missing or cannot run, completion is held; to finish without review, the user decides a goal-document change that lowers the tier to light. The acceptance of a separate review below does not apply to these goals.
• When Spar is missing or cannot run and review is not required, proceed and write in the completion report that there was no independent review. In a goal started with run-rules/4 or earlier where review is required, hold completion and record the cause, the affected conditions, the missing evidence and the resolution condition. Another separate review that records its role, inputs, reviewed version, findings or no findings, limits and checkable references counts as the required review; the completion report states that Spar was not used and the method that was used, and that review too covers the whole last head before ha done.
• When the user asks to apply remote review after a completion record, proceed in this order: reopen quoting that request, the fix, one cumulative round, re-recording stale required checks, and ha done.
• In goals started with run-rules/4 or earlier, the tier does not change the judgment or the output of ha status and ha done; in goals started with run-rules/5, run-rules/6 or run-rules/7, the gate above becomes a completion condition. The REVIEW.md of a goal started with an earlier Seal keeps the format it started with.

Verification evidence and observation scope#

New goals started with Seal 0.1.10 or later use the distinctions below in their existing review and completion report. Existing goals keep the format they started with, and the absence of the new items means unrecorded, not evidence of failure or non-execution. Do not convert existing records automatically or fill in past observations.

• Grounds for the expected result: the user's requirement, a public contract or an agreed invariant, and its location. When actual behavior or a reference implementation was taken as the standard, also state the contract and scope of that choice. An actual run or a fake's expected value is not in itself the authority on correctness.
• Boundary to observe: the boundary and scope of the actual shell, database, HTTP, model or other system to be checked. Write only the environments that affect the result, and distinguish planned, not performed and actually performed.
• Test method and substitute environment: what synthetic inputs, fakes, fault injection and comparison with a reference implementation control or stand in for. Do not stretch an example into the right answer for all inputs.
• Failure kinds not covered: gaps in the general property, the representative examples and the environment assumptions, and risky boundaries. Even a claim that no risk remains carries a scope, and the number of checks is not evidence of sufficiency.

Link every condition to these three axes and the gaps. A group of conditions that shares the same content may refer to one explanation; repetition per AC, or copies of the same table in several documents, are not required. When the expected grounds are undecided or conflicting, show that state, and do not write them as a finished answer.

Link what the review planned to the actual results in the report. When a condition, check or environment changes, also distinguish the version and the applicable scope of the evidence, and do not use earlier results as new observations. Distinguish facts confirmed by records from the executor's interpretation. Leave the scope where access or execution was blocked, and the reason, as unobserved.

While an important open decision at needs_user remains, do not execute; ask the user. Do not ask about what the implementer can decide, such as class names, file layout or implementation order (the same as Spec's questioning principle).

Assurance policy and counterexamples#

New goals started with Seal 0.1.11 or later, and high-impact verification design changes the user requested, link to each condition or condition group the source of the assurance policy, whether it is required or optional, and the reason for the risk. Explain the impact of a false success, the relevant boundary and the gaps in the current evidence, and also record why high-risk candidates were excluded. Do not impose on every goal the same agent, model or pre-baseline-check order on risk level alone. Do not lower a required assurance the executor has already set; leave only undecided outcomes for the user's decision.

Keep the expected grounds, the observation boundary, and the method and substitute environment separate; an actual comparison links the results and differences for the same property, input range and environment. Obtain evidence at the actual boundary when the property or policy a condition claims needs it, and do not require a call for every condition only because a real system exists. When structured originals linked to their targets exist, do not replace them with incomplete inference from strings. Do not promote the success of a fake, a synthetic setup, a reference implementation or a single model run into a guarantee of the whole real contract.

Independent review is a separate review, and its initial input is the goal, the public contract, the checks and the expected grounds. It does not fix its starting point on the implementer's explanation of the solution, but it may also examine the implementation and integration code it needs. Record the condition, check and code versions, the context provided, the role, checkable evidence, what was found, not found or not performed, and the limits. A self-review with only a different role name attached is not independent review, and no claim is made of model diversity, certified identity or a guarantee of sufficiency.

Link a counterexample candidate to its input, the expected violation and why the check misses it, and distinguish reproduction, rejection, fix and remaining gaps. When a violation of the original condition is confirmed, do not complete. Do not close it by passing the existing checks again and only adding risk wording to the report; record which check and which fix evidence handled the missed general property. Leave a proposal that changes the scope for the user to decide.

A check that accepts evidence does not use inconclusive as success, and a prohibition check does not hide inconclusive as no execution. Preserve unobserved, environment error, skip and actual violation. Inconclusive is not evidence of an intended baseline violation either. Evidence sufficiency and whether the product accepts or rejects an input are separate matters.

When a required review or actual evidence is missing, record the cause, the affected conditions, the missing evidence and the resolution condition, leave that required work unfinished and hold completion. Unrelated work continues within the existing authority and budget, and an optional comparison may leave its unobserved scope and risk to a later evaluation. Do not fill the gap with automatic installation, increased cost, widened permissions or a review record without facts.

When the goal, checks, code, expected grounds, environment or policy change, preserve the reviewed version and scope, and distinguish the new applicable scope. Do not reuse a past review for new inputs, or create an unrecorded review retroactively. Core's determinism, local assurance, result distinctions, adverse history, budget and authority stay; the executor chooses the method, timing, reviewers, model and mutation.

5. PROGRESS.md#

The format below is used for goals started with seal 0.1.20 or later. A goal started with an earlier Seal keeps the PROGRESS format it started with. The Skill version of the start record is on the skill: line of ha status. In a goal started with seal 0.1.6 to 0.1.19, ## 현재 is a short summary in which the check time (with time zone), the ha status and ha done judgment of that time and the record head are written by hand; each edit writes the check time and the record head as of then, and the check time is for reference. The other sections (## 타임라인, the time rules of the two tables) are as below.

5.1 Timeline#

## 타임라인 is an optional section. Events that changed a judgment or the next action are appended in time order, so that someone taking over in another session can learn "why it was changed this way". Its content is the executor's claim.

• Entry heading: ### <시각> · seq <기록 head> — <종류> · <한 줄 요약> (time, record head, kind, one-line summary)
  • The time is ISO 8601 with the time zone (for example 2026-01-01T09:00:00+09:00, or Z for UTC). When you do not know the exact time, do not make one up.
  • The seq is the record head when the entry is written (the heading carries only the seq; the hash goes in ## 현재). While there is no record yet, write seq none. An entry tied to a check run uses that run's seq. The seq is an order confirmed by the hash chain of runs.jsonl, so it is easier to confirm than the time, which is a claim.
  • The kind is one of 관측 (observation), 원인 (cause), 결정 (decision), 조치 (action), 검증 (verification), 막힘 (block) and 재개 (resume).
• Time source and judgment: distinguish the event time from the writing time, and record the time source. When the original event time is unknown, leave it unknown; the heading may use the actual writing time. Write the remaining conditions, new facts, the grounds for a hypothesis and the uncertainty to reduce next, as far as they apply. Do not record every tool call, and do not dress up the same result from the same code, environment and hypothesis as progress. After a repetition, a changed judgment must show, such as a separated cause, a different hypothesis or a blocked condition.
• Body marks: mark a 원인 (cause) as 가설 (hypothesis), 확정 (confirmed) or 기각 (rejected); a 조치 (action) as 예정 (planned) or 반영 (applied); and a 검증 (verification) as 대기 (pending), 통과 (passed) or 실패 (failed) (for example 원인 [확정]: …). Point to evidence by AC, commit and seq, and do not copy raw check output (section 6).
• Append only. Do not edit earlier entries. That something was 대기 (pending) at that point is history too. When a judgment changes, write in a new entry what was rejected and on what grounds. A small event that went from confirming the cause to verification at once may be one entry.
• What to record: events that changed a judgment or the next action. These are a new problem, a cause confirmed or changed, a change of approach, an important verification result, and blocks and resumes. A resume is any case of starting work again. This covers a new session taking over, a block being cleared and an answer received to needs_user. A 재개 entry notes where ## 현재 differed from the actual state, if it did.
• What not to record: routine edits and reads, repeated runs of the same failure, progress reports with no change
• Length: an entry is about 3 to 6 lines and ## 현재 about 5 to 8 lines. This is editing guidance, not a limit. A complex cause analysis may run longer.

Below is a hypothetical example to explain the format. It does not represent an actual run record.

### 2026-01-01T09:00:00+09:00 · seq 2 — 원인 · AC-1 빈 입력 처리
- 관측: 빈 입력을 읽는 검사에서 오류가 났다(seq 2).
- 원인 [확정]: 첫 항목이 항상 있다고 가정했다. 근거: `src/count.go`의 입력 처리
- 조치 [예정]: 빈 입력일 때 0을 반환한다.

5.2 Post-completion findings#

New reports from Seal 0.1.12 on may write details in ## 완료 뒤 발견 or refer to details kept in one place. The format, completion report and run record of existing goals are not converted automatically, and a missing new section is read as unrecorded. Even when appending a new finding to an older goal, do not create past observations or overwrite the original completion report.

Link the finding identifier; the target code, goal and reference to the completion at the time; the related condition, or no condition included, or link undecided; and the description, source, reproduction evidence, observed scope, current confirmation claim and follow-up work. Leave unknown values as undecided or none, and do not fill in arbitrary versions, conditions or check results. Distinguish the event time from the recording time and record the time source. An unknown event time is unknown, and the writing time does not stand in for it.

Distinguish candidate, confirmed, duplicate, rejected and resolved, and tell a new requirement apart from a violation of an existing condition. When a judgment changes, preserve the original and append the correction target, the new judgment, the reason and the evidence. A duplicate points to the canonical finding, and a resolution records the fix and recheck evidence and the unconfirmed scope. Do not describe the number of reports as the number of unique confirmed defects. A document's state names do not guarantee a mechanically current state or the resolution of conflicts from concurrent edits.

The current summary distinguishes the completion at the time, the current findings, and rework requests and whether they are in progress. When a confirmed violation of an existing condition exists, do not put the completion record forward and describe things as if there were no current defect. Keep the details in one place and refer to them from the summary, and do not apply later fixes or checks retroactively as evidence for the past completion.

Recording, confirming, rejecting or resolving in documents does not change the existing completion, execution budget or user authority, and does not start rework. When there is an explicit rework request, link its original source, the target finding and the follow-up result, and distinguish requested, planned, in progress, complete and not requested. Raw logs and private conversations keep their existing storage boundaries and are referred to by permitted locations and identifiers. Public examples state that they are synthetic. This document format is not an implementation of Core's structured queries or state transitions, and does not replace a separate feature contract.

Review or PR findings received without the user's request are not authority to change the completed goal's code. Record them as post-completion findings in this format and report them. Changing the code needs the user's request and reopen.

5.3 PROGRESS with decision history#

A goal started with Seal 0.1.13 or later may record detailed judgments once in the optional decision history and refer to them from PROGRESS by event ID (D<n>). A goal started with an earlier Seal keeps the PROGRESS format and documentation duties it started with. An environment that supports the feature may add an auxiliary history, but does not retroactively omit originally required explanations or convert past timelines. ha does not read the prose sections of PROGRESS, and an event ID reference does not change a task state or the completion judgment.

• Write the detailed reasons, evidence and relations once in the history, and read them with the Markdown query of ha history. Do not save the query's Markdown as a separately maintained source, and do not generate the whole of PROGRESS automatically. No number of sentences or fixed writing order is set.
• PROGRESS refers by ID only to events whose storage succeeded. For a judgment where the history was not used, the feature cannot be used, storage failed, or whether it was applied could not be confirmed, leave the explanation in Markdown in the form of 5.1. Required handover content must never remain only as an event ID.
• The decision history is local data in the Git common directory, so it does not follow to a new clone or another machine. There, the detailed reasons, evidence and relations are absent, and only the current state, the important decisions with short reasons and how to resume, kept in PROGRESS, partly make up for this loss. This is not a restoration of the detailed history.
• The executor decides which events to record and when, which relations to link, and how to group small events. The criteria for which events to record are the same as in 5.1. This feature has no human approval step or retrospective duty of its own.

5.4 Review summary#

## 검수 요약 applies to goals whose start record names seal 0.1.24 or later. A goal started with an earlier Seal keeps the PROGRESS and report form it started with, and existing goals' PROGRESS.md is never converted to the new form.

This is where the user starts reviewing a finished goal, so that the user can see in one place what changed, why and on what evidence, and what a person must inspect directly. Written once ha done records completion, as of that completion record, and rewritten as of each new completion record after a reopen; not written before completion or when work stops at needs_user, blocked or budget_exhausted. Before that, the heading holds one line saying so, and at a stop ## 현재 and the completion report (section 6) carry the state as before. ha does not read this section.

When a goal with a completion record is reopened with reopen, the earlier content of this section stays unchanged until the next completion record. Add one line at its top saying which completion record (seq and commit) it is as of, that the goal was reopened so that completion record is no longer valid, and that this section will be rewritten after the next completion record. A stop in between (needs_user, blocked, budget_exhausted) leaves the earlier content and that line as they are. After the next completion record, rewrite this section as of that record; that line does not remain. For a reopened goal this rule applies instead of the one line kept before completion.

The section has the items below, all of them and in this order; write 없음 under a heading with nothing to list.

• Opening lines, with no heading: the completion record's seq and commit, the assurance tier, how many required conditions are satisfied, and the review gate result; one line on what the change does; where to start looking.
• ### 바뀐 동작과 파일 (changed behavior and files): a table 바뀐 동작 | 조건 | 파일 (changed behavior, condition, files). Every file changed from the goal's base to the completion commit, goal documents excepted, appears in a row; this goal's check files have rows too.
• ### 범위 밖이나 기존 것을 바꾼 곳 (changes outside the scope or to existing things): one item each for files outside the SPEC scope, changes to existing tests, and changes to checks an earlier goal left, each with where the user's words allowing it are, or the reason.
• ### 근거 (evidence): for every condition, what the check that satisfied it observed and the commit where it passed, never by seq alone; and a table 라운드 | 지적 | 끝 (round, findings, ending) with one row for every review round, a round with no findings included. Every finding of the round ends in exactly one of 고침 (fixed), 반박 (rejected), 중복 (duplicate), 사용자의 답 (the user's answer), 이슈로 보류 (deferred to an issue), 자동 보류 (deferred automatically) and 처리 없음 (no disposition).
• ### 누가 정했나 (who decided): decisions in three groups: decided by the user, with where their words are; proposed by the agent and accepted by the user; executor assumptions nobody was asked about. Mark an assumption that reads a SPEC sentence.
• ### 직접 볼 것 (what to inspect directly): ordered by risk, the highest at the top, one or two lines each: every item the 직접 볼 것 line of ha report lists and, whatever that line shows, every deferred finding with its issue; every finding left with no disposition; executor assumptions that read a SPEC sentence; conditions met by checks that observe fixed text only, whose documents a person must read; manual conditions; the changes under ### 범위 밖이나 기존 것을 바꾼 곳.
• ### 보지 않은 것 (what was not observed): Unobserved scope and substitutes, assurance local, the fact that the executor wrote the checks, and the fact that the summary is not evidence of deployment, installation or a real model call.
• ### 자세히 (details): the documents and sections that hold the detail.

The judgment items of the completion report's item 2 (section 6) go here: the changed files and the condition each contributed to under ### 바뀐 동작과 파일; assumed open decisions under ### 누가 정했나; manual conditions under ### 직접 볼 것; the expected-result grounds, the actual observation boundary, the test method and the review stages actually taken (or why they were skipped, and, when the SPEC tier and the project instructions differed, the review each required and the one followed) under ### 근거; the unobserved scope and substitute environments under ### 보지 않은 것; where the independent review results are under ### 자세히; and whether the head to be sent or merged is the completion record's commit, with the fact that the completion does not cover a difference unless ha status at that head still names that completion record, in the opening lines.

The two parts of ### 근거 and the items of the opening lines are minimum lists; the items the judgment-item paragraph assigns join them in the same place.

The judgment items moved from item 2 of the completion report keep its qualifications: the executor's statements are marked as claims, and facts confirmed by records are kept apart from the executor's interpretation. When conditions, checks or environments differ from the plan, state the evidence's version and the scope that evidence covers.

Reading rules: write in the user's language; say what a record is, with its seq only as an aid; keep each item short; never copy check output or finding text; a finding is its ID, one line and its ending. The original text of a finding stays in the review records. At completion, the executor's judgment sentences are only in this section, and the completion report points to it (section 6).

Only when the user asked for a PR does the following guidance apply. This PR guidance applies only to a goal that has a ## 검수 요약. This guidance adds no authority to create, change or push a PR, or answer a review.

When writing or changing a completed goal's PR description, build it from that goal's ## 검수 요약. Include the completion record's commit, the changed behavior and files, and an evidence summary. Include every item of ### 직접 볼 것, including deferred findings with their issues and findings without a disposition; include ### 보지 않은 것. Add the items the project instructions require in a PR description, such as a list of deferred findings and check boundaries. Never drop a ### 직접 볼 것 item or rewrite it as resolved.

Leave out paths and links to goal documents, execution bundles and review records that Git does not track, since a PR reader cannot open them. Also leave out the raw user conversation; instead, describe the content briefly or say it is in local records.

6. Completion report#

Written when ha done has left a completion record, or when work stops because it cannot go further (needs_user, blocked, budget_exhausted).

The completion report of a goal started with seal 0.1.20 or later has these two parts.

1. The ha report <goal> output of that moment. Run it with --lang ko when the user's language is Korean and with --lang en otherwise, and paste it unchanged. It holds the five-line summary, the ## 현재 stamp, the evidence per condition, the completion coverage (the completion record's seq and commit, and whether it covers HEAD) and where the original output of unmet conditions is, and no raw verification output. Do not paste the raw ha status or ha done output.
2. Below it, add only the executor's judgment sentences: the changed files and the condition each contributed to (a claim); assumed open decisions and manual conditions; the grounds for the expected result, the actual observation boundary, the test method and substitute environment, and the unobserved scope; the assurance tier and the review stages actually taken, or the reason they were skipped; where the independent review results are; when the SPEC tier and the project instructions differed, the review each required and the one followed; whether the head to be sent or merged is the completion record's commit and, when it differs, the fact that the completion does not cover the difference (it does cover it when ha status at that head keeps showing the same completion record); the assurance level local and the fact that the executor wrote the checks; the fact that the report is not evidence of deployment, installation or a real model run; and, when not complete, how to continue.

For a goal started with seal 0.1.24 or later, at completion ## 완료 보고 holds item 1 and one line pointing to ## 검수 요약; item 2 lives only in ## 검수 요약 (5.4). When work stops, both parts stay as above.

A goal started with a Seal earlier than 0.1.20 keeps the report format it started with, in the order below.

1. On completion, the output of ha done; when stopping, the output of ha status --format md. Paste it unchanged and do not rewrite it. This output holds only the result, reasons, digests and record seqs, and no raw verification output.
2. Completion coverage (goals started with Seal 0.1.15 or later): the completion record's seq and commit, whether the head to be sent or merged is the same as that commit, and, when it differs, the fact that the completion does not cover the difference. When ha status at that head keeps showing the same completion record, however, the completion covers it. A goal started with an earlier Seal keeps the report format it started with.
3. Evidence per condition: condition, result, record seq. Omit it when the status output has it.
4. The changed files and the condition each contributed to. This is the agent's explanation; mark it as a claim.
5. Remaining limits: assumed open decisions, manual conditions, the assurance level (local), the fact that the executor wrote the checks
6. In the new report format, link the review's expected grounds, planned boundary and method to what was actually performed, the results, the evidence and what was unobserved. Present what was confirmed, what could not be confirmed and the risky boundaries by condition or shared group. Also state the checks, environments and versions that differ from the plan, and the valid scope of the evidence. The report does not stand in for evidence of deployment, installation or a real model run.
7. How to continue: when not complete, what remains and under what conditions the work starts again

When the user asks, after a completion record, to apply remote review or PR findings, that is a rework request. Record reopen quoting that request; after the fix, a goal that needs independent review takes one cumulative round; re-record the stale required checks on the final head; and before sending or merging, record completion again with ha done. Core's freshness decides which checks to re-record (run-record.md §3).

Never paste raw verification output anywhere in the execution bundle. The execution bundle is committed, and the user may share it with others. When a failure's cause needs explaining, summarize it, and let the raw output be viewed locally with ha log <goal> <seq>.

7. Example (a small goal, with its task merged into PLAN)#

Below is an example of ordinary runner commands for /1 and /2. For a new /3 change, this pytest exit code alone is not enough. Link a declaration and a producer, as in the result contract's actual reference integration. A maintain condition that preserves all existing checks can keep using an ordinary runner.

# PLAN — empty-input

## 조건표
| ID | 종류 | 검증 명령 | 검사 경로 | Task |
| --- | --- | --- | --- | --- |
| AC-1 | change | `python -m pytest tests/test_empty.py -q` | tests/test_empty.py | T001 |
| AC-2 | maintain | `python -m pytest -q` | — | T001 |

## 범위
- 바꿀 수 있는 경로: `src/textstats/**`, `tests/test_empty.py` (SPEC: Proposed Behavior)
- 테스트 경로: (기본값)
- 유지할 동작: 비어 있지 않은 파일의 출력 형식 (SPEC: Non-goals)

## Task
| ID | 목표 | 근거 | 제안 | 선행 | 필수 | 문서 |
| --- | --- | --- | --- | --- | --- | --- |
| T001 | 빈 입력에서 0 0 0을 출력한다 | AC-1, AC-2 | — | — | 예 | — |

## 예산
- 검증 실행: 20
- 경과 시간: 2시간
- 비용: 미관측

8. ha lint error codes#

ha lint prints one line per error with the code, the file and line, and a description. With no errors, it prints the single line ok: no lint problems, and when the goal documents have a valid Assurance: line (goal-docs.md §2.5), it adds assurance tier: <등급> (tier) on the next line. With even one error, ha start and ha check are refused, and ha status gives lint_error.

Goal documents (goal-docs.md)

Execution bundle