Usage guide

한국어 · English

Look here to change a goal, continue one after a conversation ends, answer what Seal asks, or read a completion report. New here? Read Understanding Jaekit and your first task in the README first. The first six sections follow one goal from start to finish: sending commands, changing or continuing a goal, what Seal asks and the review order, reading the completion report, the files left behind, and troubleshooting. The sections after them are for when you want the details of reports, the review gate, cost and budgets.

Why Jaekit works this way is in Understanding Jaekit; installation, updates, and removal are in the install guide.

Sending commands#

Send these in the agent conversation, not Terminal. Replace <request> with the work you want and <goal> with the goal folder name Spec reports.

In Codex, type $, select spec:spec or seal:seal installed from Jaekit, then add your request.

@Spec is a plugin mention. Use the skill invocation above to explicitly select Spec's instructions for writing goal documents only; a plugin mention alone does not guarantee the same instructions are selected.

The host agent can also call Spec: when you ask it to work through Jaekit or goal documents ("do this with jaekit"), or when a review finding can only be resolved by changing a requirement. Spec then writes a Draft document with a Proposed-By: agent line, or an amendment document under amendments/, and asks whether you accept it. The agent does not call Spec for an ordinary implementation request or bug report. Whoever called Spec, Ready and the start of implementation come only from your words.

Changing a goal or continuing#

Read Spec's report, then answer or ask for changes to revise the same document. Spec saves the goal, scope, and completion conditions directly to docs/specs/<goal>/SPEC.md, reports what it wrote and any decisions it made with their sources, then stops.

Even if you also ask it to implement the work, it only writes the goal documents. Decisions Spec proposes become yours when you accept them or ask to implement that goal.

If a goal already covers the same behavior and you have not chosen which document to write, Spec first asks whether to create a new goal or edit the existing one.

• Status: Draft: an outcome-changing decision remains, and Spec asks about it.
• Status: Ready: the document is ready. It does not start implementation by itself.
• Assurance:: how much independent review the implementer must get. Use light for small fixes, standard for ordinary changes, and strict for goals that change a public contract, stored data, permissions, or a boundary between components. Spec proposes a tier and reports why. To use another tier, say so, for example "make it strict".

When no outcome-changing decision is left, Spec ends its report with a separate question: it asks whether to implement now, naming the goal path and its tier. If you answer yes, implementation starts. If your answer also asks for a change ("yes, but drop AC-2"), Spec edits the documents first and asks again. The start command still works, and you can also tell Seal Implement docs/specs/<goal> instead of using the start command. You do not approve each step during the work. Answer decisions that affect the outcome and conditions that need your own confirmation.

If the conversation ends, open a new one in the same project folder and send the following. Seal reads the saved goal, plan, progress, and current state, then continues the remaining work.

continue docs/specs/<goal>

Seal's pre-start checks and review order#

Seal asks the decisions it can foresee once, before it starts, and during work only the questions that come up new. Below is when it asks what, and in what order independent review comes for each review tier.

What Seal asks before the start#

• One budget question. When the request names no budget, Seal writes 검증 실행: 자동 in PLAN. Within the pre-approved limit it starts without asking; above it, Seal asks once, showing the computed and pre-approved limits.
  • The number you give goes into PLAN, and the same PLAN never gets the question again.
  • Seal does not write or change ha.json.
• Environment check before the start. When checks use a browser, database, container or external service, Seal lists it in the PLAN section ## 실행 환경 and runs ha doctor before recording any baseline and, after a resume, before the next check. It gathers unavailable tools into one question and never widens permissions or settings on its own.
• Questions before the start, in one message. From Seal 0.1.23, before recording any baseline, Seal gathers the decisions it can foresee from the goal documents, the plan, the project instructions and the code that need your words, and asks them in one message. When there is nothing to ask, Seal asks nothing and starts the work.
  • Examples are a plan that changes a file on a protected path, a change to an existing test that the request does not authorize, a place where the goal documents and the code seem to disagree, unusable tools and a budget that needs approval.
  • Each question gives its options, the recommended one leading, and what the answer changes.
  • When a condition can be met only by your confirmation, the same message names it and what you will be asked to confirm at the end.
  • Test and check files the plan will add are in 바꿀 수 있는 경로 from the start, so adding them raises no scope question later.

Questions during work, and reports#

• Later questions when they arise. A question no one could foresee, such as a requirement-question from review or a round cap, is asked when it arises; questions pending at the same moment go in one message. The confirmations needed at the end are also asked together in one message, once the results exist.
  • Having asked early does not by itself confirm a change outside Seal's authority or one that weakens a check.
  • Seal records an answer given up front as the confirmation, quoting it, once the change it allows is committed, and does not ask about that change again.
  • When the confirmed content changes later, that is a new change and Seal asks again.
