@matteeh/osq 0.2.1 → 0.2.2

package/README.md

@@ -22,6 +22,12 @@ Run `osq init --refresh-schema` to pick up a new OpenSpec schema. It overwrites
 
 ## Upgrading
 
+To 0.2.2:
+
+- The opencode adapter needs opencode 2. `osq doctor` and the watcher's preflight refuse opencode 1.
+- A config file that exists but fails to import or validate now stops every command with `Error: Failed to load <path>: <message>` and exit 1. Earlier releases carried on with the defaults.
+- The managed `AGENTS.md` and `PLANNER.md` blocks changed. Run `osq init` to refresh them; until you do, `osq doctor` reports the drift.
+
 Resolver 2 changes the automated done-marker hashes for active changes. On the first watcher cycle after upgrading, a completed task in an active change whose `.run/done/<n>` lacks `scope_resolver: 2` is detected even when its recorded aggregate hash still matches. This is a one-time recertification wave: the watcher runs each affected task's `verify` at detection, writes one idempotent `.run/regressed/<n>.md` scope-regression marker carrying the recorded and current resolver versions, and halts the change. Review each marker and run `osq retry <id> <task>` to recertify that task explicitly; a passing verification refreshes the marker with resolver-2 hashes. Markers inside `openspec/changes/archive/` are not rewritten or audited by this migration.
 
 ## What it puts in your repo
@@ -41,7 +47,7 @@ openspec/
   specs/           living capability specifications (e.g. cli-foundation/spec.md)
   changes/
     042-order-cancellation/
-      proposal.md  parent spec: goal, verify, non-goals, contract, human steps, delta
+      proposal.md  parent spec: goal, verify, non-goals, surface, decisions, contract, human steps, delta
       plan-prompt.md  the planning prompt `osq plan` writes; removed at archive
       tasks.md     task checklist, ticked by the watcher
       tasks/1.md   unit of work: acceptance, verify, scope, entry, tests.modify, verify_starts
@@ -73,13 +79,14 @@ Smart models author specs and never execute them. Cheap models execute specs and
 ## Gates and permissions
 
 - **Approval gate.** Nothing runs until a human runs `osq approve`. It lints the change, hashes the folder, and writes `.run/approved` plus `.run/manifest.json`.
