Reading work status and the completion report

한국어 · English

Read this when you want to know why work stopped, or to check in detail what a completion report rests on. It covers pre-start checks, what a failure before the change means, the evidence behind the report, the state that needs your confirmation (needs_user), blocks and budgets, and the assurance policy. For first-time users, invocation, resuming, and troubleshooting are in the usage guide. For installation and checking versions, see the install guide.

This document describes preflight diagnostics, capability checks, nested/1, /3 results, and total run-limit changes in v0.1.8 (ha 0.1.8, spar 0.1.8, spec 0.1.13, seal 0.1.23, spar plugin 0.1.4). Existing goals keep their saved rules and formats. The difference between release distributions and source builds is in Release and development combinations.

Handing over a goal#

Spec organizes your request into goals, scope, and completion criteria in docs/specs/<goal>/SPEC.md, reports what it wrote, and then stops. Refine the goal by answering outcome-changing questions or stating what to change. Status: Ready indicates that the document is ready; it does not start implementation.

When ready, select seal:seal from the $ list in a Codex conversation and send $seal:seal docs/specs/<goal> as a separate message. In Claude Code, use /seal:seal docs/specs/<goal>. If a goal document already exists, you can hand it over to Seal directly. The agent reviews the plan and check methods, then proceeds with implementation, checks, and fixes. You do not need to approve every operation.

The user decides whether to change the goal and scope. Seal never modifies goal documents. If you revised the goal with Spec, make a separate request such as docs/specs/<goal> 이어서 해줘 (continue docs/specs/<goal>). For detailed document formats, see the goal documents contract and execution bundle contract.

Checking tools beforehand#

If your checks use a browser or another external tool, confirm the tool is there before the checks actually run. List the tools in the PLAN section ## 실행 환경 in the form - <이름>: `<점검 명령>` and run ha doctor <goal>. Each tool gets 사용 가능 (available) or 사용 불가 (unavailable), and the reason for an unavailable tool is one of 실행 파일 없음 (no executable), 실행 권한 없음 (no permission to run), 시간 초과 (timed out), 0이 아닌 종료 (nonzero exit) and 신호로 종료 (ended by a signal). Each check gets at most 60 seconds and counts toward neither the record nor the budget. ha doctor installs nothing. Install an unavailable tool or fix its path before the checks.

What to check before running#

Before recording anything, Seal looks at three things: whether the installed ha has the support it needs, whether the budget is enough, and whether the working tree has uncommitted changes. If any of them is off, it stops and says why.

Core support#

From Seal 0.1.20, Seal no longer compares Core support by hand. It declares the support it needs in core-requirements.json in its skill folder and starts with ha start --check-skill; when support is missing, ha refuses without a record, and Seal reports the executable and the message and stops.

• Seal 0.1.21 also requires run-rules/5 and the review gate support.
• When the installed ha does not know run-rules/5 or other support Seal requires, Seal stops without a record and does not fall back to older rules. What to do is install an ha that has that support.
• For a goal already started, each command computes its saved rules or refuses them with exit 66.

Seal 0.1.26 requires run-rules/6 for new goals and starts with ha start --rules run-rules/6 … --check-skill. Its format and feature requirements are the same as 0.1.21; only the rule changes. ha 0.1.8 does not support /6 and refuses this start. Without /6 or any other required support, Seal stops without a record and does not fall back to earlier rules. An ha with that support is needed; goals already started under /1 through /5 keep their saved rules.

When the skill folder that Seal names with --skill has a core-requirements.json, start compares the Core support that skill needs with the actual executable and refuses without a record when any support is missing. With --check-skill, the declaration is required, and an ha from before this feature does not accept that start (Core capabilities contract §8).

The support check of earlier Seal versions (0.1.17 to 0.1.19)

The rest of this section describes the check of earlier Seal versions (0.1.17 to 0.1.19).

Seal resolves the absolute path of the Core executable it will actually use, and reads capabilities --format json from that executable. A fresh start requires both that the default rule is understood and that all required capabilities are present. Existing goals are checked against their saved rules and the requested action.

Seal stops before recording and explains the target and reason if any of the following occurs:

• Querying capabilities is unsupported or fails.
• The query returns invalid information.
• Required capabilities are missing.

Seal never reuses query results from another executable or starts by switching to /1 or /2. If the path or the executable content changes, Seal checks capabilities again. For the exact fields, see the Core capabilities contract.

This capability check is never bypassed through automatic installation, privilege escalation, or altering historical records. Even after an update, Seal re-reads the capability information from the actually selected executable.