• Five-line report. Goals started with 0.1.20 or later use ha report in PROGRESS.md. ## 현재 opens with the ha report stamp, pasted unchanged; Seal does not type the time.
  • In ## 완료 보고, read the five lines at the top (Changed, Checked, To review, Remaining limits, Next step), 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 ## 검수 요약.
  • A Korean request gets --lang ko.

Review order by tier#

The SPEC's Assurance: line sets the independent review stages. Spar decides how a review runs; Seal decides when and what happens with the findings.

The cumulative round is a candidate round over the whole change, from the goal's base commit to the last head. In a goal under review, Seal runs ha done only once that round ends with no open defect or requirement-question.

• When project instructions such as AGENTS.md ask for more review, Seal follows them and says so in the completion report.
• A goal without the line keeps the selected assurance policy as before.
• When you ask for remote review comments to be applied after completion, Seal records reopen, fixes, runs one cumulative round, re-records stale checks and runs ha done again.

Reading the completion report#

Start with what changed and what was verified. The report appears in the conversation and in PROGRESS.md in the goal folder.

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.

• Required completion conditions need recorded checks or necessary user confirmations.
• Optional conditions do not block completion and are identified separately.
• The agent writes the automated checks.

What to do next#

Use the ha status / ha done result to find your next step. The numbers are exit codes. A complete from ha status alone is not a completion: until the output names a completion record, Seal records one with ha done.

flowchart LR
    S["ha status / ha done"] -->|complete · 0| R{"Completion record?"}
    R -->|"none yet"| D["Seal runs ha done"]
    R -->|"seq N"| C["Review the result"]
    S -->|incomplete · 1| I["Let Seal keep working"]
    S -->|needs_user · 2| U["Answer the question"]
    S -->|blocked · 3| B["Fix the cause, then send<br/>continue docs/specs/#lt;goal#gt;"]
    S -->|budget_exhausted · 4| E["Decide on the budget"]
    S -->|"error · 64+"| X["Read the error message,<br/>then see Troubleshooting"]
    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

Exit codes 64 and above are errors, not work statuses: 64 for a usage error, 65 for a refusal such as a goal that has not started or a broken record, 66 for a rule version the Core does not support, and 70 for an internal error. Read the message, then see Troubleshooting.

Completion evidence and rework#

Review the assumptions, changed checks, remaining limitations, and the actual result together. The evidence of completion is the record written by ha done.

The assurance level local refers to evidence obtained on that computer. An agent with the same user permissions can change the checks and records, so it is not independent third-party verification.

The operations guide gives the detailed review procedure.

If something is missing, say what needs fixing. Seal records the rework request and continues. If the goal document itself needs changing, revise it with Spec and then separately ask to continue.

Seal's default result currently ends at local changes and commits (saved entries in the change history). You can push and create pull requests yourself or ask a general-purpose agent separately. Jaekit does not provide an independent verification environment or unattended operation.

Saved files#

Find the goal and its records in docs/specs/<goal>/:

• Git tracking: follow project policy. Commit these files when the project tracks them; keep them locally when the project treats them as private or ignored. Do not force ignored documents into Git.
• Before publishing: a commit saves history locally; publishing it is a separate step. Records can include user statements and working paths, so review them before sending them to a public repository.
• Jaekit's policy: this repository's own private docs/ policy is not a requirement for other projects.
• Raw output: check output stays local in .git/ha/, which Git does not track. You do not need to add anything to .gitignore.
• Linked worktrees: in a separate working folder sharing the same Git history, output is under ha/ in the Git directory printed by git rev-parse --absolute-git-dir.
• Read output: run ha log <goal> <seq> in Terminal. Here <goal> is the goal path, and <seq> is the record number from the report.
• Run timing: use ha timing <goal> to see which checks took long and how close they came to their time limit. It requires a Core with capability run-timing/v1; measurement details are below.
• Decision history: with capability decision-history/v1, Seal can keep summaries, evidence and correction links in the optional decision history. Use ha history <goal> for current judgments, or ha history <goal> show <event ID> for one event's evidence and neighboring links.

Troubleshooting#

The operations guide describes the detailed reasons for user confirmation, blocked work, and budget stops. The steps above cover what you need to respond and continue.

Reports and tool checks#

ha report <goal> summarizes a goal's state in five lines. It prints English by default and Korean with --lang ko. It only reads the same computation as ha status and never changes the record.

When Git cannot compare the base with HEAD, as in a shallow clone without the base commit, it prints only the five lines and exits 70. Next step then says how to fetch the base (for example git fetch --unshallow).