-- **Approval digest.** Before sealing, `osq approve` prints a short digest: the goal, one line per task with its resolved-scope file count, and the requirements each delta adds, modifies, or removes. It then flags six things worth a human look: `shared_file` (a path two tasks share), `sensitive_path` (a package manifest, lockfile, CI workflow, osq or OpenSpec config, managed instruction file, or env file in scope), `verify_without_test` (a verify naming no test file or runner), `removed_requirement` (a delta that removes requirements), `unknown_capability` (a delta for a capability with no living spec that either has no `## Purpose` or has a name resembling a living capability, and the label names which; a deliberate new capability instead prints `(new capability)` on its digest heading), and `verify_starts_conflict` (a task that declares `green` or `any` while its verify names a missing test its own scope creates). Flags never block by default: they print last, as information, and the approval line names them (`Approved <id> with N flags: ...`). Add `--confirm` to stop and ask about them instead.
+- **Approval digest.** Before sealing, `osq approve` prints a short digest: the goal, one line per task with its resolved-scope file count, and the requirements each delta adds, modifies, or removes. It then flags eight things worth a human look: `shared_file` (a path two tasks share), `sensitive_path` (a package manifest, lockfile, CI workflow, osq or OpenSpec config, managed instruction file, or env file in scope), `verify_without_test` (a verify naming no test file or runner), `removed_requirement` (a delta that removes requirements), `unknown_capability` (a delta for a capability with no living spec that either has no `## Purpose` or has a name resembling a living capability, and the label names which; a deliberate new capability instead prints `(new capability)` on its digest heading), `verify_starts_conflict` (a task that declares `green` or `any` while its verify names a missing test its own scope creates), `adr_departure` (a `Departs from ADR <n>:` line in `## Decisions`), and `adr_check_modified` (a task that may change an ADR's check file; see Architecture decisions). Flags never block by default: they print last, as information, and the approval line names them (`Approved <id> with N flags: ...`). Add `--confirm` to stop and ask about them instead.
 - **Verification gate.** The watcher never trusts the agent's claim. It runs each task's `verify` in its own process after the agent exits and writes `.run/done/<n>` only on exit 0; a non-zero exit becomes `.run/dead/<n>.md`.
 - **Change verification after every task.** When the task's `verify` passes, the watcher also runs the proposal's change-level `verify` (`gates.changeVerifyAfterTask`, on by default). A red result kills the task with `change_verify_red`, so every task must leave the whole change green.
+- **Baseline verify.** When `gates.baselineVerify` names a command, the watcher runs it once in the project root before a change's first task spawns, to prove the tree was green before the change started. A non-zero exit kills the first task with `baseline_red` and prints "tree was red before this change started"; no agent spawns and the reason waits for `osq retry`. Under git, when HEAD and every dirty file outside a `.run/` folder are unchanged since the latest green baseline in any active or archived change, the watcher reuses it and records `baseline_ran` with `outcome: reused` instead of running the command; outside git, or with no commit, the command always runs.
 - **Pre-spawn verify check.** Before a task's first attempt, the watcher runs that task's `verify` once and expects it to fail: a verify already green before any agent work means the work is done or the verify does not exercise the task. A task declares its expected start with `verify_starts` — `red` by default, `green` for work like a refactor that should already pass, or `any` when either is fine. A mismatch warns by default and the task continues; `gates.preSpawnVerify: fail` kills the task with `verify_precondition` before the agent spawns, and `off` disables the check. A mismatch shows in the task's `verify_ran` event, `osq show`, and `osq report`. A named path the verify refers to that does not exist yet is recorded as `missingPaths` on that event and does not count as a mismatch for a `red` task. The check adds one extra verify per task, on its first attempt only.
-- **Automatic retry.** When a task dies for a reason a fresh attempt could fix — `verify_red`, `change_verify_red`, `undeclared_test_change`, `verify_path_missing`, `no_result`, `crashed`, or `timeout` — the watcher retries it without asking. Every other reason (`spec_conflict`, `verify_precondition`, `already_running`) waits for you. `gates.autoRetries` caps how many automatic retries a task gets since its approval or its last manual retry; it defaults to 1, `0` turns automatic retries off entirely, and a manual `osq retry` grants one more. Each retry's prompt carries the previous dead marker's body, so the fresh agent sees exactly what failed.
+- **Automatic retry.** When a task dies for a reason a fresh attempt could fix — `verify_red`, `change_verify_red`, `undeclared_test_change`, `verify_path_missing`, `denied_dependency`, `no_result`, `crashed`, or `timeout` — the watcher retries it without asking. Every other reason (`spec_conflict`, `verify_precondition`, `already_running`, `blocked`, `baseline_red`) waits for you. `gates.autoRetries` caps how many automatic retries a task gets since its approval or its last manual retry; it defaults to 1, `0` turns automatic retries off entirely, and a manual `osq retry` grants one more. Each retry's prompt carries the previous dead marker's body, so the fresh agent sees exactly what failed.
 - **Stuck tasks.** Every dead marker records a `fingerprint` over its reason and body, ignoring details a rerun changes: ISO timestamps, durations, PIDs, ANSI codes, and absolute paths under the project root. When a task dies again with the same fingerprint as its most recent retained death, the watcher stops retrying and marks it stuck — `stuck: true` on the active marker, one `stuck` event, one line. The inbox shows the task as stuck and `osq --json` gives its `task-dead` item a `stuck` field carrying the fingerprint; `osq retry <id> <n>` still retries it after you fix the cause.
-- **Scope recertification.** Before each task and again before archiving, the watcher re-hashes the resolved `scope` of every done task. If a later task changed any of those files, it re-runs that task's `verify`, writes `.run/regressed/<n>.md`, and halts the change until you run `osq retry <id> <n>`.
+- **Scope recertification.** Before each task and again before archiving, the watcher re-hashes the resolved `scope` of every done task. When a later task whose `scope` covers a changed file changed it, the recorded hashes show nothing else did, and the task's `verify` still passes, the watcher recertifies that task by itself. Every other change halts the change until you run `osq retry <id> <n>`.
 - **Archive verification.** Before archiving, the watcher re-runs every task's `verify` and the change-level `verify` against the final tree, halting with `.run/regressed/<n>.md` (or `.run/regressed/change.md`) if any fails.
 - **State from disk.** The only authoritative state is which marker files exist under `.run/`: `running/<n>.pid`, `done/<n>`, `dead/<n>.md`, `regressed/<n>.md`, and `approved`. There is no in-memory state that matters, so the watcher can be killed and restarted at any time.
 - **Executor permissions.** A coding agent may write only `.run/results/<n>.md` and files inside its task's `scope`. It may not edit living capability specs, `tasks.md`, or marker files. The watcher writes markers and checkboxes automatically; a human writes the rest through `osq approve`, `osq retry`, `osq reject`, and `osq done`.
@@ -101,12 +108,17 @@ features:
 ## Verify
 ## Non-goals
 ## Surface
+## Decisions
 ## Contract
 ## Human steps
+### Before approval
+### After landing
 ## Delta
 ```
 
-The frontmatter `verify` is the change-level command the watcher runs after every task and before archiving. Capability writes are not declared in frontmatter: the set of delta specs under `specs/<capability>/spec.md` is the authoritative declaration of what the change writes.
+The frontmatter `verify` is the change-level command the watcher runs after every task and before archiving. An optional `fixes` list names the changes this one reworks; lint fails on an id that names no active, archived, or rejected change, and `fixes` never affects execution order. Capability writes are not declared in frontmatter: the set of delta specs under `specs/<capability>/spec.md` is the authoritative declaration of what the change writes.
+
+`## Human steps` holds what osq cannot do. Steps under `### Before approval` show in the approval digest and on the inbox's approval item. Steps under `### After landing`, or a `check: <command>` in the frontmatter, leave the change **verification pending** once it archives: changes that depend on it wait until you run `osq check <id>` (for a `check` command) and record the outcome with `osq verified <id> --passed` or `--failed`. `osq status`, `osq show`, and the inbox list pending changes with their next command. Write `None` under a heading with no steps.
 
 `## Surface` lists the user-facing names the change adds, changes, or removes — commands, flags, config keys, frontmatter fields, document sections, dead reasons, and event types; a change with none of those writes `None`.
 
@@ -146,7 +158,9 @@ skills: []
 
 Tasks run in order. The agent reads its task, the parent `proposal.md`, the delta specs and capability docs it names, `AGENTS.md`, and a previous result file for that task if there is one. The runner also injects capability-specific constraints and code ownership rules extracted from living capability specs. The delta is applied by the watcher, so the agent never edits living specs under `openspec/specs/`.
 
-Lint, run by `osq approve` and `osq lint`. Limits come from `osq.config.ts`; defaults are shown.
+Before exiting, the agent writes `.run/results/<n>.md` with these headings, leaving out any that would be empty: `## Changed`, `## Deviated` (for the reviewer), `## Missing context` (for the planner), `## Outside scope` (for the human), `## Blocked`, and `## Next`, ending with a `Touched: <paths>` line. A task that cannot finish within its scope writes what it needs under `## Blocked` and no code; the watcher records it dead with reason `blocked`, never retries it automatically, and the inbox shows the stated need. `osq show` prints each task's disclosures, and the plan prompt quotes those from recent archived changes, bounded by `planning.disclosures.recentChanges` (default 3) and `planning.disclosures.maxCharacters` (default 4000).
+
+Lint, run by `osq approve` and `osq lint`. Limits come from `osq.config.ts`; defaults are shown. `osq lint` prints each finding as `<change>: <severity> <file> (<requirement or section>): <message>`, with repository-wide findings in their own group at the end, and `osq lint --json` prints them as JSON.
 
 | Check | Result |
 | --- | --- |
@@ -154,6 +168,7 @@ Lint, run by `osq approve` and `osq lint`. Limits come from `osq.config.ts`; def
 | proposal declares `features.writes` | reject |
 | more than one table under `## Contract` | reject |
 | `depends_on` names a missing change | reject |
+| `fixes` names a missing change | reject |
 | task `scope` has more than 8 patterns (`limits.maxScopeFiles`) | reject |
 | task acceptance longer than 7 lines (`limits.maxAcceptanceLines`), or two lines fused into one | reject |
 | task scope names a preexisting test without `tests.modify: true` | reject |
@@ -162,14 +177,140 @@ Lint, run by `osq approve` and `osq lint`. Limits come from `osq.config.ts`; def
 | `verify` names an absent package script | reject |
 | `verify` names no existing path or package script | warn |
 | a delta targets a requirement the living spec lacks, or is written as an instruction | reject |
+| a project with ADRs has no usable `## Decisions` section (`None` with no governing ADR passes) | reject |
+| `## Decisions` omits an accepted ADR that governs a capability the change writes | reject |
+| the AGENTS.md project rules block is stale or exceeds `limits.maxProjectRules` | reject |
+| `## Decisions` names an ADR that does not exist or is not accepted | warn |
 | a file contains a prohibited control character | reject |
 | OpenSpec schema or validator drift | reject |
 | two tasks resolve the same scope file | warn |
+| a task scope reaches a preexisting test no task may modify (`limits.importGraphDepth`) | warn |
+| a scoped file imports code owned by a capability the proposal neither reads nor has a delta for | warn |
+| a scoped file is owned by a capability with no delta in the change | warn |
+| a task `verify` runs only tests that import nothing in the task's scope | warn |
 
 `osq init` and `osq new` seed `verify: node -e "process.exit(0)"`. That is a planning sentinel, not trusted coverage: replace it before approval with a command that verifies the completed change's final tree. Checked-in fixtures use a local `node verify.cjs` verifier backed by files in their own execution root, never the sentinel, the network, a TTY, or this repository's full verification suite.
 
 The rules lint can't check live in the managed `PLANNER.md` block: titles read "When X, Y"; every task leaves the change green on its own; a file belongs to one task; approve the task list before writing any task in full.
 
+### Architecture decisions
+
+Architecture decision records live under `paths.decisions` (default `decisions/`). A markdown file there is an ADR when its YAML frontmatter carries `status` (`proposed`, `accepted`, or `superseded`); its number is the leading digits of the file name, its title the first `# ` heading without that number prefix. Only accepted ADRs take effect. An accepted ADR states `applies_to`, either `all` or a list of capability names, and a one-line `rule`; a superseded ADR states `superseded_by`. `limits.maxRuleLength` (default 160) caps a rule's length. A file without frontmatter is ignored and reported.
+
+`osq init` writes the rules block for every accepted system-wide ADR into `AGENTS.md` between `<!-- OSQ:RULES:START -->` and `<!-- OSQ:RULES:END -->`: a `## Project rules` heading and one `- <rule> ADR <number>` line per ADR, in number order. `limits.maxProjectRules` (default 10) caps how many lines the block may hold. The `decisions` check in `osq doctor` validates every ADR, fails on a stale or oversized rules block, and warns about ignored files and capability names with no living spec.
+
+When the project has any ADR with osq frontmatter, every proposal needs a `## Decisions` section after `## Surface`. Name each accepted ADR that governs a capability the change writes, or write `None` when none does. A departure line begins `Departs from ADR <n>:` and gives the reason. `osq lint` and `osq approve` reject a missing or empty section, reject an unnamed governing ADR, and fail while the AGENTS.md rules block is out of date.
+
+An accepted ADR may also name `checks`, the repository-relative test files that enforce it, and `denies`, the package names it forbids. A check path is trimmed, uses forward slashes, and drops a leading `./`; only accepted ADRs' checks and denials take effect. The `decisions` doctor check fails when an accepted ADR names a check file that does not exist. When a task declares `tests.modify: true` and its resolved scope covers an accepted ADR's check file, approval raises one `adr_check_modified` flag labelled `task <n> may modify a check of ADR <number>`, and `osq report` counts it in `approvalFlags.byFlag`.
+
+After an agent exits, the watcher compares each scoped `package.json` against the baseline recorded on the attempt's `measures` start event. A new package appends one `dependencies_added` event; if an accepted ADR denies it, the task dies with `denied_dependency`, eligible for one automatic retry, and the marker names each package, file, ADR, and rule. `osq show` prints a `Dependencies added: <name> (<file>), ...` line under such a task, and `osq report` prints a `Dependencies added:` section with one `<change>: <name> (<file>), ...` line per change that added packages.
+
+### Traceability
+
+Opt a capability in through the `traceability` block in `osq.config.ts`:
+
+```ts
+export default defineConfig({
+  traceability: {
+    capabilities: ['pricing'], // or 'all'
+    mode: 'warn',              // or 'require'
+    focusedTests: 'node --test --test-reporter=tap {files}', // optional
+  },
+});
+```
+
+The resolved config always holds `traceability`, defaulting to `{ capabilities: [], mode: 'warn' }`. With no capability opted in, `osq init`, `osq lint`, `osq report`, and both managed blocks are exactly what they were, and a project that never imports the helper sees no change.
+
+When at least one capability is opted in, `osq init` writes a `<!-- OSQ:TRACEABILITY:START -->` … `<!-- OSQ:TRACEABILITY:END -->` block directly after the managed block in `AGENTS.md` and `PLANNER.md`. Its scope is `every capability` for `'all'`, otherwise the opted-in names joined by `, `. Removing the opt-in removes the block and restores both files.
+
+A test proves a scenario by importing from `@matteeh/osq/testing`:
+
+```ts
+import { scenario } from '@matteeh/osq/testing';
+
+scenario('pricing', 'Volume pricing', { covers: quote }, ({ run, then, each }) => {
+  then('the subtotal is 1800.00', () => assert.equal(run(100).subtotal, 1800));
+  each('the unit price follows this table', (row) => assert.equal(quote(+row.quantity).unit, +row['unit price']));
+});
+```
+
+`scenario(capability, name, { covers }, body)` registers one `node:test` test titled `Scenario: <name>`. It fails unless the covered function ran through `run`, every outcome was asserted by a `then` or `each` that completed, and every table row passed. `run` takes the covered function's parameters and returns its result, `then(outcome, check)` asserts one outcome, and `each(outcome, check)` calls the check once per table row, in order, with the row as an object keyed by the header cells. The helper's failure messages are exact: a missing name is `"<text>" is not a THEN of this scenario`; a `then` on a table is `THEN <text>: has a table, so check it with each`; an `each` on a non-table is `THEN <text>: has no table`; a failed check is `THEN <text>: failed` or `THEN <text>: failed at <column> <value>, ...`; a check before the function ran or settled is `THEN <text>: checked before <fn> ran` or `THEN <text>: checked before <fn> settled`; a body that never called `run` is `<fn> never ran`; and a missing assertion is `No assertion for: <text>; <text>`. A lookup failure is reported unchanged.
+
+A scenario with more than one case puts a Markdown table directly under its THEN or AND line, with only blank lines between:
+
+```
+- **THEN** the unit price follows this table
+
+  | quantity | unit price |
+  | -------- | ---------- |
+  | 100      | 9.00       |
+  | 500      | 8.00       |
+```
+
+The first row names the columns, the dashes row is skipped, and later rows are keyed by the trimmed header cells with trimmed string values. Lint accepts a table under a THEN or AND line in a delta and in a living spec.
+
+Lint reads tags only from a `/** ... */` doc comment directly above `export function`/`export async function`, or `export const <name>` bound to an arrow or function expression. A `@scenario <capability>: <scenario name>` line names a scenario the function serves; `@adr <number>` names a decision it follows. A file is a scenario test file when it imports from `@matteeh/osq/testing`, and its `scenario(` calls are read when capability and name are string literals and the third argument is `{ covers: <identifier> }`; anything else is reported as unreadable as `<file>:<line>: <reason>`.
+
+A task lists the scenarios its tests prove under `## Scenarios`, one `- <capability>: <scenario name>` bullet each. A listed scenario counts as planned while the task's resolved scope holds a test path, so lint passes before the test exists; once a scoped test names it, only real `scenario(...)` calls count.
+
+The watcher sets `OSQ_CHANGE` to the absolute change folder for every verify, so the helper resolves scenarios from the change's delta while it is still active. `osq check` on an archived change runs without it, because its deltas are already in the living spec.
+
+For an opted-in capability, `osq lint` reports each scenario an ADDED or MODIFIED requirement holds that no scoped test names and that is not planned (`<capability>: no test names scenario "<name>"`), a `@scenario` tag naming a missing scenario (`<fn>: names a scenario the <capability> spec doesn't have: "<name>"`) or one no test covers (`<fn>: no test for "<name>" covers it`), a bad `@adr` tag (`<fn>: ADR <n> doesn't exist or isn't accepted`, `<fn>: ADR <n> doesn't apply to any capability it serves`), and a duplicate scenario name (`<capability>: two scenarios named "<name>"`). For every capability it also lists the tests naming a scenario a MODIFIED or REMOVED requirement changes and warns `<file> names changed scenario "<name>" but no task scopes it with tests.modify: true`. Every finding is a warning under `mode: 'warn'` and an error under `mode: 'require'`.
+
+When a capability is opted in, `osq report` prints a `Traceability:` section with `<capability>: <n> untested scenarios, <m> unclaimed functions` and `    untested: <name>` / `    unclaimed: <file>#<name>` lines, also carried in JSON under `traceability`. `osq show` prints `      Scenarios: <capability>: <name>; ...` under a task whose scoped tests name scenarios.
+
+Set the optional `traceability.focusedTests` to a command containing `{files}`, such as the reference `node --test --test-reporter=tap {files}`, to run a task's scenario tests before its full verify. When a task's resolved scope holds scenario test files naming opted-in scenarios, the watcher replaces `{files}` with every scenario test file in the repository that names one of those scenarios, each single-quoted and separated by spaces, and runs it through the verify's environment, `OSQ_CHANGE` included. The outcome is `passed` when the command succeeds, `failed` when the TAP output has a `not ok` line for a collected `Scenario: <name>`, and `problem` when it exits nonzero, times out, or cannot start and isn't `failed`. Only a `failed` outcome ends the attempt: the task dies with `verify_red` and its verify is skipped, so the next attempt receives the focused output; a `problem` or `passed` outcome goes on to the full verify, which alone decides the task. Each run appends one `focused_ran` event carrying the command, files, scenarios, outcome, exit code, duration, timeout state, and output. `osq show` prints `      Focused runs: <outcome> <duration>s, ...` under the task after its `Scenarios:` line, adding ` (attempt ended, verify skipped)` to each `failed` entry.
+
+### Mutation checks
+
+Set the optional `traceability.mutation` block to the project's mutation command
+and an optional per-task budget in seconds (default `300`):
+
+```ts
+export default defineConfig({
+  traceability: {
+    capabilities: ['pricing'], // or 'all'
+    mode: 'warn',
+    mutation: {
+      command: 'npx stryker run', // or a command using {mutate}, {tests}, {report}
+      budgetSeconds: 300,         // optional
+    },
+  },
+});
+```
+
+After a task passes, osq picks the covered functions the task changed or newly tested. A covered function is an exported function carrying a `@scenario` tag naming an opted-in capability whose tagged scenario a scenario test file names. A function is picked when its file is in the task's resolved scope and its own range's hash differs from the task's last start `measures` event's `functionHashes` entry (a missing entry counts as different), or when a scenario test file the task changed covers it.
+
+Each run gets that function's own range plus the range of every non-exported top-level function in the same file it calls, sorted by start line as `<file>:<start>-<end>`, and the sorted, distinct scenario test files naming its tagged scenarios. The command is run once per pick through the verify's environment, `OSQ_CHANGE` included, and receives:
+
+- `{mutate}` and `OSQ_MUTATE`: the ranges, comma-joined for the placeholder and a JSON array for the variable
+- `{tests}` and `OSQ_MUTATION_TESTS`: the tests, single-quoted and space-separated for the placeholder and a JSON array for the variable
+- `{report}` and `OSQ_MUTATION_REPORT`: an absolute path in a fresh temporary folder, single-quoted for the placeholder
+
+Each run's timeout is the budget left, and picks left once `budgetSeconds` of total wall time for the task is spent are not run. Each pick appends one `mutation_ran` event to the task's stream with `file`, `function`, `ranges`, `scenarios`, `tests`, `outcome`, `killed`, `survived`, `invalid`, `survivors`, `duration`, and `exitCode`. When a pick can't be measured the event says why: `range_unknown` (unknown ranges), `budget`, `timed_out`, `command_failed`, or `report_invalid`; a failed or timed-out run also carries the command's last 2,000 output characters. The check is observe only: it never fails, retries, or halts a task.
+
+`osq show` prints, under a task whose stream holds `mutation_ran` events after its last `measures` start event, `      Mutation: <entry>; <entry>` with one entry per event in stream order. A measured entry is `<file>#<function> <killed> of <killed + survived> killed`, a not-measured one is `<file>#<function> not measured (<reason>)`, and each survivor adds a `        Survived: <file>:<line>:<column> <mutator> -> <replacement>` line. When a capability is opted in, `osq report` prints a `Mutation:` section with `  <capability>: <killed> of <killed + survived> killed (<percent>%), <n> survivors not yet reviewed`, the percent to one decimal, then a `    survived: ...` line per survivor, also carried under `mutation` in JSON. Every listed survivor counts as not yet reviewed.
+
+The reference setup uses StrykerJS with its command test runner. Add `@stryker-mutator/core` as a dev dependency of the project, set `traceability.mutation.command` to `npx stryker run`, and add this `stryker.config.mjs`:
+
+```js
+const tests = JSON.parse(process.env.OSQ_MUTATION_TESTS ?? '[]')
+  .map((file) => `'build/${file.replace(/\.(m|c)?ts$/, (_, k) => `.${k ?? ''}js`)}'`)
+  .join(' ');
+export default {
+  testRunner: 'command',
+  commandRunner: { command: `node --test ${tests}` },
+  buildCommand: 'npx tsc',
+  mutate: JSON.parse(process.env.OSQ_MUTATE ?? '[]'),
+  coverageAnalysis: 'off',
+  reporters: ['json'],
+  jsonReporter: { fileName: process.env.OSQ_MUTATION_REPORT },
+  tempDirName: '.stryker-tmp',
+};
+```
+
+The config assumes `tsc` compiles `tests/` to `build/tests/`; follow the project's own layout if it differs. Leave `thresholds.break` unset so survivors never change the command's exit code, and add `.stryker-tmp` to `.gitignore`.
+
 ## What the watcher guarantees
 
 - **Rebuilt from disk**: State is rebuilt from `openspec/` on every change. Kill it and restart it any time.
@@ -182,17 +323,40 @@ The rules lint can't check live in the managed `PLANNER.md` block: titles read "
 - **Deterministic spec merges**: Capability specs are only ever changed by the watcher applying an approved delta merge (ADR 002). Agents never touch `openspec/specs/`.
 - **Synthesized results**: An agent that exits without writing `.run/results/<n>.md` is not lost: if the adapter captured a final text message, the watcher synthesizes a result file (`synthesized: true`) from it and proceeds to verify. Only an exit with neither a result file nor final text is `dead` with `reason: no_result`. Nothing disappears silently.
 
-Dead reasons: `verify_red` (with `timed_out: true` if verify exceeded its timeout), `change_verify_red`, `verify_precondition`, `undeclared_test_change`, `verify_path_missing` (a path the task's `verify` names did not exist after the agent exited), `no_result`, `crashed`, `timeout`, `spec_conflict`, and `already_running`. A done task whose scoped files changed afterwards is recorded under `.run/regressed/<n>.md` with `reason: scope_regression`, and a failed archive-time change verify under `.run/regressed/change.md`; either stops the run before the next task spawns. Every dead marker also carries a `fingerprint` of its reason and body, and a marker the watcher stopped retrying carries `stuck: true`.
+Dead reasons: `verify_red` (with `timed_out: true` if verify exceeded its timeout), `change_verify_red`, `verify_precondition`, `baseline_red` (the configured baseline verify failed before the change's first task), `undeclared_test_change`, `verify_path_missing` (a path the task's `verify` names did not exist after the agent exited), `denied_dependency` (a scoped `package.json` gained a package an accepted ADR denies; retried automatically once), `blocked` (the agent wrote `## Blocked` in its result; never retried automatically), `no_result`, `crashed`, `timeout`, `spec_conflict`, and `already_running`. A done task whose scoped files changed afterwards is recorded under `.run/regressed/<n>.md` with `reason: scope_regression`, and a failed archive-time change verify under `.run/regressed/change.md`; either stops the run before the next task spawns. Every dead marker also carries a `fingerprint` of its reason and body, and a marker the watcher stopped retrying carries `stuck: true`.
+
+## Version control
+
+osq reads git when it is available: `osq doctor` reports it, baseline reuse compares HEAD, and the watcher records `scope_violation` and `vcs_violation` events. Agents never run git. osq makes no git writes unless `vcs.enabled` is true, and in this release that support is **unfinished**. Leave it off.
+
+```ts
+export default defineConfig({
+  vcs: {
+    enabled: false,                  // default; no git writes
+    author: 'osq <osq@example.com>', // required when enabled
+    // defaultBranch: 'main',        // approval's base branch when origin has no HEAD; default main
+    // worktreeRoot: '~/.osq/worktrees',
+    // prepare: 'pnpm install',      // run once in each new worktree
+  },
+  timeouts: {
+    gitSeconds: 10,        // each git read
+    gitCommitSeconds: 120, // each commit
+  },
+});
+```
+
+With `vcs.enabled`, `osq approve` creates branch `osq/<folder>` and a linked worktree under `vcs.worktreeRoot`, runs `vcs.prepare` there, writes the seal plus `.run/base` and `.run/approver` into the worktree's copy, commits `osq: <id> approved`, and prints `Worktree:` and `Branch:` lines. Your checkout is left untouched, and `osq status` warns when the checkout's copy of the change is edited afterwards. The watcher does not yet run changes in their worktrees, so a change approved this way does not run.
 
 ## Harnesses
 
-`OSQ_HARNESS` picks an adapter. An adapter does two things: spawn an agent for a tier (`coding` or `smart`) and write its harness's config files (`osq setup`). Adapters translate the harness's own event stream into typed events (`started`, `tokens`, `tool`, `text`, `file_changed`, `result_written`, `exited`), and the watcher appends its own (`measures`, `verify_ran`, `done`, `done_manual`, `dead`, `regressed`, `retry`, `recertification`, `rejected`), all to the task's `.run/events/<n>.jsonl`. Hooks are optional shims that append to the same file. The loop works without them.
+`OSQ_HARNESS` picks an adapter. An adapter does two things: spawn an agent for a tier (`coding` or `smart`) and write its harness's config files (`osq setup`). Adapters translate the harness's own event stream into typed events (`started`, `tokens`, `tool`, `text`, `file_changed`, `result_written`, `exited`), and the watcher appends its own, among them `measures`, `verify_ran`, `baseline_ran`, `focused_ran`, `mutation_ran`, `dependencies_added`, `done`, `done_manual`, `dead`, `stuck`, `regressed`, `retry`, `recertification`, and `rejected`, to the task's `.run/events/<n>.jsonl`. Change-level events such as `archived`, `check_ran`, and `verification_recorded` go to `.run/events/change.jsonl`. Hooks are optional shims that append to the same file. The loop works without them.
 
 Available adapters:
 
 - `agy`: Antigravity harness adapter
+- `claude`: Claude Code harness adapter running fresh headless `claude -p` tasks
 - `codex`: Codex CLI harness adapter running tasks via `codex exec` and planning via the Codex TUI
-- `opencode`: OpenCode harness adapter running tasks via `opencode run`
+- `opencode`: OpenCode harness adapter running tasks via `opencode run` (requires opencode 2)
 - `pi`: Pi coding agent harness adapter running fresh one-shot tasks in JSON mode
 - `mock`: In-memory deterministic simulation for tests
 
@@ -207,11 +371,13 @@ export default defineConfig({
     bin: 'opencode',
     model: 'deepseek/deepseek-flash',
     agent: 'osq-coder',
-    variant: 'thinking', // optional
+    variant: 'thinking', // optional; passed as <model>#<variant>
   },
 });
 ```
 
+The adapter needs opencode 2; `osq doctor` reports a failing `harness-version` check for opencode 1 and a warning above the tested range. Tasks run with `opencode run --standalone` from the project root, and a configured `variant` is appended to the model as `<model>#<variant>`.
+
 Running `osq setup` with the `opencode` harness scaffolds `.opencode/agent/osq-coder.md` with restricted permissions (denying `webfetch` and `websearch`) and the managed `AGENTS.md` execution procedure. Note that the `--auto` flag approves any action the agent file does not deny. The agent file must have mode `all` or `primary`; a subagent cannot be selected with --agent and OpenCode silently falls back to an unrestricted default. `webfetch` and `websearch` are denied at the tool level, but `bash` is allowed and unrestricted, so the agent can reach the network through the shell. Network isolation requires a sandbox, which osq does not provide.
 
 ### Codex CLI
@@ -306,6 +472,46 @@ As with every harness, scope is a protocol, not confinement: the prompt and the
 
 Pi cannot plan: the adapter has no interactive session, so `osq plan --session` with Pi selected as the planner stops with the existing "does not support interactive sessions" error, and `planner.agent` is unsupported for Pi and rejected by configuration validation.
 
+### Claude Code
+
+Select Claude Code as the executor in `osq.config.ts`:
+
+```ts
+import { defineConfig } from '@matteeh/osq';
+
+export default defineConfig({
+  harness: 'claude',
+  claude: {
+    // All fields are optional; omit any to use Claude Code's native value.
+    // bin: '/path/to/claude',  // claude.bin -> `claude`
+    // model: '<your-model>',   // claude.model -> OSQ_MODEL (Claude executor only) -> native
+    // sandbox: true,           // confine Bash with Claude Code's OS sandbox (needs bubblewrap and socat)
+  },
+});
+```
+
+Setting `OSQ_HARNESS=claude` in the environment or `.env` also selects Claude Code, but an explicit `harness` in `osq.config.ts` wins over that fallback. Binary precedence is `claude.bin`, then `claude` on `PATH`. Model precedence is `claude.model`, then `OSQ_MODEL` only when Claude Code is the executor, then Claude Code's native default; with no model configured, osq records `default` rather than guessing one. This release requires Claude Code `2.1.278` or newer, the version every flag below was verified on; `osq doctor`'s `harness-version` check and the watcher's preflight both fail under it.
+
+Each task is a fresh `claude -p --output-format stream-json --verbose` process in the project root with stdin closed and `--no-session-persistence`, so there is no session to resume.
+
+#### Claude Code setup and prerequisites
+
+Install the Claude Code CLI and log in as usual: by default osq reuses your Claude Code login. When `ANTHROPIC_API_KEY` is set to a non-empty value, osq adds `--bare` and uses the key instead; `--bare` never reads your login, which is why it is tied to the key. The `started` event records which one ran through `harnessAuth`: `api_key` with a key and `login` otherwise.
+
+`osq setup` writes no Claude Code files for execution; it only maintains the shared managed `AGENTS.md` block. Planning with Claude Code uses the tool-native `/osq-plan` command that `osq init` installs, not this adapter.
+
+#### Claude Code stripped tool surface
+
+Each task loads only six built-in tools: `Bash`, `Read`, `Edit`, `Write`, `Glob`, and `Grep`. osq passes `--tools Bash,Read,Edit,Write,Glob,Grep`, `--strict-mcp-config` with no `--mcp-config`, `--disable-slash-commands`, `--setting-sources ""`, `--no-session-persistence`, and `--settings '{"autoMemoryEnabled":false}'`. That strips MCP servers, skills, plugins, hooks, user, project and local settings, saved sessions, and auto-memory so the agent pays no tokens for harness features a coding task never uses: measured on a one-line prompt, input fell from about 29,500 to about 13,300 tokens per request. No configuration key re-enables any of them.
+
+#### Claude Code permissions
+
+Executor tasks run with `--permission-mode dontAsk`, so anything not allowed is denied rather than prompting. `Read`, `Glob`, and `Grep` are allowed; `Edit` and `Write` are confined to the project through `Edit(./**)` and `Write(./**)`; `Bash` is allowed but `git` is denied by `Bash(git:*)`, which still denies `git` inside compound commands such as `echo a && git status`.
+
+Without `claude.sandbox`, Bash is not confined: a shell command can still write outside the project or reach the network. Set `claude.sandbox: true` to add Claude Code's Bash sandbox with no network. It fails at startup if the sandbox is unavailable instead of running unconfined, and on Linux and WSL2 it needs the OS packages `bubblewrap` and `socat` (`apt install bubblewrap socat`).
+
+As with every harness, scope is a protocol, not confinement beyond what the harness itself enforces.
+
 ## Commands
 
 ```
@@ -317,11 +523,13 @@ osq setup                write harness config for OSQ_HARNESS
 osq new <name>           new change folder from template in openspec/changes/
 osq plan [name]          create a change, write plan-prompt.md, and hand off to your planning tool
 osq queue                print the read-only brief queue from openspec/queue.md
-osq lint [ids...]        validate change folders and OpenSpec artifacts against constraints
+osq lint [ids...]        validate change folders and OpenSpec artifacts against constraints (--json for JSON)
 osq approve <ids...>     lint, print the digest, approve change; write .run/approved and .run/manifest.json
 osq retry <id> <target>  retry a dead or regressed task, or a change-level regression
 osq reject <id>          move an unapproved or failed change intact into rejected history
 osq done <id> <task>     mark a task done manually with required justification (--manual)
+osq check <id>           run an archived change's recorded check command
+osq verified <id>        record an after-landing outcome (--passed or --failed, optional --note <text>)
 osq watch                run the watcher loop
 osq status               overview of all changes, tasks, and runtime states
 osq show <id>            change details, tasks, results, dead markers, and event timeline (--json for JSON)
@@ -335,14 +543,19 @@ osq migrate openspec     migrate a legacy osq layout to the canonical openspec/
 ### Approval
 
 ```sh
-osq approve <id> --confirm   # show the digest, then ask about any flags before sealing
-osq show <id> --json         # details, tasks, events, and the digest as JSON
+osq approve <id> --confirm      # show the digest, then ask about any flags before sealing
+osq approve <id> --base-ok      # approve even when HEAD is not the default branch
+osq approve <id> --ignore-dirty # approve despite uncommitted changes in task scope
+osq show <id> --json            # details, tasks, events, and the digest as JSON
 ```
 
 By default `osq approve` prints the digest and its flags, then approves without
 asking; flags never block. `--confirm` asks only when flags fire, defaults to no,
 and refuses without a terminal rather than waiting. A declined or refused approval
 writes nothing, and `--confirm` on a flag-free change approves without a prompt.
+With `vcs.enabled`, approve normally requires HEAD on the default branch and a
+clean checkout in task scope; `--base-ok` and `--ignore-dirty` override those
+two refusals.
 `osq show <id> --json` prints the same details as JSON, with the digest and flags
 for an unapproved change and a null digest once it is approved.
 
@@ -502,7 +715,13 @@ Run `osq doctor` to verify repository health:
 
 - `config`: confirms `osq.config.ts` is valid and well-formed
 - `harness`: checks that the configured harness binary (e.g. `opencode`, `agy`) exists and is executable
-- `harness-version`, `harness-auth`: Pi's extra checks (only when Pi is selected) warn on an untested Pi version and, with `pi.provider` set, fail unless `pi auth check` reports `ready`
+- `harness-version`: the installed harness's version. Pi warns outside its tested range; Claude Code fails under `2.1.278`; opencode fails under 2 and warns from 3
+- `harness-auth`: with Pi and `pi.provider` set, fails unless `pi auth check` reports `ready`
+- `harness-containment`: with Claude Code, states what confines the agent's Bash
+- `decisions`: validates every ADR, the AGENTS.md rules block, and each accepted ADR's check files
+- `planning-prices`: warns, only when it applies, that a model with recorded planning tokens has no price in `planning.prices`
+- `git`: git's version, or a warning saying why git is off. `git-env` warns when a variable such as `GIT_DIR` is set
+- `vcs-prepare`, `git-hooks`, `git-signing`: with `vcs.enabled` only, warn about a lockfile without `vcs.prepare`, active commit hooks, and commit signing
 - `managed-blocks`: verifies the `AGENTS.md`, `PLANNER.md`, and `.claude/commands/osq-plan.md` managed sections match the installed osq version (run `osq init` to repair drift)
 - `locks`: checks for orphaned `.run/running/*.pid` locks and processes
 - `archives`: validates integrity of archived change folders
@@ -515,7 +734,7 @@ To release a new version of `osq`:
 
 1. Bump `"version"` in `package.json`.
 2. Add a corresponding release section in `CHANGELOG.md`.
-3. Commit the changes: `git commit -am "release: v<x.y.z>"`.
+3. Commit the changes: `git commit -am "chore: release <x.y.z>"`.
 4. Create and push the release tag: `git tag v<x.y.z> && git push --tags`.
 5. GitHub Actions (`release.yml`) verifies the build and publishes to npm with provenance via trusted publishing.
 

package/dist/cli/approve.d.ts

@@ -1,3 +1,4 @@
+import type { Command } from 'commander';
 import { type OsqConfig } from '../core/foundation/config.js';
 import type { PlanningSessionReader } from '../core/report/planning-observed.js';
 export interface ApproveCommandOptions {
@@ -7,10 +8,16 @@ export interface ApproveCommandOptions {
     now?: Date | string;
     /** Block on flagged approvals by asking before the seal is written. */
     confirm?: boolean;
+    /** Approve from a branch other than the default branch. */
+    baseOk?: boolean;
+    /** Approve despite uncommitted changes covered by a task's scope. */
+    ignoreDirty?: boolean;
     /** Injectable terminal check; defaults to both stdio streams being TTYs. */
     isTerminal?: () => boolean;
     /** Injectable prompt; defaults to a `node:readline/promises` question. */
     ask?: (question: string) => Promise<string | null>;
 }
 export declare function approveCommand(specIds: string[], options?: ApproveCommandOptions): Promise<void>;