The Python compatibility helper is optional. Even without Python, you can directly verify the contract against the actual capability information. Spec does not need Core or this query to write documents. Whether an installed Codex or Claude model actually follows instructions is subject to separate host evaluation; capability output alone does not guarantee it.

Budget and tools#

• Without a budget it starts with 검증 실행: 자동 and asks once, only when approval is needed.
• It checks the tools the checks need with ha doctor before any baseline and asks about unavailable tools in one question.

The agent can compare the minimum verification run count in PLAN with the limit using ha estimate docs/specs/<goal>. For example, up to run-rules/6, 34 required change conditions need at least 68 runs: one before and one after the change for each. manual conditions are not included in the check execution count. The estimate also separately displays:

• Optional conditions included in default comparative verification.
• Additional run counts for explicitly selected AC, EX, or task commands.

--baseline shows the runs for the baseline (comparison) selection, and --format json gives machine-readable output.

If PLAN gives - 검증 실행: 자동 (automatic), start sets the limit to max(50, ⌈required minimum × 1.5⌉).

• When that value is at or below preapproved_runs in ha.json in the user configuration folder (~/.config/jaekit/, or $XDG_CONFIG_HOME/jaekit/ when XDG_CONFIG_HOME is set), the goal starts without a question. Without the file, that limit is 50.
• Above it, start stops with exceeds the pre-approved limit, records nothing, and waits for the user's approval.
• A file that cannot be used stops with a pre-approved run limit error instead of falling back to 50.

The format and examples are in the usage guide.

If the limit is less than the required minimum, start refuses before recording. In this case, split the goal within the existing allowed scope, or decide on an adequate budget before starting. The estimate does not include retries or preparation time. Querying an in-progress goal only explains the current PLAN; it does not increase an already recorded limit or remaining budget.

Uncommitted changes#

If verification is refused before running due to uncommitted changes, check the printed paths:

• tracked: Changes to files already tracked by Git. Commit or revert them according to your work intent.
• untracked dependency symlink: Look at the path of the link itself to decide whether to keep or ignore it. For example, if apps/web/node_modules is displayed, review the ignore rules for that path.

Guidance alone will not ignore all node_modules or clean up files automatically.

Refused checks do not count toward the execution count. If execution stopped while running multiple checks, previously executed results and usage remain, and the output indicates how many were executed. The paths and types also appear under worktree_dirty in ha status. A Git query failure is never treated as a clean state. Resolve the problem, then rerun verification.

Criteria format in goal documents#

New Spec examples specify Criteria-Format: nested/1. This reads description lists under an AC as the body of that same condition. Existing goals without this marker keep their previous interpretation.

Adding this marker to an existing goal changes the goal document. Therefore, previous verifications and manual confirmations cannot be reused for the new interpretation. For indentation examples, refer to the goal documents contract.

What a failure before the change means#

Up to run-rules/6, a check for every change condition must show the intended violation before the change; under run-rules/7, this applies to a marked change condition. The mere fact that a command failed does not constitute pre-modification evidence.

A change check must link declared targets and requirement violations through structured results. The following are not accepted as expected failures:

• Missing dependencies
• Errors in import, test collection, or browser startup
• Unexecuted or skipped checks (skip)
• Script failures with uninterpretable meaning

Results where an actually executed check directly observes the absence of functionality can be distinguished.

When recording a baseline, all declared targets must run and show the intended violation without errors or other assertion failures. Current checks require all declared targets to pass whether or not a baseline is required.

See the check result contract and reference check for how to link them. The reference check is a small example that actually reads files; it does not automatically install specific test runners or support all runners.

Linking a test you already have#

To use a test you already have, a Core whose ha capabilities lists check-adapter/v1 can link a change condition to that one test through a runner adapter. ha reads the output of go test -json …, or the JUnit XML a runner writes at the {HA_JUNIT_XML} location, without a producer program.

Put the marker jaekit:violation=<violation id> on the first line of the assertion's failure message for when the property breaks. For a hypothetical greeting CLI test, write t.Fatalf("jaekit:violation=greeting-missing the CLI says %q", got).

A failure without the marker, or with the marker only in a log or standard output, is not accepted as the intended violation. Adapters are optional; without support, use the reference check or a dedicated producer.

Errors and retries#

error and inconclusive verdicts are included in limited error retries. Actually attempted failures, errors, stale results, and usage remain. A later pass alone does not erase an unfavorable result produced on the same input.

Look at the reason in the status and the corresponding ha log to decide what must change among the check, the product, or the environment.

Differences between rule versions (run-rules)