After the summary come a stamp to copy into ## 현재 in PROGRESS.md (the record head's seq and hash, the recorded time and the status), the evidence per condition, the completion coverage, and where the output of unmet conditions is (ha log <goal> <seq>). A synthetic example:

Changed: 2 files and 2 commits outside the bundle documents since base 3c1f0a9e7b25
Checked: 2 of 2 required conditions satisfied (2 by check records, 0 by user confirmation); 1 of 1 change conditions have a fresh baseline
To review: none
Remaining limits: assurance local; check author: executor
Next step: none; completion record seq 5 holds and nothing is left to do

To check the tools your checks need beforehand, add a ## 실행 환경 section to PLAN with one tool per line in the form - <이름>: `<점검 명령>` (a tool name, a colon, and its check command in one code span).

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

ha doctor <goal> runs these check commands in order with a 60-second limit each and prints 사용 가능 (available) or 사용 불가 (<reason>) (unavailable) for each tool. For an unavailable tool, the end of its output follows. It works before the start too, and leaves nothing in the record or the run count. A malformed line is reported with its file and line, and then no check runs. Judgments never read this section.

Review gate (run-rules/5)#

From v0.1.7, Seal (0.1.21 or later) starts new goals with ha start --rules run-rules/5. run-rules/5 keeps all of run-rules/4's autonomy and adds a recorded independent review as a completion condition for goals whose SPEC tier is standard or strict. So a standard or strict goal started under run-rules/5 completes only with a recorded Spar gate. light goals, goals without an Assurance: line and goals started under run-rules/4 or earlier do not need Spar. To finish without review, you decide a goal-document change that lowers the tier to light (see the list below).

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.

• Once the cumulative round ends with no open finding, Seal makes a gate with spar gate from that series' rounds for HEAD, records the gate file with ha note <goal> review --gate <file>, and then runs ha done. The record keeps the file digest and the summary the judgment needs, never the findings' text.
• Without a gate the status shows review_missing; with a commit after the review, review_head_stale; when the goal documents changed after the review or a round did not receive them all, review_docs_stale. Completion is not recorded. A blocked or degraded gate, an open defect or requirement-question, a gate with no code round, and a strict goal with no plan round each have their own reason too. User confirmations and other notes do not stand in for a gate.
• To finish without review when Spar cannot run, you decide a SPEC change that lowers the tier to Assurance: light. After confirm spec and fresh checks, the goal completes without a gate.
• A light goal, a goal without the tier line, and goals started under run-rules/1 to run-rules/4 are judged without a gate, as before.

Seal 0.1.26 starts new goals with ha start --rules run-rules/6 … --check-skill instead of the start rule above. This needs a Core that supports run-rules/6; ha 0.1.8 does not. Without support, Seal stops without a record and does not fall back to earlier rules. /6 changes only these four judgments from /5.

• The last candidate round (excluding dry runs) for a standard or strict goal must review from the start record's base_commit. A mismatch gives review_base_mismatch with the gate seq and both bases and blocks completion. A gate with only fixes rounds gives the same reason. Fixes may follow a candidate from the start base; Spar checks their chain. reopen does not move the start base.
• For a light goal or one without a tier line, a review note after completion leaves an otherwise valid completion record in place. For standard and strict, the record is invalidated and the new gate is judged, as before.
• 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.
• Budget elapsed time excludes the interval from a completion done to the next check or baseline start or a non-complete done. With neither endpoint, it ends at the window's last budget record; notes and findings in between do not end it. post_completion_seconds shows the additional excluded seconds that do not overlap reported waits or run intervals; status, report and cost use the same elapsed time. Run counts and limits stay unchanged; code rework after completion opens a new window with reopen.

Goals started under run-rules/1 through run-rules/5 keep their existing judgments and are not migrated automatically. The exact interval and output definitions are in the run record contract.

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 one goal's cost#

ha cost <goal> gathers what one goal cost in verification and review on one screen. It only reads records and writes nothing; it never reads the current time and calls no model. It reads Spar review records only from the series folders you name with --series. It does not guess where they are, so give --series once per series.

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