+/** Register `osq approve` and its approval-only flags. */
+export declare function registerApproveCommand(program: Command): void;
 //# sourceMappingURL=approve.d.ts.map

package/dist/cli/approve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"approve.d.ts","sourceRoot":"","sources":["../../src/cli/approve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAc,MAAM,8BAA8B,CAAC;AAE1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAajF,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,eAAe,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAC3B,0EAA0E;IAC1E,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACpD;AA0BD,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAsDf"}
+{"version":3,"file":"approve.d.ts","sourceRoot":"","sources":["../../src/cli/approve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,KAAK,SAAS,EAAc,MAAM,8BAA8B,CAAC;AAE1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAgBjF,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,eAAe,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAC3B,0EAA0E;IAC1E,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACpD;AA0BD,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAoEf;AAED,0DAA0D;AAC1D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmB7D"}

package/dist/cli/approve.js

@@ -1,7 +1,10 @@
 import { loadConfig } from '../core/foundation/config.js';
 import { resolveHarnessExecutable } from '../core/foundation/harness-catalog.js';
+import { formatPriceKey } from '../core/report/planning-price-gaps.js';
 import { approveSpec } from '../core/spec/approve.js';
 import { formatApprovalDigest, formatApprovalFlags, summarizeApprovalFlags, } from '../core/spec/digest.js';
+import { findChange } from '../core/status/change-locations.js';
+import { formatNextStep, readNextStep } from '../core/status/next-step.js';
 import { readClaudePlanningSessions } from '../harness/claude/claude-usage.js';
 import { readCodexPlanningSessions } from '../harness/codex/codex-observe-usage.js';
 import { readOpencodePlanningSessions } from '../harness/opencode/opencode-observe-usage.js';
@@ -60,22 +63,53 @@ export async function approveCommand(specIds, options = {}) {
                 planningReaders,
                 now: options.now,
                 review,
+                baseOk: options.baseOk,
+                ignoreDirty: options.ignoreDirty,
             });
             const summary = summarizeApprovalFlags(result.digest.flags);
             console.log(`Approved ${result.specId} (${result.folderName})${summary ? ` with ${summary}` : ''}`);
             console.log(`  Hash: ${result.hash}`);