Starting with Seal 0.1.16, Seal starts new goals under run-rules/4, and from 0.1.21 under run-rules/5, which keeps all of /4 and adds the review gate for standard and strict goals. /4 preserves the /3 result rules while adding autonomy, including error recovery.

Seal 0.1.26 starts under run-rules/6. /6 changes only four judgments from /5.

• For standard and strict goals, review_base_mismatch blocks completion if the last candidate round (excluding dry runs) did not review from the start's base_commit. Spar's gate checks a fixes chain following a candidate from the start base.
• A review note after completion voids the completion record only for the current standard or strict tier. With light or no tier line, an otherwise valid completion record stays valid.
• A done line is judged when its record_head is the hash of an earlier line and every line strictly between that line and the done line is a finding line (run-finding/v1), including when there are no intervening lines. The named line may itself be a finding line. Every done line is judged on the full record first, so a line may be judged even when its record_head names an unjudged line. Unjudged complete and non-complete done lines are then treated as absent from status computation, including the completion record and its explanation, the latest done line, the budget window, elapsed time, post-completion intervals and budget-change refusal. Status, report, cost and budget changes use this same view. An earlier record still needs every other validity condition; a judged line invalid for another reason still stops the search.
• The interval after completion until the next run or a non-complete done leaves elapsed time and is shown separately as post_completion_seconds. The budget explanation below and contract §4.9 define its boundaries.

Existing goals started under /1 through /5 keep their previous judgments and are not automatically migrated.

Baseline selection and check freeze (run-rules/7)#

Current Seal starts new goals under run-rules/7. It stops without a record on a Core that lacks support and does not fall back to earlier rules. A direct ha start still defaults to run-rules/3; judgments, output and records of goals already started under /1 through /6 stay unchanged.

Only change conditions with 요구 in the condition table's optional baseline column require a baseline. An empty cell, —, or no column means none is required. Mark conditions at risk of a false pass, such as bug fixes, regressions, "X does not happen", or conditions partly met at base, and write the reason in REVIEW before the plan round. Unmarked change conditions still need check paths and the structured result contract, but can link to tests of new functions without an entry point that also exists at base.

The required minimum is marked required change × 2 + unmarked required change + required maintain (표시한 필수 change × 2 + 표시하지 않은 필수 change + 필수 maintain). Manual conditions count as 0 runs. One marked change, four unmarked changes and three maintains, all required, need at least 9 runs; the automatic limit is max(50, ⌈9 × 1.5⌉) = 50. Before starting, view this with ha estimate <goal> --rules run-rules/7. Started goals use their saved rules and refuse a different --rules.

With no target, ha check <goal> --baseline selects only marked change conditions, including marked optional conditions. With none marked, it refuses without a record. An explicitly named unmarked condition can also run a baseline, and actual runs count toward the budget. Fresh adverse results from that baseline still affect judgment. Plan to record a marked condition's baseline once its check files are settled. This reduces the habit of recording after every check fix; it does not make stale evidence fresh.

Under /7, the "before any baseline" questions, ha doctor and the strict plan round all happen before the goal has any ha check record, current check or baseline, even when the goal needs no baseline. Seal gathers foreseeable questions before work; with nothing to ask, it proceeds.

• An input failure—a missing target file, corrupt input, a tool that cannot start, or termination by a signal—is never a pass.
• Checks that require no baseline (maintain, EX-n, task commands and unmarked change conditions) may count an input failure as a violation, error or inconclusive result; that alone is not a check defect. A failure recorded as a violation remains until the input changes.
• A dedicated producer of a marked change condition reports none of them as a violation unless the result contract allows it, such as missing: violation; record that choice in REVIEW.md before the plan round, or before any review round when there is no plan round.

Read the baseline requirement under the goal's rules: all change conditions require it up to run-rules/6, and only marked conditions do under /7. Runner adapters classify input failures themselves; the classifications and input-failure table of the result contract stay unchanged.

The check freeze uses the earliest plan round for strict or the earliest candidate round for standard, in gate order among the last recorded gate's non-dry-run rounds. It covers declarations, producers, tests, helpers and settings in the condition table's check paths, from every row that lists any. Right after the freeze round, Seal records the gate and current condition table's check paths with ha note <goal> review --gate <file>. Without a gate note ending at that round, removed check paths are unobserved and status and report show freeze-time condition table was not recorded.

After changing a check file following the freeze, commit it and record ha note <goal> check-change checks:<path> --reason "<finding ID, or condition and reason>". A review fix names its finding ID. The reason binds to the current blob, so another edit needs a reason for that edit. Give the next code review round the changed checks and reasons together. No such reason is needed before the freeze; check defects may still be fixed afterward. The freeze display itself neither blocks completion nor requires a plan-delta.