• Kind and size: the tier, the rules version, the required and optional criteria, the files and commits changed since the base (the same as Changed in ha report), and a valid completion record.
• Verification: runs and their time, runs per condition, and for each re-recorded run the inputs that differ from the run before it (code, goal documents, verification command, overlaid check files). When no input differs, it shows the earlier run's result. The budget window shows the values ha status shows.
• Questions and waits: each reported wait with the decision it asked and its length, Spar's requirement-question findings with their answers, cap extensions and reviewer waivers. They are counted by source and listed. Whether one was a scope or authority decision or a needless re-check is for the person reading the list to judge.
• Review rounds and findings: rounds by stage (counted rounds and reruns), reviewer time, findings by class and location with their dispositions, and the lines fixes rounds added (the gate's growth). Without --series, these parts say they were not given and show no zeros.
• Tokens: no record holds them, so they show as "not recorded".

--format json shows the same values as a cost/v1 document, and --lang ko changes only labels and sentences. The format and the source of each value are in the run record contract §1.7.

When you compare. The summary shows numbers only; it never compares the goal with another or says it improved. To compare goals, put goals of the same tier and similar size (criteria, changed files and commits) side by side. A difference between a few goals before and after a process change mixes in what each goal was about and chance, so it is not a causal effect of that change.

Automatic budget#

If the plan's ## 예산 gives the run count as - 검증 실행: 자동 (automatic) instead of a number, ha start sets the limit. The limit is max(50, ⌈required minimum × 1.5⌉): up to run-rules/6, a goal with 34 required change conditions needs at least 68 runs and gets a limit of 102. You still write 경과 시간 (elapsed time) yourself. A plan with a number works as before.

When the computed limit is at or below the limit you approved in advance, the goal starts without a question. Write that pre-approved limit once in ha.json in your user configuration folder: ~/.config/jaekit/, or $XDG_CONFIG_HOME/jaekit/ when XDG_CONFIG_HOME is set. Without the file, the limit is 50 runs. No file inside a repository can set this limit. To check that, ha lists the working trees with git worktree list -z when the file exists, which needs Git 2.36 or later.

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

The home is the HOME environment variable when it is set, otherwise USERPROFILE on Windows. In Windows PowerShell, pick the folder in the same order:

$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 shows the same computed limit before the start, and whether your approval is needed. When the computed limit is above your limit, ha start records nothing and stops:

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

If you approve that count, write it as a number in the plan or raise preapproved_runs in ha.json. A malformed or unreadable file stops with ha: pre-approved run limit: <path>: <reason>; it is never replaced by 50. The limit applies only to the start; raising the limit and reopening after the start work as before. The exact rules are in the run record contract.

Autonomy (run-rules/4)#

Starting with Seal 0.1.16, Seal starts new goals with ha start --rules run-rules/4 when the Core supports run-rules/4 and its five features. The Core's default rule stays run-rules/3, and a goal that has already started keeps the rule it started with. Under the new rule, Seal does not ask again about work the authority it already has covers.

• When your request allows test changes inside the scope, Seal records its reading with --test-authority. When it changes or moves an existing test, it records which conditions the file checks and how with ha note <goal> test-change, and the change needs no confirmation. A weakening change or one outside the scope still asks for your confirmation.
• While it waits for your answer to a question, it reports the wait with ha note <goal> wait, and records resume if it continues without the answer. Only reported waits leave the budget's elapsed time.
• A run limit you approve in advance is recorded with ha budget <goal> --preapprove; within it, Seal raises the limit with a reason.
• When a check passed its error limit because of something Seal can fix in how it runs, such as a missing tool, Seal records recover. Each condition and input allows two; allow-recovery lets you allow more. Earlier failures stay in the record.
• A long check gets its own limit, up to two hours, in the plan's ## 시간 제한 section. When an earlier run reached or neared its limit, a notice appears before the run.

Verification reporting format#

The reporting format introduced in Seal 0.1.10 separates these four things in the existing review and report:

• Expected-result grounds.
• Observation boundaries.
• Methods and substitutes.
• Unobserved scope.

Condition groups may share an explanation; a plan is not an observation. The current release v0.1.8 includes this format in Seal 0.1.23; existing goal formats stay unchanged.

See the synthetic reporting example; it is not an actual execution record.

Release and rules#

The current release v0.1.8 combines ha 0.1.8, spar 0.1.8, spec 0.1.13, seal 0.1.23 and the spar plugin 0.1.4. The default rules are /3; Seal starts new goals under run-rules/4 from 0.1.16 and under run-rules/5 from 0.1.21. Preflight refusal, run estimation, /3 result classification and budget policy apply to this release. Existing goals keep their saved rules. See Release and development combinations.

Rules (run-rules/N) are the version of how ha computes a goal's records. A goal is computed under the rules it started with until it ends, so a new ha does not change the meaning of a goal in progress.

The Seal skill body went from about 4,600 words to at most 2,200 words. Seal 0.1.23 raised that limit to 2,300 words to add the pre-start question rule. The formats of goals started with an earlier Seal moved to a reference read only when continuing such a goal (references/earlier-goals.md); the records and documents of those goals do not change.