+            if (result.worktreePath !== undefined && result.branch !== undefined) {
+                console.log(`  Worktree: ${result.worktreePath}`);
+                console.log(`  Branch: ${result.branch}`);
+            }
             for (const warning of result.warnings) {
                 console.warn(`  Warning: ${warning}`);
             }
             if (result.planningMatches === 0) {
                 console.log(`No planning record found for ${result.specId}.`);
             }
+            for (const model of result.missingPrices) {
+                console.log(`Planning cost for ${model} stays unreported; add ${formatPriceKey(model)}.`);
+            }
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             console.error(`Error approving ${specId}:\n  ${message}`);
+            try {
+                const { folderPath } = await findChange(cwd, config, specId);
+                const nextStep = await readNextStep(cwd, folderPath, config);
+                console.log(`Next: ${formatNextStep(nextStep)}`);
+            }
+            catch { }
             process.exit(1);
         }
     }
 }
+/** Register `osq approve` and its approval-only flags. */
+export function registerApproveCommand(program) {
+    program
+        .command('approve <ids...>')
+        .description('lint, hash, and approve change folders')
+        .option('--confirm', 'ask about approval flags before sealing')
+        .option('--base-ok', 'approve even when HEAD is not the default branch')
+        .option('--ignore-dirty', 'approve despite uncommitted changes in task scope')
+        .action(async (ids, options) => {
+        await approveCommand(ids, {
+            confirm: options.confirm,
+            baseOk: options.baseOk,
+            ignoreDirty: options.ignoreDirty,
+        });
+    });
+}
 //# sourceMappingURL=approve.js.map