ha status shows baseline_required on each change condition and a human-readable baseline required line. Checked in ha report separates how many of all change conditions require a baseline from how many of those have fresh baselines. Read To review for baseline marks removed since the start, check files changed after the freeze with reasons, and changes without reasons. Removed paths identify the source review note seq. light goals and goals without a recorded gate have no freeze display. The review summary's ### 보지 않은 것 lists change conditions satisfied without a baseline. Run record §4.10 defines exact fields and wording.

Reading the completion report#

The completion report (## 완료 보고) appears in PROGRESS.md in the goal folder and in the conversation. Check the following:

1. What changed. Check whether actual files, screens, and behaviors match the request.
2. How required conditions were satisfied. Distinguish between automated check results and items confirmed manually. Optional conditions do not block completion and are marked separately.
3. What the checks covered. Review checks that verified new behavior, behavior that must be preserved, and unverified scope. If verification commands or condition kinds were changed, check the reason.
4. What assumptions and limitations exist. Review whether agent-chosen assumptions match your intent, and whether remaining limitations affect the result.

The evidence of completion is the completion record left by ha done. In Terminal, run ha status <goal> to check the status based on the current goal and records. Replace <goal> with the actual goal folder path, such as docs/specs/login-link.

For goals started with Seal 0.1.20 or later, the completion report pastes the ha report output unchanged: read the five lines at the top, then the completion record and Seal's judgment below them. In a finished goal started with 0.1.24 or later, the judgment is in ## 검수 요약. ha report <goal> summarizes the same records in five lines: Changed, Checked, To review, Remaining limits and Next step. It is the same computation as ha status and does not change the record. The stamp below the summary shows which record head ## 현재 in PROGRESS.md should be checked against.

Review summary. In goals started with 0.1.24 or later, after completion, ## 검수 요약 right after ## 현재 is where you start reviewing. Its top lines give the completion record, the assurance tier, how many required conditions are satisfied, the review gate result, what the change does and where to start looking; below them come changed behavior and files, scope changes, evidence, who decided, what to inspect, what was not observed, and details, in that order. A heading with nothing to list says 없음, and after a reopen the section is rewritten as of the new completion record. It is written in the user's language and says what each record is; each item is short, with seq numbers only as an aid; no check output or finding text is copied; a finding is its ID, one line and its ending. Seal's judgment is only there, and ## 완료 보고 holds the ha report output and one line pointing to it. For a finished goal, read ## 검수 요약 first. For a goal that stopped, or one started with an earlier Seal, read ## 완료 보고 as before.

The assurance level local means evidence obtained on that computer. Checks are authored by the executing agent, which can modify files and records with the same user permissions. It does not mean that the whole result is defect-free or guaranteed by an independent third party.

If something is missing, state what to fix. Seal records reopen citing the user's request and reworks the goal. Previous completion records are not used as current completion evidence, and a new budget window opens. If the goal document itself must change, update it with Spec and separately ask to continue.

If you need the raw check output, view it in Terminal with ha log <goal> <seq>. <seq> is the record number shown in the report. For process_output records where saving output failed after execution, the raw output path may be empty even though the actual attempt and usage remain. If applying changes is uncertain due to a record-saving error, do not assume success; verify the save state. Preserved raw outputs live under ha/ in the Git directory of the worktree and are not tracked by Git (see Saved files).

Handling needs_user#

When items remain that the agent cannot decide on its own, it asks along with the reason. Make the required judgment and reply, and that response is recorded.

Blocks and budget#

• blocked: Stopped due to expired authentication, denied permissions, usage limits, or similar issues. Read the clearing conditions recorded by the agent, resolve the cause, and tell the agent to continue.
• budget_exhausted: Exceeded the budget for check run count or elapsed time. Review remaining work and which limit was exceeded, then decide whether to allocate more.

run-rules/4 and later follow the /3 budget rules below while separately setting pre-approved limits, reported waits, and limits for resumed windows. For those differences, see Autonomy (run-rules/4) and the run record contract. run-rules/6 also excludes time after completion as described below.

In /3, to use more runs only, change the total run limit of the current window:

• For example, if usage is 48 runs against a limit of 50 runs, changing the limit to 100 gives 48 used and 52 remaining.
• If reduced to 40 runs, there are 0 remaining and 8 in excess; recorded usage does not disappear.
• An increase retains the user's raw words allowing the limit and the request context; a decrease retains the reason.
• Even a short "okay" ("좋아") is not rejected on form alone if context shows what was agreed to.
• If the quote source cannot be confirmed, it remains an agent-recorded claim.

Changes are linked to the status window number, budget revision, and current limit. If a change conflicts with another change or resume, it is never overwritten or summed automatically. Re-check current status to decide. If a storage error signals uncertainty of application, verify the record before reapplying. See the product contract for exact commands and fields.

This change does not open a new window. It does not reset the time limit, elapsed time, failure or error limits, or blocked state. Changing the time limit is unsupported. Editing PLAN alone does not change in-progress limits. A completed window requires explicit rework or resumption; a new /3 window inherits the latest run limit and the original time limit. Existing /1 and /2 goals open a new window with original limits via reopen quoting the user's statement, as before.

The budget window runs from the last start or reopen to the timestamp of the last record subject to the run budget. Finding lines are excluded from budget input. A status check alone does not increase elapsed time, but a new record—including a budget change—extends the window. /4 and /5 subtract reported waits from the window span; run-rules/6 also subtracts intervals after completion. Checks executed across resumptions are counted in the window where they are recorded. Actual attempts of checks and baselines, errors and inconclusive verdicts, and valid versus stale results are separate aggregation axes. Baselines are also included in usage.

Under run-rules/6, an interval after completion starts at the at of a judged complete done and ends at the earlier of the earliest started_at of a check or baseline that started in the same second as that at or later and the at of a non-complete done. A run that started before completion and was recorded afterward does not end the interval. With neither endpoint, it ends at the window's last budget record. Another completion done continues the interval; notes and finding lines do not end it. Run intervals stay elapsed, and time overlapping reported waits is subtracted only once. The additional excluded seconds are budget.post_completion_seconds, with elapsed_seconds = span_seconds - reported_wait_seconds - post_completion_seconds. The human-readable status Budget section and the budget window in ha cost JSON show these seconds separately; the remaining limits in ha report and ha cost use the same elapsed time. Work before the first run after completion is also excluded, so code rework proceeds in a new window opened with reopen quoting the user's request. Run counts, limits and refusal to change a completed window's budget stay unchanged.

Reaching the limit means usage equals the limit; exceeding it means usage actually surpassed the limit. A goal with a completion record does not enter budget_exhausted as time passes. Under /2 through /7, if all required conditions are satisfied and only budget exhaustion remains, completion can be recorded. This is not authority for additional execution; nor is budget a mechanism that automatically blocks check execution or terminates running checks.

Continuing in a new conversation#

Open a new conversation in the same project folder and send docs/specs/<goal> 이어서 해줘 (or continue docs/specs/<goal>). Seal reads the goal, plan, progress records, and current status, then continues the remaining work. If any items remain that require user judgment, answer them first.

Reporting verification evidence#

The reporting format introduced in Seal 0.1.10 distinguishes grounds for expected results, actual observation boundaries, test methods, and alternative environments. Condition groups can reference the same grounds. Reviews record planned items; completion and discontinuation reports record actual results, unobserved scope, and remaining risks. Actual execution is not in itself grounds for correctness, and fake results do not turn into real model observations. Time sources and new facts that altered judgments are also distinguished.

Existing goals keep their starting formats, and omitted new items remain unrecorded. Past completions are never overwritten, nor are past observations backfilled. This reporting format is included starting with Seal 0.1.12 and is present in the current release v0.1.8. See the synthetic reporting example (Korean).

Assurance policy#

If required independent reviews or actual boundary evidence are missing, completion is withheld; unrelated work can continue.

From Seal 0.1.20 the SPEC's Assurance: tier sets the independent review stages:

• standard takes the candidate, fixes and cumulative rounds, strict adds a plan round before any baseline, and light may skip review with a reason.
• When project instructions ask for more review, Seal follows them.

A goal that needs independent review runs ha done only once a cumulative round over the whole last head ends with no open finding (usage guide).

The scope of the assurance policy and a synthetic case

The assurance policy introduced in Seal 0.1.11 links the required scope of an assurance policy specified by a goal or project to conditions. Optional comparisons record unobserved scope and limitations. The executor decides the model and execution order; Core does not treat reviewers' agreement as sufficient evidence.

The synthetic assurance case (Korean) is an example of linking the contract, not an actual model observation.

Post-completion finding documents#

The new reporting format in Seal 0.1.12 preserves the original completion report while linking subsequent findings to target versions, conditions, reproduction scope, judgment history, and rework requests. Unresolved findings and historical completions can be displayed at the same time. Document status does not substitute for Core structured queries or concurrent change handling; finding records alone do not resume execution or change budgets. The synthetic finding history (Korean) is not an actual run record.