package/dist/cli/approve.js.map

@@ -1 +1 @@
-{"version":3,"file":"approve.js","sourceRoot":"","sources":["../../src/cli/approve.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"approve.js","sourceRoot":"","sources":["../../src/cli/approve.ts"],"names":[],"mappings":"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"}

package/dist/cli/bin.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { createProgram, resolvePackageVersion } from './index.js';
-const program = createProgram(resolvePackageVersion());
-await program.parseAsync(process.argv);
+import { runCli } from './run.js';
+await runCli(process.argv);
 //# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAElE,MAAM,OAAO,GAAG,aAAa,CAAC,qBAAqB,EAAE,CAAC,CAAC;AACvD,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/cli/check.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from 'commander';
+import { type OsqConfig } from '../core/foundation/config.js';
+export interface CheckCommandOptions {
+    cwd?: string;
+    config?: OsqConfig;
+}
+/**
+ * Run an archived change's recorded `check` command once, append one
+ * `check_ran` event, print the result and next step, and exit zero only when
+ * the check passed. A refusal writes nothing.
+ */
+export declare function checkCommand(specId: string, options?: CheckCommandOptions): Promise<void>;
+/** Register `osq check` and `osq verified` on the root program. */
+export declare function registerVerificationCommands(program: Command): void;
+//# sourceMappingURL=check.d.ts.map

package/dist/cli/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/cli/check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,KAAK,SAAS,EAAc,MAAM,8BAA8B,CAAC;AAK1E,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AA4BD;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CAcf;AAED,mEAAmE;AACnE,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiBnE"}