# Changelog

## v0.12.0 - Approved runs

### Added

- Approved runs: a human approves a plan once, and the agent works it without asking about what the plan approved. The plan names what it needs in a fenced `heli-run` block (`branch`, `push`, `remote`, `hours`, `keep-going`); `heli run approve plan.md` (an interactive terminal only; the hooks refuse an agent-run one) shows what the run allows and what stays blocked, then records it in Heli's own data directory, bound to the agent session working near the plan. A run with `push: yes` issues a `git.push` grant limited to that branch of that remote: every push a command makes must land, unforced, on it (Heli asks git where a bare `git push` or `HEAD` goes); `main`, `master` and the remote's default branch are refused at approval; tags, `--all`, deletions and `gh pr merge` are not covered; the grant is void as soon as the plan's text changes and revoked when the run ends. The agent reports with `heli run done`, `heli run blocked "<what it needs>"` (and `resume`), and anyone can `heli run stop` it. `heli run status` lists runs. Every other block (T6, `.env`, publish/tag/deploy approvals, Heli's state, the project's governance files) is unchanged. Grants can carry a `constraint` generally. Pinned by `scripts/smoke-constrained-push.mjs` and `scripts/smoke-approved-runs.mjs`.
- A Claude Code Stop hook keeps an agent working its approved run. When the agent is about to end its turn, the session an active run is bound to gets `{"decision":"block"}` with its next instruction: continue the plan, or end with `heli run done` / `heli run blocked "<what it needs>"`. Other sessions, blocked/done/stopped/expired runs and `keep-going: no` stop normally, at most 40 continuations per run, a user interrupt always wins, and the hook fails open. Other hosts get the approved-run grants without the Stop hook. Pinned by `scripts/smoke-run-stop-hook.mjs`.
- `HARNESS.md` tells agents how to ask for an approved run and how to work one.

### Security

- An agent can no longer change the rules it runs under. In a linked project, agent writes to `.heli/safety/**` (the command rules the hooks read on every call), `.heli/policies/**`, `.heli/workspace.json` and `.heli/heli.lock`, and moving or removing `.heli` itself, are refused with `HELI_POLICY_PROTECTED` for file tools, shell commands and MCP writes, under YOLO too. Before, an agent could delete a project T5/T6 rule, or the binding, mid-session. Reading them is fine; `.heli/profiles` and `.heli/skills` stay agent-writable; an embedded workspace (the Heli source checkout dogfoods one) is unchanged.
- Remote writes that are not spelled `git push` need approval too. `gh pr merge` and `glab mr merge` (which land a pull request on its base branch) and `git subtree push` now go through the push gate and the same `git.push` approval, with a reason that names the command. The shipped `command-rules.json` adds T5 rules for `gh release create`, `docker push`, `kubectl apply|delete` (not with `--dry-run=client|server`) and `terraform apply|destroy`; `heli update` merges them into existing projects. Pinned by `scripts/smoke-remote-writes.mjs`.
- `heli governance set` is human-only like `heli grant issue`: the CLI needs an interactive terminal and the hooks refuse an agent-run one, since `observe` switches the live write-conflict gate off for every session. Both pinned by `scripts/smoke-policy-protection.mjs`.

### Documentation

- Docs now describe what the code does: `command-tiers.md` says the hooks enforce T5/T6 rules (plus the push and `.env` gates) and that T0–T4 are guidance only (a T3/T4 entry in `command-rules.json` is not enforced); the governance model lists the grant fields that exist (issuer, action, resource, optional execution/session/time scope, once or reusable, revocation) and says delegation and N-use counts are not implemented; the README and `grant.mjs` no longer say every grant is bound to one execution (any checkout on the machine unless `--execution` pins one).
- The skills and current docs know about approved runs and the other new gates.
  - `heli-assistant`: how to set up unattended plan work, and how to read `keep going: off`, a push refused during a run, protected governance files and short write conflicts.
  - `heli-help` and `heli-governance`: list `heli run`, `heli governance` and the recovery classes.
  - `branch`, `gh-write` and `release`: what a run covers (its branch only; never a merge, a tag or a release command), and the shipped T5 release rules and their read-only forms.
  - The architecture index, governance model (grant constraints, approved runs), enforcement matrix (approved runs, keep-going, remote git writes, governance files, deny recovery, YOLO expiry), adapter matrix (the Claude Code Stop hook, the Codex marketplace refresh) and roadmap describe them.
  - Every list of human-only commands includes `heli run approve`.
  - `HARNESS.md` says any edit to an approved plan voids it, not only an edit to its `heli-run` block.

### Changed

- The protocol tells agents to keep going. `HARNESS.md` is rewritten linked-first (6.5 KB, was 15.7 KB): what the hooks enforce, what each deny recovery class asks of the agent, "end your turn when the work is done or when every remaining step needs the user", one two-strike rule (the same check failing twice after real fixes with no new information means write a short diagnosis and change approach, not stop), risk tiers, done criteria, skill triggers and the cloud-sync boundary. The embedded-only bookkeeping (`current-task.md` fields, `plan.md` evidence, resume card, task gates) moved to `HARNESS-embedded.md`, shipped and seeded with it. A linked SessionStart now carries these rules inline with the path of the packaged `HARNESS.md`, instead of telling the agent to read a `.heli-harness/HARNESS.md` the project does not have. Skills are read once per session; the `engineering`, `debug`, `fix-loop`, `impact` and `heli-assistant` skills continue the work after two strikes or a `HUMAN_REQUIRED` deny instead of stopping; the adapter instruction files no longer tell agents to "ask" for T3/T4 work, which nothing enforces. Pinned by `scripts/smoke-protocol-text.mjs`.
- Every deny says who can lift it, what to do next, and what to do meanwhile. Only ownership denies carried a recovery class, and they ended with "STOP"; every other deny was a bare reason, so agents could not tell a block they can clear themselves from one only the user can lift, and stopped to ask about all of them. Now every PreToolUse deny has `recoverability` (`SELF_RECOVERABLE`, `HUMAN_REQUIRED`, `HARD_DENY`), `nextAction` and `retryable: false`, and its reason ends with them and with the conduct for that class: clear it and continue without asking; ask once and keep working on what does not need the decision; or continue another way. The hook's fail-closed deny says `HUMAN_REQUIRED` too. Stuck-task/plan gate denies now have the code `TASK_GATE`. Pinned by `scripts/smoke-deny-recovery.mjs`.
- A write conflict with a short lease is waited out instead of escalated. Two agents in one worktree conflict whenever one runs a command whose files Heli cannot read (it locks the whole worktree, `/`, for 30 s after each such call), and the deny said a person must decide, so an agent stopped for a block that was gone seconds later. A conflict with a lease that lapses within a minute is now `SELF_RECOVERABLE` with `retryAfterSeconds`: wait, retry once, and ask the user only if the same blocker is back (the other session is still writing). Strict-mode resource leases and task leases still need the user; the call is denied while the lease is live either way.

### Fixed

- `heli migrate` says when it merged newly shipped rules into a workspace that is already on the current version. The status stayed `current` (it compares runtime versions only), so a run that added rules to every project's `.heli/safety/command-rules.json` read as if it changed nothing; each such workspace now gets a line naming the merged rule ids, and the safety merge result carries them (`added`). Pinned in `scripts/smoke-migrate-workspaces.mjs`.
- `heli host status` / `heli host update` no longer report an installed Codex plugin as absent. `codex plugin list` now prints the whole remote plugin catalog (about 2 MB), past Node's 1 MiB default output buffer, and the overflowed call read as a failed one ("codex: FAILED — plugin not detected"). Host CLI calls now take up to 64 MiB of output. Pinned by `scripts/smoke-host-large-output.mjs`; the fake host CLI writes its canned output synchronously so a large response is not cut short on macOS.
- `heli host update codex` installs the current Heli plugin. It ran `codex plugin marketplace add`, which Codex answers for a marketplace it already has with "already added" and fetches nothing, then reinstalled the plugin from the snapshot taken when the marketplace was first added, and reported "updated/verified". It now runs `codex plugin marketplace upgrade heli-harness` in between (install and repair too), and the manual commands in the Codex install guide are in that order. Pinned in `scripts/smoke-host-manager.mjs`.
- The diagnosis two-strike counter counts consecutive failures. It only ever grew (only a new failure class or a restart reset it), so after the first two strikes every later same-class failure forced another reroute; it now starts again after `heli diagnosis route` (two strikes per route) and after a passing run. An S2/S3 task whose diagnosis held only passing runs no longer needs an "established root cause" to complete: completion, like the write gate, asks for one only when a failure or a disputed premise activated the diagnosis. Pinned by `scripts/smoke-diagnosis-counters.mjs`.
- YOLO ends on its own, and sessions say when it is on. `heli yolo on` now expires after 8 hours unless `--hours N` or `--no-expiry` says otherwise (it used to stay on until `heli yolo off`), and while YOLO is on every linked SessionStart carries a warning with its source and expiry, what it lifts (push gate, `.env` writes, T5 approvals, stuck-task gates) and what it never lifts. `yolo-mode.md` now describes the linked-project file location, the session/task sources and the full lists of what YOLO lifts and keeps. Pinned by `scripts/smoke-yolo-expiry.mjs`.
- The grant a deny message asks for is the grant the hook looks for. In a workspace holding other git repositories (`heli-ws/repos/app`), a push from the nested repository is checked against its own worktree, but `heli grant issue` bound grants to the workspace root, so the user ran the suggested command and the agent was refused again. Deny messages now add `--resource <folder>` when the call is checked against a nested worktree; `--resource` accepts a folder as well as `workspace` or a resource id (and finds the workspace from it, so the command works from any terminal); and with no `--resource` a grant is for the worktree of the folder the command names or runs in. `heli grant --help` lists the real scopes (`once|session|workspace|time`). Pinned by `scripts/smoke-grant-resource.mjs`.
- The `.env` write gate guards the files that may hold secrets, not the templates committed on purpose: `.env.example`, `.env.sample`, `.env.template` and `.env.dist` (also after a stage, `.env.local.example`) no longer need an `env.write` grant, and direnv's `.envrc` is now guarded (also in the Pi extension). `.env`, `.env.<stage>`, files in a `.env.<x>/` folder, and copying a real `.env` anywhere are guarded as before. Pinned by `scripts/smoke-env-files.mjs`.
- Read-only forms of the shipped release rules no longer need a grant: `git tag` (bare), `git tag -l`/`--list`/`-n`/`--contains`/`--points-at`/`--merged`/`-v`, a bare `npm version` or `npm version --json`, `npm publish --dry-run` and `pnpm publish --dry-run`, and `heli sync auto`/`heli sync e2e` without `on`/`off`. `<rule words> --help` is help for every rules-file T5 rule. A read-only flag next to a writing one (`git tag -l -d v1`), `--dry-run=false`, or a project that rewrites a shipped rule's words still needs its approval; T6 rules have no exception. Pinned by `scripts/smoke-command-readonly.mjs`.
- Bash here-documents that a command only reads as data are no longer hard denies: a `git commit -F - <<'EOF'` message, a `gh pr create --body-file -` body or a `cat > script.sh <<'EOF'` script that mentions `rm -rf`, `git reset --hard` or `git push` is text, not commands. A body is still read as commands when anything in the command could run it (a shell, `eval`, `source`, a loop, `xargs`, a pipe or descriptor into a shell, `$(...)` in an unquoted body, a `VAR=` prefix such as `GIT_EDITOR=sh`, a git alias or config, a gh extension), and the command line around the body (`&& git push`, `> .env`) is read as before. Checked against the real bash in `scripts/smoke-command-heredocs.mjs`.
- Text run by a tool named for bash is matched against the command rules only the way bash reads it. Its Windows reading, where `\"` ends a quote (so `git commit -m "a \" rm -rf b"` read as a delete), now only feeds the protected-path write check, the push gate and force-push rule, and Heli's own self-protection rules: a push or an agent approving itself is still refused in every spelling. Shells Heli cannot name (MCP command tools, Codex `shell`, Monitor) are read as before. The Pi extension keeps its own guard and is unchanged.

## v0.11.2 - Global workspace migration

### Added

- `heli migrate` updates all linked workspaces listed in the machine-global locator registry to the installed Heli runtime, preserving operational authority.
- `--root`, `--discover`, `--depth`, `--dry-run`, and `--json` support nested development directories and recovery when the registry is missing.

### Fixed

- Migration can rebuild missing or malformed linked runtime locks and correctly handles stale registry paths on Windows without crossing the selected root.

## v0.11.1 - Linked source workspace resolution

### Added

- `heli migrate` migrates all registered linked workspaces to the currently installed global Heli runtime. `--root` filters a development tree, `--discover` recovers bindings from `.heli/workspace.json`, `--depth` bounds discovery, and `--dry-run` previews without mutating workspace or registry state.
- Linked migration repairs missing or malformed `.heli/heli.lock` files and refreshes project overlays/safety defaults without copying or resetting sessions, leases, grants, tasks, or runtime capability observations.

### Fixed

- Heli source/distribution checkouts nested under a linked parent no longer let packaged `.heli-harness/` content shadow the parent's explicit `.heli/` binding; ordinary embedded workspaces and standalone source checkouts keep their existing resolution behavior.

## v0.11.0 - Flow-first governance

### Added

- Governance profiles `flow` (default), `strict`, and `observe`, with `heli governance show` and `heli governance set`.
- Short-lived path-scoped mutation leases. A session is coordination identity, not a worktree mutex.
- `heli doctor --repair` releases closed, orphaned, and unknown stale authority, clears stale bindings, and normalizes safe path aliases without taking a live writer.
- Lazy session recovery when a linked write arrives without SessionStart. Missing hooks continue in degraded mode.
- Windows path-identity normalization prefers the native realpath and can collapse 8.3 and long-path aliases before containment checks.

### Changed

- Flow profile allows a write unless Heli can prove a live overlapping mutation or an existing destructive policy applies. Stale, closed, missing, and unknown authority is recovered instead of demanding takeover.
- Observe profile records those decisions and does not block ordinary writes. Strict profile keeps the previous fail-closed writer gate.
- Live overlap still blocks, with the owner, path, and last mutation activity. Non-overlapping live work is allowed.
- The Grok plugin closes the Heli session on `SessionEnd`, so a clean `grok -p` exit releases the mutation lease.

## v0.10.12 - Multi-repo host continuity

### Fixed

- CLI help is now first-class and read-only across command surfaces: `heli --help`, `heli help <command> [subcommand]`, `heli <command> --help`, and grouped subcommand help are intercepted before dispatch so commands such as `heli link --help` cannot mutate workspace state.

## v0.10.11 - Flow-first governance

### Changed

- Flow-first governance for normal development: a valid bound compatibility writer automatically establishes missing free writer authority instead of looping on `NO_LEASE`; live writer conflicts still fail closed and explicit review/observe intent is never silently upgraded.
- Ownership denials now carry recovery classification, `retryable=false`, a stable blocker fingerprint, and host-facing STOP guidance so agents do not burn usage retrying unchanged governance state.
- Read/recovery Heli control-plane commands remain usable while coding work is blocked; explicit takeover remains human-only.
- `heli-assistant` and SessionStart guidance teach the same recovery semantics and discourage using YOLO as a normal writer-authority workaround.

## v0.10.10 - Heli assistant and skill routing

### Added

- `heli-assistant` provides version/layout/state-aware situational guidance for Heli: it inspects only relevant CLI/state surfaces, explains the current workspace/session/host situation, recommends the smallest supported path, and routes to specialist skills without gaining authority.

### Changed

- Heli skill guidance is modernized around the linked v0.10 topology: npm-first install guidance, current command/help surfaces, task-optional linked workflows, canonical diagnosis CLI usage, and thin `/heli-*` wrappers that delegate to specialist skills instead of duplicating methodology.
- Release guidance now requires post-release proof across source/tag, exact registry version, release channel/dist-tag, and fresh-install/runtime version where applicable.

## v0.10.9 - Durable resume context for agent switching

### Added

- `heli resume` / `heli resume --json` provide a read-only continuation packet for switching coding hosts: workspace/execution/worktree, Git state, active tasks, dependency/handoff readiness, current writer authority, sessions, runtime observations, and non-orchestrating continuation guidance.

## v0.10.8 - Workspace task dependencies and artifact handoffs

### Added

- Workspace-scoped task dependencies and artifact handoffs with explicit `blocked` / `ready` coordination state, Git-ref snapshots, idempotent declaration/publication, and human + JSON CLI surfaces.

### Fixed

- Task/path/schema/event helpers honor fixture data-directory overrides so hermetic tests cannot spill linked workspace state into the user's real `~/.heli`; fixture cleanup refuses non-owned state roots.
- Native SessionStart callbacks retain host-session identity for later PreToolUse resolution without weakening worktree writer isolation.
- Release validation checks that runtime task/session/binding/lock directories are excluded from the npm allowlist instead of requiring live checkout state to be empty.

## v0.10.7 - Reliable approvals and host integration

### Fixed

- One `once` grant is spent at most once per host tool call. Grok runs the global Heli hook and the installed plugin on the same call; the later evaluation replays the recorded approval instead of denying.
- `heli host install grok` keeps one Heli hook source: with the plugin registered it skips the global hooks file, and `heli host repair grok` removes a duplicate global file. Status reports the hook topology and names duplicates.
- Human grants are workspace-wide by default (workspace + action + resource + usage/expiry) and match from any checkout of the workspace; `heli grant issue --execution <id>` pins one explicitly.
- A missing host binding names the host-plugin route first; the CLI write session is the fallback for hosts without the plugin.

## v0.10.6 - Workspace-shared task coordination

### Changed

- Linked task records are stored once per workspace. Every checkout of that workspace lists the same tasks. Sessions, writer leases, resource authority, grants, and capability observations stay on the execution.
- `heli explain authority` names the CLI session and the host writer separately.
- A linked write into a worktree that already has a writer names that session and resource.
- SessionStart records a `session_start` observation on the session it binds.

## v0.10.5 - Align linked host sessions and CLI state

### Fixed

- PreToolUse resumes the session SessionStart bound for that host, then stores the host session id. A linked Grok write no longer needs `HELI_SESSION_ID`. A different host's default session is not reused when an external id is present.
- PreToolUse records a `pre_tool` observation with the allow or deny decision when a session exists.
- `heli link` seeds `skills/` on a fresh linked project.
- `heli yolo` on a linked project uses the execution-local YOLO file and does not require `.heli-harness/HARNESS.md`. Turning YOLO on still requires a human terminal.
- `heli target show` reads the workspace target unless the active task names a repository.
- `heli task migrate-legacy` refuses an idle seed with `NO_LEGACY_STATE`. A real in-progress legacy task still migrates.
- `heli update` refreshes missing linked overlays and the runtime pin. `heli uninstall` removes the linked `.heli/` project and its registry row, and leaves host integrations in place.
- Install docs install from the published npm package and describe how a host obtains a write session.

## v0.10.4 - Phase 0 security hardening

### Security

- PreToolUse hooks fail closed: malformed or empty hook input, broken workspace state (for example an invalid `.heli/workspace.json`) and internal errors now produce a deny that points to `heli doctor`, instead of a crash the host treats as "allow". The decision is emitted before audit writes, so a failing audit write can no longer turn a deny into an allow.
- Every command rule is evaluated: any T6 match is a hard deny that scoped grants, YOLO and `HELI_ALLOW_COMMAND` cannot override, and each matched T5 rule needs its own approval. Grants are consumed only when the call is finally allowed.
- A built-in, non-removable T6 floor covers recursive forced deletes in any spelling (`rm -rf`/`-fr`/`-r -f`/`--recursive --force`, `rd /s`, `Remove-Item -Recurse -Force`), `git reset --hard`, `git clean -f` with `-d`/`-x` and unfiltered `find -delete`; `git push --force` needs its own `git-push-force` approval. Commands are normalized (quotes, escapes, `git -C/-c`, chains, `sh -c`/`bash -c`/`cmd /c`/`pwsh -Command` payloads) before matching. A missing or malformed `safety/command-rules.json` now denies shell commands instead of disabling every rule.
- Heli protects itself: agent-run `heli grant issue`, `heli yolo on`, task takeovers, write transfers, YOLO task/session flags and Heli removal are hard-denied; `heli grant issue` and `heli yolo on` require an interactive terminal; Heli authority state (task, session, lock, binding, YOLO and workspace records, `~/.heli`, Heli-installed host hooks) is not agent-writable under any path spelling, including `..`, casing, junction/symlink, alternate-data-stream and `\\?\` forms; settings that disable Claude Code hooks are denied; shell writes to `.env` files and protected paths are checked.
- Claude Code: the PreToolUse matcher covers `PowerShell` (the Windows default shell), `Monitor`, `NotebookEdit` and MCP tools, and the kernel recognizes PowerShell file-mutating cmdlets.
- Cloud sync (experimental): browser activation requires an explicit confirmation and binds the OAuth state to the confirming browser; pulls refuse plaintext when E2E is on, refuse rollbacks and relabeled ciphertext (bundles are bound to workspace id and version), and never apply `safety/`, `policies/` or task YOLO changes without `--accept-policy-changes`; portable bundle paths reject Windows trailing-dot/space aliases, NTFS streams and 8.3 spellings before policy classification; `heli init --clone` rejects unsafe repo paths and remotes.

### Changed

- PreToolUse hook timeouts are 30 seconds for every host; the Codex Windows fallback denies when `node` is missing; the Claude plugin no longer declares the Codex-only `commandWindows` field.
- `current-task.md` `Mode: yolo` no longer enables YOLO; a human runs `heli yolo on` in their own terminal.
- `workspace/target.json` is protected state; use `heli target set <repo>`.
- Atomic state writes retry transient Windows sharing violations instead of deleting the target first.
- Legacy unbound E2E bundles (`aes-256-gcm-scrypt`) are refused; re-push them from an updated client.

### Fixed

- The test suite is hermetic: host lifecycle tests run against fake host CLIs in a temporary home, host CLI calls always receive the caller's environment, and grant lookups no longer create directories under the real `~/.heli`.
- The release workflow fails when `NPM_TOKEN` is missing instead of reporting success without publishing; the release script bumps every current-facing version file and supports `--prepare-only`.
- Documentation currentness checks now cover two-digit minor versions.


## v0.10.3 - Pi runtime evidence distribution fix

### Fixed

- Pi package discovery now loads `extensions/pi-governed.js`, so real `session_start` and `tool_call` callbacks persist session-scoped runtime capability observations while preserving the existing Pi commands and guard decisions.
- The Pi runtime-evidence smoke imports the extension declared by `package.json` instead of hardcoding the governed wrapper, preventing distribution wiring from drifting away from the tested path.
- Missing required host CLIs now report `host-unavailable` consistently, and install output no longer duplicates `CLI` in labels such as Kimi Code CLI.

### Changed

- GitHub Actions checkout/setup-node actions use their current Node 24 runtime majors.
- Integration convergence validation now fails if the Pi package entrypoint regresses to the legacy non-observing extension.

## v0.10.2 - Global host integration convergence

### Changed

- Canonical onboarding is global Heli → `heli host install <host>` → project `heli link`; normal linked projects no longer depend on a copied `.heli-harness/` tree.
- Pi `/heli-install` now links the current project through lightweight `.heli/` state. Embedded workspace installation/update is explicitly named `/heli-legacy-install` and `/heli-legacy-update`.
- Host management now exposes version-aware `status`, idempotent `install`, `update`, `repair`, and scoped `remove` lifecycle operations.
- OpenCode, Cursor, Grok, Kimi, and conditional Antigravity installation/removal own only Heli-specific files or directories and preserve unrelated host configuration.
- Root metadata now declares `global-linked` as the default topology; the shipped `.heli-harness/manifest.json` is explicitly `embedded-compatibility`.
- Adapter support reporting now separates runtime, fresh install, global discovery, linked projects, update/repair, removal, automated E2E, live-host proof, and distribution currency.

### Added

- Fresh linked-project integration migration smoke covering no-local-harness setup, repeat install, stale upgrade, uninstall preservation, explicit compatibility mode, Pi regression behavior, and Heli-scoped host artifacts.
- CI architecture/version-convergence gate preventing legacy default onboarding, contradictory install metadata, Pi local-install regression, and release-train manifest skew.

### Release

- This migration is intended for the next patch release after CI and merge. External package/catalog publication is not inferred from source HEAD.

## v0.10.1 - Linked authority and host onboarding correction

### Fixed

- Fresh linked workspaces no longer use the embedded `CONCURRENT_BOOTSTRAP` exception when no named task exists; guarded writes now establish execution-local, resource-scoped authority for the resolved worktree.
- Resource authority now treats `taskId` as optional provenance, so ordinary reversible linked work can be governed without manufacturing a durable task record.
- `heli explain authority`, `heli status`, and `heli doctor` now project the linked resource-authority model instead of presenting task/lease compatibility terminology as the primary authority source.

### Added

- `heli host status|list|install` and `heli host install all` for machine-level host integration onboarding from the installed Heli distribution.
- Host installation/status coverage for Codex, Pi, Claude Code, Grok Build, OpenCode, Kimi Code CLI, Cursor, AXGA, and Antigravity, with installation state kept distinct from live runtime callback evidence.
- Post-`heli setup` and post-`heli link` next-step guidance for installing host integrations, launching a supported host from the linked project root, and verifying live capabilities.
- Regression coverage for taskless linked resource authority and host installation plans.

### Compatibility

- Embedded `.heli-harness/` installs retain their existing compatibility bootstrap/task-session behavior.
- Host plugin/hook installation remains machine-level; linked projects do not need a copied `.heli-harness/` tree merely to activate Codex/Pi/Claude/etc.

## v0.10.0 - Portable governance kernel and scoped authority

### Added

- Global distribution/project binding with `heli setup`, `heli link`, committed `.heli/workspace.json`, reproducibility lock `.heli/heli.lock`, stable machine identity, and execution-local operational state.
- Resource-scoped cooperative write authority for linked workspaces: one canonical worktree resource owns one writer authority, with generation/revision tracking and task ids retained as provenance rather than the exclusivity key.
- Scoped grants stored outside project-controlled files, bounded by action, resource, execution, optional session, expiry, and usage count; `allow once` is consumed atomically.
- Trusted policy composition where built-in/user ceilings may be narrowed by project policy but not elevated by repository content.
- Canonical governance decision receipts with decision ids, structured historical explanation, capability-observation freshness, and host/runtime/adapter/config identity.

### Changed

- Human and machine task lifecycle paths now share canonical claim/release/takeover/complete transitions.
- Authority explanation uses the same ownership evaluator as runtime enforcement; trace output declares its completeness instead of implying a universal audit log.
- External host-session identity is namespaced by host, and runtime capability observations distinguish documented/observed evidence from enforcement claims.
- Linked cloud portability follows the active workspace layout and carries portable work/evidence while excluding live sessions, bindings, locks, grants, YOLO state, and runtime authority.
- Project-binding validation rejects mutable authority in committed manifests/locks and rejects resource paths that escape the project root.

### Safety and compatibility

- Embedded v0.8.x workspaces remain supported as a compatibility path; first linked cutover fails closed while active embedded write authority exists.
- Cloning a linked project preserves logical workspace identity but creates a new machine/execution identity with no inherited leases, grants, sessions, or capability observations.
- T6 hard-deny rules remain non-grantable; scoped grants replace broad permission bypasses as the preferred temporary-approval path.
- The v0.9 governance-semantic stabilization work is included in this release; no separate v0.9 stable release is required for these semantics.

## v0.8.3 - Cross-machine task target restore

### Fixed

- Cloud-sync task targets now use workspace-relative worktree and repository companions, rebuild destination-local absolute caches, preserve stable normalized hashes, and mark ambiguous or unsafe legacy metadata stale without overriding live coordination.

## v0.8.2 - Allow planning tools without write lease

### Changed

- Release metadata and validation updated.

## v0.8.1 - CLI version reporting and Windows-safe release validation

### Added

- `heli --version` / `heli -v` report the package version from the standalone CLI and the embedded workspace manifest.

## v0.8.0 - Root-Cause Convergence & Evidence-Gated Autonomy

### Added

- Lazy task-local `diagnosis.json` state and append-only evidence transitions for closest proven boundaries, hypothesis invalidation, failure-class rerouting, subsystem checkpoints, material decisions, verification, and completion claims.
- `heli diagnosis show|init|record|route|gate` structured CLI surface and shared PreToolUse/tool-call evaluation for reroutes and generic expensive-action retries.
- Deterministic vNext behavioral smokes covering false premises, contradicted hypotheses, same/new failures, subsystem changes, retry justifications, review boundaries, fresh installs, and update overlay merges.
- `evidence-gates` skill and practical documentation distinguishing documented, advisory, smoke-proven, and runtime-enforced behavior.

### Changed

- S2/S3 diagnosis-aware material writes and task completion now require current evidence; YOLO does not bypass ownership, reroute, retry, S3, or production gates.
- Safety overlay updates merge newly shipped defaults by stable rule/action id while preserving local custom policy.
- Skill manifest and plugin mirrors are synchronized with the full canonical skill tree.

### Release

- Released from the independently reviewed commit and published as the `v0.8.0` npm package. No deployment or production mutation is included.

## v0.7.3 - Re-audit hardening

Response to the independent re-audit of v0.7.2 (8.1/10): its FAIL/PARTIAL claims and new-risk findings, converted.

### Fixed

- Command-tier tokenizer treats shell separators (`;`, `&`, `|`, parentheses, newlines) as token boundaries and strips surrounding quotes per token — `git push;echo hi`, `npm publish;echo done`, `"git" "push"`, and quoted program paths (`"C:\tools\heli.mjs" push`) no longer evade T5/T6 gating. Adversarial guard suite grows 260 → 310 hard asserts; `echo "digit pushups"` and `getprop | grep push` stay allowed.
- Cloud-sync design doc body rewritten to shipped reality (Durable Object storage + gzip `heli-bundle-v1`, not the original D1 + tar.gz design, which is retained as clearly-labeled "original design / scale-up path" notes); ROADMAP Phase 2 version corrected to v0.7.1. Root cause of the drift: the release script's version rewrite clobbers historical version mentions — `validate-release` now cross-checks phase versions between ROADMAP and the design doc and bans un-marked `v0.8` speculation, and it runs inside every release's gate after the rewrite, so this class now fails a release instead of shipping.

### Changed

- The release script's npm invocation decision lives in `scripts/lib/release-npm.mjs` as a pure function, unit-tested across the npm_execpath/platform matrix by `scripts/smoke-release-npm.mjs` in the check chain — the Windows EINVAL fix is now provable without cutting a release.
- `heli ws unlink` racing a concurrent auto-push is assessed benign and documented at the code site (the push either fails into the warn-only catch or lands one final retained version); doctor warnings intentionally keep exit code 0 — exit codes signal breakage, warnings signal attention.

## v0.7.2 - Doctor, hardened guards, audit response

Agent-facing governance for cloud sync: every plugin now ships the rules, not just the user docs.

### Added

- `cloud-sync` skill (29th) in the canonical library and all five plugin trees: when agents may run sync commands (only on explicit user request), what never syncs, how to treat auto-push output, conflicts, and secret-scan blocks.
- HARNESS.md **Cloud Sync Boundary**: local-only default, no unrequested sync commands, no hand-editing `state/sync.json`/credentials, no bypassing secret findings; skill routing points at `cloud-sync`.
- Command-tier rules: `heli push` / `heli sync` (and `heli.mjs` forms) are T5 explicit-approval — uploading workspace context is egress, same class as `git push`.
- `heli ws unlink` — return a linked workspace to local-only at any time; deliberately works without credentials (post-logout or dead-server escape hatch). Server copies remain until `heli ws delete`.
- `heli doctor [path]` — purely offline workspace health check: manifest/schema/index/target validity, per-task lease state (expired, orphaned), sessions and worktree bindings, embedded CLI presence, host-plugin file presence (with the honest "activation not verifiable from files" caveat), cloud-sync link + credentials, and YOLO state. Exits non-zero only on real failures; `scripts/smoke-cli-doctor.mjs` covers healthy, corrupt-schema, missing-repo, expired-lease, and orphan-lease scenarios in the check chain.

### Changed

- Command-tier rule matching is token-based instead of substring-based: rule tokens must appear as a consecutive, case-insensitive token subsequence of the (whitespace-normalized) command, with path-qualified program names still matching (`node .heli-harness/heli.mjs push` hits the `heli.mjs push` rule). Closes whitespace/tab/case evasion and substring false positives (`echo digit pushups` no longer trips `git push`). Adversarial guard suite grows 225 → 260 hard asserts.

### Fixed

- ROADMAP and the cloud-sync design doc now state shipped reality (Phases 0–1 → v0.7.0, Phase 2 → v0.7.1) instead of pre-implementation version targets.

## v0.7.1 - Cloud sync Phase 2

Cloud sync Phase 2 per [docs/architecture/cloud-sync.md](docs/architecture/cloud-sync.md): full device restore, one-command sync, and client-side encryption.

### Added

- `heli init <name> [--dir path] [--clone]` — one-command device restore: installs the workspace if absent, links the named sync workspace, pulls full context, and lists missing product repos (`--clone` re-clones entries whose `workspace/index.json` record carries a `remote` field).
- `heli sync` — pushes when local is ahead, pulls when the server is ahead, refuses cleanly on divergence; `heli sync auto on` auto-pushes the portable context after every `heli task complete` (best-effort: offline or blocked pushes warn, never fail the completion).
- Client-side E2E encryption: `heli sync e2e on` + `HELI_E2E_PASSPHRASE` env — bundles are AES-256-GCM encrypted with a scrypt-derived key before upload, the server stores ciphertext only, and pulling an encrypted bundle latches e2e on locally so no device can silently downgrade the workspace to plaintext.

### Changed

- Sync dirty detection now hashes canonical bundle content (`lastContentSha` in machine-local `state/sync.json`) instead of wire bytes — required because encrypted bundles are non-deterministic. Existing 0.7.0 links self-heal on the next push/pull.

## v0.7.0 - Cloud sync Phase 0-1

Cloud sync Phases 0–1 per [docs/architecture/cloud-sync.md](docs/architecture/cloud-sync.md): carry a workspace's portable context (profiles, policies, safety overlays, task history) across devices, gcloud-style. Strictly optional — no governance path requires the service; workspaces stay fully offline-capable.

### Added

- `npm i -g heli-harness` global install path (`prepublishOnly` gates publishes on `npm run check`); npm registry names `heli`/`heli-cli` are taken, so the package is `heli-harness` with bin `heli`.
- `heli auth login|logout|status|devices` — OAuth device-flow auth against a heli sync server (GitHub as identity provider; per-device revocable tokens stored in `~/.heli/credentials.json`, override dir with `HELI_CONFIG_DIR`).
- `heli ws create|link|list|versions|delete` — sync workspace management; the local link lives in machine-local `.heli-harness/state/sync.json` and never syncs.
- `heli push` / `heli pull` — snapshot sync of the portable subset (`profiles/`, `policies/`, `safety/`, `tasks/`, `workspace/index.json`, `workspace/schema.json`, `state/*.md`) as gzip'd `heli-bundle-v1` bundles with optimistic concurrency (stale push → 409 → pull first or `--force`; old heads stay in the last-10 version history), dirty-pull refusal, and a blocking pre-push secret scan (`--allow-secrets` to override false positives).
- Sync server: `cloud/core.mjs` portable API core (dependency-free, standard Request/Response) + `cloud/worker.mjs` Cloudflare shell (single Durable Object serializes state, R2 stores bundles) + `cloud/wrangler.toml` + deploy guide in `cloud/README.md`.
- `scripts/smoke-cloud-sync.mjs` in `npm run check` / CI: full client↔core contract — device-flow login ×2 devices, create/link, push/pull round-trip, secret blocking, version conflict, dirty-pull refusal, device revocation — against the real CLI subprocess and the core served over node:http.

## v0.6.0 - Enforcement, lifecycle, and offline CLI

Driven by a full code review and field feedback from five agent sessions using the harness on real projects.

### Added

- Workspace-embedded CLI: every install ships `.heli-harness/heli.mjs` + `cli/` (generated by `scripts/sync-workspace-cli.mjs`, byte-checked in `npm run check`), so `node .heli-harness/heli.mjs <cmd>` works offline with no npx and no PATH setup. Denial messages reference this path.
- `heli task complete <id>` — terminal state transition: updates task.json, syncs current-task.md, releases the session's own lease; refuses when another session holds an active lease.
- `heli task provenance <id>` — claim/renew/release timeline from events.jsonl plus live lease state.
- `heli task create --reuse` — idempotent create returns the existing task instead of failing with TASK_EXISTS.
- `heli install --force` — required to overwrite an existing workspace; plain re-install now refuses instead of silently wiping profiles, policies, tasks, and sessions.
- Command-tier rules from `safety/command-rules.json` are enforced at PreToolUse: T6 blocks, T5 denies pending explicit approval (`HELI_ALLOW_COMMAND=<rule-id>`, YOLO, or run manually); T0–T4 stay advisory.
- `Verification limitations:` is a first-class current-task.md field for recording what could not be verified.
- quality-guard-strictness now runs in `npm run check` / CI with new adversarial sections (fail-closed gates, control-plane writes, tier rules): 225 hard asserts across 5 host hooks.

### Changed

- `update.sh` / `update.ps1` delegate to `node bin/heli.mjs update`, gaining concurrent-state preservation, pruning of removed assets, and the package-dogfood guard (previously a divergent v0.5.5 copy).
- Zero-task concurrent workspaces accept `heli target set` (bootstrap parity with the ownership gate); still refused once tasks exist.
- A session's own expired write lease self-renews on claim or next gated write instead of requiring `task takeover` against itself; other sessions are still refused.

### Fixed

- Ownership gate fails closed: a malformed `workspace/schema.json` resolves to concurrent mode instead of silently disabling enforcement; corrupt task.json files no longer re-open zero-task bootstrap writes; `sessions/`, `bindings/`, `locks/`, and `workspace/schema.json` are no longer exempt from the gate (self-granted leases, session rebinds, and mode flips by hand-edit are denied).
- `release.mjs` uses real semver tuple comparison; downgrades and equal versions are rejected.
- `smoke-pack-artifact.mjs` extracts with relative tar paths, fixing `npm run check` on Windows hosts where GNU tar treats `C:\` paths as remote hosts.

## v0.5.27 - Default concurrent install and Start with Heli

### Added

- README **Start with Heli** guide: parent workspace layout (`repos/`, `docs/`, `resources/`), npx install, Codex plugin, strict YOLO default, target/profile setup, and first-session open prompt.

### Changed

- **New installs default to concurrent mode** (`workspace/schema.json` `"mode": "concurrent"`). Zero tasks = single-agent bootstrap (writes allowed); once any task exists, full session/lease ownership applies. `heli update` still does not flip existing legacy workspaces.
- SessionStart/ownership: concurrent empty-task bootstrap messaging; full lease gates once any task exists.
- Install CLI seed messaging documents concurrent default and multi-agent claim path.

## v0.5.26 - Ops honesty and concurrent hygiene

### Added

- **Ops honesty & concurrent hygiene**
  - Templates: Resume card + Command friction on `current-task.md`; plan Active strategy / Evidence hygiene; `ops-gate-packet.md`; `windows-shell-recipes.md`
  - Skill `concurrent-upgrade` for legacy to concurrent migration after `heli update`
  - SessionStart: governance enforcement honesty, legacy multi-agent race warning, concurrent unbound write denial messaging
  - `heli status` / `heli update`: legacy multi-writer risk + migrate path (update does not flip mode)
  - Skills: `verify-premise` (e2e contract + ACTION_UNSUPPORTED), `impact` (destructive multi-path checklist), `fix-loop` (friction vs implementation failures)

### Changed

- HARNESS.md: plan/task freshness, evidence purity, resume/gate packet, legacy vs concurrent upgrade truth, command-friction vs failed attempts
- Codex adapter: Windows/shell recipes pointer

## v0.5.25 - Codex Git marketplace and update host refresh

### Added

- **Codex Git marketplace (Ponytail parity):** repo-root `.agents/plugins/marketplace.json` indexes `./.heli-harness/adapters/codex-plugin`, so `codex plugin marketplace add KJ-AIML/heli-harness` works and `codex plugin marketplace upgrade heli-harness` can refresh a Git marketplace snapshot (local nested path remains available for workspace dogfood only).

### Changed

- `heli update` / `update.sh` / `update.ps1` now print host plugin refresh commands after a workspace update, including `codex plugin marketplace upgrade heli-harness` for the Git marketplace and a one-time local-to-Git switch sequence.
- INSTALL / INSTALL_MATRIX document workspace update vs Codex marketplace upgrade as separate steps.
- `scripts/smoke-pack-artifact.mjs` asserts the packed version dynamically against `package.json` (no hardcoded version) and requires the root Codex marketplace manifest in the tarball.

### Fixed

- Codex install docs and `heli install` post-install hints no longer recommend bare `.heli-harness/adapters/codex-plugin` as a marketplace source — Codex rejects that form (`invalid marketplace source format`). Use `KJ-AIML/heli-harness` (Git) or `./.heli-harness/adapters/codex-plugin` / an absolute path (local).
- `scripts/live-verify-codex-plugin-install.mjs` now proves repo-root marketplace install, nested dogfood install, and bare-path rejection against the real Codex CLI.

## v0.5.24 - Concurrent Session Foundation

### Added

- **Concurrent Session Foundation** for multi-session local coordination without becoming an agent orchestrator:
  - Durable tasks under `.heli-harness/tasks/<task-id>/` (`task.json`, task-local plan/decisions/reports/evidence/events)
  - Heli-generated sessions under `.heli-harness/sessions/<session-id>.json` with optional `externalHostSessionId`
  - Worktree bindings under `.heli-harness/bindings/worktrees/`
  - Single-writer task leases via exclusive lock directories `locks/tasks/<task-id>.write.lock/`
  - Shared execution resolver used by Claude, Codex, Grok, Kimi, OpenCode, Antigravity hooks and Pi
  - Workspace schema `.heli-harness/workspace/schema.json` with `mode: legacy | concurrent`
  - CLI: `heli task`, `heli session`, `heli conflicts`
  - Task-scoped YOLO (global `yolo.json` does not bleed across tasks in concurrent mode)
  - Task-authoritative targets in concurrent mode
  - Duplicate work-item detection on task create
  - Advisory path-claim conflict detection
  - `heli task migrate-legacy` one-way import from singular state files
  - Regression suite: `node scripts/smoke-concurrency-foundation.mjs` (included in `npm run check`)
  - Canonical clean-install seed: `lib/cli/seed-workspace.mjs` (distribution assets only + explicit idle operational seed)
  - Pollution-proof install smokes: `scripts/smoke-clean-install.mjs`
  - Status worktree projection smokes: `scripts/smoke-status-worktree.mjs`
  - Live concurrent host proofs (not in `npm run check`): `scripts/live-verify-codex-concurrency.mjs`, `scripts/live-verify-claude-concurrency.mjs`
  - Plugin-local `shared/` copies for host cache installs + `scripts/sync-plugin-shared.mjs`
  - **Full host-native skill library packaging:** canonical `.heli-harness/skills/` (including `using-heli-skills` meta-skill + governance trio) is mirrored into Codex, Claude, Grok, Antigravity, and Cursor plugin `skills/` trees
  - `scripts/sync-plugin-skills.mjs` + `npm run sync:plugin-skills` / `--check` for frontmatter validation and plugin parity
  - Compact SessionStart **skill-usage bootstrap** (distinct from task/session/lease governance context)
  - `scripts/smoke-plugin-skills.mjs` packaging/discovery smoke (in `npm run check`)

### Changed

- `heli status` reports concurrent multi-task summaries when schema mode is concurrent, projecting **live** worktree from write lease → writer session → binding → task metadata (with conflict warnings).
- `heli status` reports skill packaging counts and **host activation not verifiable** (file presence ≠ live activation).
- `heli install` / `install.sh` / `install.ps1` / Pi `/heli-install` all use one clean seed path — never copy package checkout dogfood (tasks, sessions, live current-task, YOLO, selected target).
- `heli install` stdout clearly separates workspace governance install from host plugin activation commands for native skills.
- `heli update` updates distribution assets only; preserves user tasks/sessions/bindings/locks/state/targets/YOLO; `--reset-state` reseeds idle operational state without importing package dogfood.
- Plugin hooks import embedded `../shared/` so Codex marketplace cache and Claude `--plugin-dir` copies are self-contained.
- Skill frontmatter standardized to unique hyphenated names and “Use when…” trigger descriptions for host semantic discovery.
- `HARNESS.md` Skill Routing updated for full plugin skill inventory + `using-heli-skills` protocol.

### Fixed

- Clean installs no longer inherit operational state from a dogfooded source package tree.
- **Published tarball is free of operational dogfood:** package seeds ship idle `current-task.md`, empty `target.json`/`index.json`, no `plan.md`/`yolo.json`, and `.npmignore` excludes `sessions/`/`tasks/`/`bindings/`/`locks/`. Plugin SessionStart smokes no longer mint sessions into the package checkout (fixture cwd). Guard: `scripts/smoke-pack-artifact.mjs` in `npm run check`.
- Codex/Claude plugin packages no longer fail hook module resolution when hosts cache only the plugin directory (missing sibling `adapters/shared`).
- UTF-8 BOM stripped from packaged skill frontmatter so Codex can parse `SKILL.md`.
- Host plugins no longer ship only the three wrapper skills; the complete intended Heli skill library is packaged for native discovery when the host plugin is activated.

### Notes

- Local workspace coordination only — not a distributed lock service, scheduler, agent runtime, or merge orchestrator.
- YOLO never bypasses ownership, lease, or wrong-task gates.
- Legacy singular `state/current-task.md` workspaces continue to work until concurrent mode is initialized.
- Workspace install and host plugin activation remain separate: `heli install` alone does not register host-native skills.
- Live v0.5.24 plugin runtime proof (this release): **Codex** isolated `CODEX_HOME` + real `codex exec` — marketplace install, SessionStart Completed, PreToolUse denials for `git push` and `.env` honored. Claude Code SessionStart + concurrent context proven via `--plugin-dir`; full Claude PreToolUse enforcement requires a working host API key on the verification machine.
- After editing `adapters/shared`, run `npm run sync:plugin-shared` before commit.
- After editing `.heli-harness/skills/`, run `npm run sync:plugin-skills` before commit.

## v0.5.23 - Cursor Marketplace and OpenCode Discovery


### Added

- Installable Cursor marketplace layout with `.cursor-plugin/marketplace.json` and a nested Heli-Harness plugin package.
- Cursor marketplace smoke validation covering the marketplace manifest, plugin manifest, rule, and skills.

### Fixed

- OpenCode installation guidance now uses automatic project/global plugin discovery from `.opencode/plugins/` and `~/.config/opencode/plugins/`.
- Cursor and OpenCode adapter documentation and support metadata now match their host layouts.

## v0.5.22 - YOLO / unguarded mode (opt-in)

### Added

- **YOLO / unguarded mode** (opt-in only): skip Heli PreToolUse blocks for remote git write, `.env`-style secrets, and stuck-task gates when the user explicitly enables it.
  - `heli yolo on|off|status [path] [--hours N]`
  - Env: `HELI_YOLO=1` or `HELI_GUARDS=off`
  - File: `.heli-harness/state/yolo.json` `{ "enabled": true }`
  - Task: `Mode: yolo` (or `unguarded` / `dangerous`)
  - Granular: `HELI_ALLOW_GIT_PUSH=1`, `HELI_ALLOW_ENV_WRITE=1`
  - Wired across Claude/Codex/Grok/Kimi/OpenCode hooks + Pi `tool_call` guard
  - Docs: `.heli-harness/safety/yolo-mode.md`
  - Smoke: `node scripts/smoke-yolo-mode.mjs`
- Default remains **strict**. YOLO never turns on by itself.

### Notes

- YOLO is not a host sandbox bypass. It only disables Heli's own guard denials.
- Use for large autonomous workflows that intentionally need remote push or secret-file writes; turn off when finished.

## v0.5.21 - Multi-Host Adapters (Grok / OpenCode / Kimi / Antigravity)

### Added

- First-class adapters for **Grok Build**, **OpenCode**, **Kimi Code CLI**, and **Antigravity CLI**:
  - Pointer + plugin/hooks packs under `.heli-harness/adapters/{grok,opencode,kimi,antigravity}(-plugin)/`
  - One-command installers: `grok-plugin/install-user-hooks.mjs`, `kimi-plugin/install-user-hooks.mjs`
  - Synthetic smokes + live-verify scripts for Grok/OpenCode/Kimi
  - Adversarial strictness suite: `node scripts/quality-guard-strictness.mjs`
- **Grok (`enforced`)**: live `grok -p` PreToolUse deny of `git push` via user hooks (`~/.grok/hooks/heli-harness.json`). Valid `grok plugin validate/install` for skills. Important: Grok 0.2.x does not execute plugin-inventory hooks at runtime — user hooks are required.
- **OpenCode (`enforced`)**: self-contained `heli-harness.mjs`; live `opencode run` loads plugin and blocks git push. Register in `opencode.json` `plugin` array.
- **Kimi (`enforced`)**: live `kimi -p` prints Heli git-push denial after `install-user-hooks.mjs` + valid `kimi doctor config`.
- **Antigravity (`verified-plugin-wired`)**: artifacts + synthetic smokes only (no live `agy` on verification host).

### Fixed

- Grok `plugin.json` now uses Claude/Grok-compatible `author` object + `.claude-plugin` / `.grok-plugin` layouts (previous root manifest failed `grok plugin validate`).
- Kimi TOML hook examples use single-quoted command strings (Windows path-safe).
- Docs: INSTALL.md / INSTALL_MATRIX / ADAPTER_SUPPORT_MATRIX / README aligned with proven status (Claude/Codex rows no longer stuck on stale `verified-plugin-wired` in INSTALL_MATRIX).

### Notes

- Live-verify scripts require the host CLI + credentials and are **not** part of `npm run check`.
- Guards are pattern-based PreToolUse/plugin hooks, not a sandbox: install hooks correctly, and know obfuscation gaps remain.


## v0.5.20 - `heli target` Path Argument Fix

### Fixed

- `heli target list|show|set|clear` previously always operated on `process.cwd()` and silently ignored any path argument, unlike `heli status`'s existing `args[0] || process.cwd()` support for the same kind of override. Pointing the CLI at a different workspace (e.g. `heli target list /some/other/workspace`) silently returned the caller's own current-directory data instead of erroring, warning, or reading the given path — a silent-wrong-answer footgun, not just an inconsistency. Found via real `npx`-distributed dogfooding against a workspace other than the shell's cwd.
- `runTarget()` now threads an optional trailing path argument through all four subcommands (`list [path]`, `show [path]`, `set <repo> [--confirm] [path]`, `clear [path]`), matching `status.mjs`'s pattern exactly. No-path invocations (the overwhelmingly common case) are byte-for-byte unchanged.

### Notes

- The underlying pure functions (`listRepos`/`showTarget`/`setTarget`/`clearTarget`) were never the problem — they already took `cwd` as an explicit parameter and never read `process.cwd()` themselves, per the CLI's Global Constraint. Only the CLI-facing `runTarget` wrapper had never threaded a path through to begin with.
- New regression coverage spawns the real `bin/heli.mjs` as a subprocess from one temp directory while passing a second, differently-seeded temp directory as the explicit path argument — proving the path argument, not `process.cwd()`, is honored, for all four subcommands. This is currently the only test in the suite that exercises a `run*()` wrapper's argv/path handling end-to-end; `smoke-cli-{install,update,uninstall,status}.mjs` still only test their underlying pure functions directly, and `smoke-cli-entry.mjs`'s subprocess test only checks generic label presence, not path-correctness. Same root-cause class as the `bin/heli.mjs` coverage gap fixed in v0.5.19 — noted as a follow-up, not fixed here.

## v0.5.19 - Standalone `heli` CLI

### Added

- New standalone `heli` CLI (`bin/heli.mjs` + `lib/cli/{install,update,uninstall,target,status}.mjs`), distributed via `npx github:KJ-AIML/heli-harness <command> <path>` — no npm registry publish, no new dependencies, hand-rolled argv dispatch. Covers `install`, `update` (with `--reset-state`), `uninstall`, `target list|show|set|clear` (`set` gates on `--confirm` when switching an already-selected target, replacing the skill's conversational confirmation step), and a new read-only `status` command with no prior equivalent.
- This is the one real, tested implementation each surface now points at, replacing what were previously N independently drifting copies of the same install/update logic: Pi/AXGA's extension (which had install but, until now, no update command at all), Claude/Codex's prose skills (manual steps for an agent to replicate by hand), and the raw `.ps1`/`.sh` scripts.
- `extensions/pi-extension.js`'s `/heli-install` now calls the CLI's `install()` directly instead of shelling out to `install.ps1`/`.sh`; a new `/heli-update` command (`/hh-update` alias) calls `update()` the same way, closing the "Pi has no update command" gap.
- Both `heli-install`/`heli-target` skill pairs (Claude, Codex plugins), `README.md`, and `INSTALL.md` document the CLI as the preferred method, keeping the existing manual/script-based instructions as the documented fallback for Node-less environments.
- Subprocess-level smoke test (`scripts/smoke-cli-entry.mjs`) spawns the real `bin/heli.mjs` binary to prove its argv dispatch and self-location (`fileURLToPath(import.meta.url)`) work end-to-end, distinct from the 5 module-level smoke tests which exercise `lib/cli/*.mjs` directly; `bin/heli.mjs` is now covered by `node --check` in the `check` script.

### Fixed

- `install()`/`update()` now guard against a self-collision case (the package root and the install target resolving to the same directory — e.g. running the CLI from inside a local heli-harness checkout as its own target) with a clear, specific error instead of letting Node's raw `fs.cpSync` `ERR_FS_CP_EINVAL` surface.

### Notes

- Distribution is git-URL/npx only, deliberately not published to the npm registry, to avoid the ongoing maintenance cost of npm publishing (account, 2FA, a publish step every release).
- Every low-level `lib/cli/*.mjs` function takes explicit paths and never reads `process.cwd()` internally — only the `run*(packageRoot, args)`/`run*(args)` CLI-facing wrappers touch argv/cwd defaults. `extensions/pi-extension.js` importing directly from `../lib/cli/*.mjs` is a deliberate exception to this codebase's usual small-duplicated-pure-function convention, since both live in the same repo checkout Pi loads directly.
- Existing `.ps1`/`.sh` scripts are completely untouched and remain the documented fallback; this release is purely additive.
- A pre-existing, out-of-scope gap found during this work: Pi's `/heli-target set` handler still overwrites `target.json` unconditionally with no mismatch confirmation, unlike this new CLI's `--confirm` gate and the documented Claude/Codex skill behavior — tracked as a separate future follow-up, not fixed here.

## v0.5.18 - Skill Discipline & Step-Count Warning

### Added

- `current-task.md` gains a self-reported `Step count: N` field, mirroring `Failed attempts count`. Session-start context (Claude-plugin, Codex-plugin, Pi/AXGA) now warns — not a blocking gate — when `Step count` is 3+ but `Plan:` is still `n/a`: the exact case where a task obviously needed a `plan.md` and never got one, previously invisible everywhere in the system.
- `claude/CLAUDE.md` and `codex/AGENTS.md`'s enforcement self-check now also states the inference that `PreToolUse` is equally wired whenever the `SessionStart` marker fired, since a plugin's hooks load atomically from the same manifest — never having triggered a deny condition isn't evidence the blocking side is inactive.

### Changed

- `HARNESS.md`'s Skill Routing section rewritten with mandatory-invocation framing and a Red Flags rationalization table (borrowed from superpowers' `using-superpowers` skill), and now states explicitly that reading a `.heli-harness/skills/*/SKILL.md` file directly is the correct mechanism on Claude/Codex plugin installs — not a fallback — since those adapters never expose the shared skills directory as native Skill-tool entries.
- `state/README.md` gains a dedup nudge: cross-reference one canonical location for repeated verification facts (test counts, version numbers) instead of hand-retyping them across `current-task.md`/`plan.md`/`decisions.md`.

### Notes

- All four changes came from evidence-based feedback on two independent real projects using Heli-Harness. The skill-routing gap was found twice, independently, by two unrelated sessions — strong enough signal to fix immediately rather than continue deferring it.
- The `Step count`/`Plan` warning is deliberately a warning, not a `PreToolUse` deny: it's a new, self-reported field with no track record yet, and a false-positive block would cost more than the gap it closes. `readPlanGate()`'s existing `if (!existsSync(planPath)) return null` (matching `decisions.md`'s own nothing-if-missing precedent) is unchanged — this is additive context, not a new gate.
- Implemented directly rather than through the worktree/subagent-driven-development pipeline used for v0.5.17: no new state file, no `PreToolUse` changes, just an addition to the existing session-start injection — meaningfully lower-stakes than the plan-ledger feature itself.

## v0.5.17 - Cross-CLI Plan Ledger

### Added

- New optional state file `.heli-harness/state/plan.md` (template at `.heli-harness/templates/plan.md`): a self-contained, step-by-step plan ledger using `## Step N: <title>` sections with `Files:`/`Verify:`/`Status:`/`Evidence:`/`Attempts:` fields, so a multi-step task can be handed off between CLIs (e.g. a quota-driven Codex-to-Claude switch mid-plan) with each step carrying verifiable evidence and a failed-attempts count, not just a bare checkbox.
- All three adapters (Claude Code plugin, Codex plugin, Pi/AXGA extension) now surface a compact rollup of `plan.md` (title, "N/M steps complete", current step's title/status/attempts) in session-start context when the file is present, and inject nothing when it's absent.
- All three adapters extend their existing whole-task stuck-task gate down to step granularity: 2+ failed attempts on the current (first non-complete) step blocks further `Edit`/`Write`/`apply_patch` calls until that step's `Status`/`Attempts` fields are updated, mirroring the v0.5.15 whole-task gate. Writes to `plan.md` itself remain exempt.
- `HARNESS.md`'s "3+ discrete steps" rule (the same threshold governing the `Relevant skills consulted` field) now also requires writing these steps to `plan.md` before starting, with per-step `Evidence`/`Status` filled in immediately after each step verifies, not batched at the end.

### Changed

- `.heli-harness/templates/current-task.md` and `HARNESS.md`'s Required Task State list gained a `Plan:` field pointing at `.heli-harness/state/plan.md` when one exists.
- `.heli-harness/manifest.json`'s `state` block now lists `plan.md` alongside `current_task`/`decisions`.
- `docs/ADAPTER_SUPPORT_MATRIX.md` and `.heli-harness/state/README.md` document the new rollup and per-step gate across all three adapters.

### Notes

- HARNESS.md's Operating Model previously had a gap: an earlier release intended to add a "3+ discrete steps" rule alongside the `Relevant skills consulted` field, but only the field name landed in the Required Task State list — the behavioral rule itself was never written. This release adds that rule for the first time, extended to also cover `plan.md`.
- Non-goals: no support for multiple simultaneous plans (one `plan.md`, same singular-active-task model as `current-task.md`); no archival mechanism for completed plans beyond whatever git history the workspace keeps; not a replacement for tool-specific planning skills (e.g. superpowers' `writing-plans`) — `plan.md` is the cross-CLI-portable layer, usable alongside a richer tool-specific plan doc if one exists.

## v0.5.16 - Cross-CLI Context Parity

### Added

- Claude Code and Codex native plugins now surface the last 5 `## `-headed sections of `.heli-harness/state/decisions.md` (the durable "why" decision log) at session start, alongside the `current-task.md` content already surfaced since v0.5.15.
- Pi/AXGA's `extensions/pi-extension.js` brought up to the same level as the Claude/Codex plugins: `before_agent_start` now injects real `current-task.md` and `decisions.md` content (previously only a generic reminder), and `tool_call` now gates file writes when `current-task.md` shows a stuck task (2+ failed attempts, incomplete) — mirroring the guard the plugins got in v0.5.15.
- Both `heli-governance/SKILL.md` copies (Claude, Codex) gained a one-line nudge to log durable decisions to `decisions.md` after completing S2/S3-tier work.

### Fixed

- Fixed a pre-existing bug (predating this release, from the original safe-auto-hooks work) in `isSuspiciousHarnessRuntimePath`'s call site in `extensions/pi-extension.js`: it was called with the raw relative path instead of the already-resolved absolute path, causing it to incorrectly flag the harness's own `.heli-harness/state/current-task.md` as a "suspicious" runtime folder. This silently broke the new stuck-task gate's self-exemption (an agent couldn't write `current-task.md` to resolve a stuck task). Found by new test coverage for that exemption; had zero prior test coverage.

### Changed

- `docs/ADAPTER_SUPPORT_MATRIX.md` and `.heli-harness/state/README.md` document the new Pi stuck-task gate and the cross-adapter `decisions.md` surfacing.

### Notes

- Closes the remaining asymmetry from v0.5.15: Pi/AXGA previously had weaker context continuity than Claude/Codex; all three adapters with a runtime hook mechanism (Claude, Codex, Pi/AXGA) now behave identically on this feature. Cursor and Generic have no hook mechanism and are unaffected.
- `enforced` status for Claude Code, Codex, and Pi is unaffected — this adds enforcement surface and context, it doesn't change the taxonomy basis for any adapter's status.

## v0.5.15 - Session Task Gate

### Added

- `SessionStart` in both the Claude Code and Codex native plugins now injects the real content of `.heli-harness/state/current-task.md` (previously only a static reminder to go read it), so carried-over task state actually reaches the next session's context instead of depending on the agent going to look for it.
- `PreToolUse` in both plugins now blocks `Edit`/`Write`/`apply_patch` calls when that carried-over task is stuck (2+ failed attempts, still not `complete`) or its target repo no longer matches `.heli-harness/workspace/target.json` — until the state file (or `target.json`) is updated to resolve it. Stateless: re-reads both files on every call, no session-id tracking or marker files, and clears itself automatically once the mismatch/stuck condition is fixed.
- Added 4 new fixture-based smoke assertions per plugin (`scripts/smoke-claude-plugin.mjs`, `scripts/smoke-codex-plugin.mjs`) covering the stuck case, the mismatch case, the healthy pass-through case, and the exemption for edits to `current-task.md`/`target.json` themselves. New shared test helpers (`withFixtureWorkspace`, `assertHookDenyInCwd`, `assertHookAllowInCwd`) added to `scripts/lib/plugin-smoke-helpers.mjs`.

### Changed

- `adapters.json` and `docs/ADAPTER_SUPPORT_MATRIX.md` now list this gate as a new enforcement surface for the `claude` and `codex` adapters.
- `HARNESS.md`'s Operating Model documents the new enforcement.

### Notes

- Closes a real cross-CLI handoff gap: this workspace's actual usage pattern is switching between Claude Code, Codex, and Pi/AXGA mid-task, and nothing previously stopped a new session in a different CLI from silently working against stale or mismatched task state left by a prior session.
- Scoped to the Claude Code and Codex native plugins only. Pi/AXGA already has its own separate `enforced` mechanism (`before_agent_start`/`session_start` hooks); extending this same gate there is a reasonable follow-up, not done here.
- `enforced` status for Claude Code and Codex is unaffected — this adds a new enforcement surface, it doesn't change the taxonomy basis for the existing status.

## v0.5.14 - Plugin Install Parity

### Added

- Added a `heli-install` skill to both `.heli-harness/adapters/claude-plugin/skills/` and `.heli-harness/adapters/codex-plugin/skills/`, giving parity with Pi/AXGA's `/heli-install`. Instruction-based (no JS runtime in these plugins): the agent runs `install.ps1`/`install.sh` itself instead of the skill shelling out.
- Reproduces Pi's `installHandler` guard (refuse and point at the update flow if the workspace is already installed) and `verifyInstall` checklist, since a dry-run confirmed `install.ps1` has no preserve-local-state logic of its own — that safety only exists in `update.ps1`.
- Resolves the latest release tag at run time instead of hardcoding a version, so the skill won't go stale next release.
- Added `assertFile` smoke coverage for `heli-target` and `heli-install` in both plugin smoke tests.

### Changed

- `adapters.json` and `docs/ADAPTER_SUPPORT_MATRIX.md` limitations updated to list the current plugin skill surface: `heli-governance` + `heli-target` + `heli-install`.

### Notes

- Same gap class as v0.5.13's `heli-target` port: a Pi/AXGA-only command with no Claude/Codex equivalent.
- `enforced` status for Claude Code and Codex is unaffected.

## v0.5.13 - Plugin Target Parity

### Added

- Added a `heli-target` skill to both `.heli-harness/adapters/claude-plugin/skills/` and `.heli-harness/adapters/codex-plugin/skills/`, giving `list`/`show`/`set`/`clear` parity with Pi/AXGA's `/heli-target` against `.heli-harness/workspace/index.json` and `target.json`. Instruction-based (no JS runtime in these plugins), so the agent performs the steps itself with its own file tools.
- `set` now confirms with the user before overwriting a `target.json` that already points at a different repo, instead of silently switching.

### Changed

- Reworded the `git push` deny message in both `heli-pre-tool-use.mjs` plugin copies: it previously said "without explicit release approval," which read as though ordinary branch pushes were release-gated. It now states plainly this is a blanket in-session rule with no bypass.
- Both `heli-governance/SKILL.md` copies now point at the `heli-target` mismatch-confirm workflow when the repo the user describes differs from the active target.
- `adapters.json` and `docs/ADAPTER_SUPPORT_MATRIX.md` now disclose that the Claude Code and Codex plugin skill surface is `heli-governance` + `heli-target` only, not Pi/AXGA's full 23-skill set. No adapter `status` value changed.

### Notes

- Prompted by real Codex CLI feedback hitting this exact gap while working against this harness in a separate workspace.
- `enforced` status for Claude Code and Codex is unaffected — it's scoped to runtime hook proof, which this release doesn't touch.

## v0.5.12 - Codex Live Hook Verification

### Fixed

- Fixed `heli-pre-tool-use.mjs` (Codex and Claude Code plugin copies): the file-write guard only recognized `path`/`file` object keys, but Codex's `apply_patch` tool embeds the target path inside a patch-format string under `command` (e.g. `*** Add File: .env`), so `.env` writes went through unguarded in a real Codex session. Now also parses `*** Add/Update/Delete File:` and `*** Move to:` patch directives.
- Fixed the synthetic `apply_patch` test case in `smoke-claude-plugin.mjs` and `smoke-codex-plugin.mjs`, which used an unrealistic `{ path: ... }` payload that passed without exercising Codex's real tool shape — replaced with the actual payload shape captured from a live Codex session.

### Added

- Added `scripts/live-verify-codex-plugin-hook.mjs`: drives a real `codex exec` turn (isolated `CODEX_HOME`, throwaway git repo, `--dangerously-bypass-hook-trust`) and asserts the CLI's own output shows the PreToolUse hook denying both `git push` and a `.env` write, with the filesystem confirming `.env` was never created.
- Added `live-verify:codex-plugin-hook` npm script. Not part of `npm run check` — requires a real installed, logged-in Codex CLI and available usage quota.

### Changed

- Promoted Codex from `verified-plugin-wired` to `enforced`, backed by live-session evidence.
- Updated adapter manifest, support matrix, README, and Codex adapter docs for the new status.

### Notes

- Live proof used `--dangerously-bypass-hook-trust`; the normal interactive hook-trust prompt flow is not separately verified.
- Pi, Claude Code, and Codex are now all `enforced`.

## v0.5.11 - Live Runtime Verification

### Added

- Added `.heli-harness/adapters/codex-plugin/.agents/plugins/marketplace.json` — the Codex plugin directory had no marketplace manifest, so `codex plugin marketplace add` could not recognize it. Fixed and live-verified against the real Codex CLI.
- Added `scripts/live-verify-claude-plugin.mjs`: drives a real `claude -p` session (`--plugin-dir`, isolated sandbox repo) and asserts the session's own `permission_denials` result shows the PreToolUse hook denying `git push` and a `.env` write.
- Added `scripts/live-verify-codex-plugin-install.mjs`: drives the real `codex` CLI (isolated `CODEX_HOME`) through `plugin marketplace add` and `plugin add`, and confirms `plugin list` reports it installed and enabled.
- Added `live-verify:claude-plugin` and `live-verify:codex-plugin-install` npm scripts. Not part of `npm run check` — they require a real installed CLI and make real API calls.

### Changed

- Promoted Claude Code from `verified-plugin-wired` to `enforced`, backed by live-session evidence.
- Updated adapter manifest, support matrix, README, and Claude/Codex adapter docs for the new evidence and status.

### Notes

- Codex remains `verified-plugin-wired`: marketplace add, plugin install, and trust are proven live against the real Codex CLI, but PreToolUse hook firing during a real model turn is not yet proven — that check needs Codex usage quota that was unavailable at verification time.
- Claude Code's live proof used `--plugin-dir` session loading, not the marketplace-installed-and-trusted flow (`claude plugin install`); that path is not separately verified.
- Pi and Claude Code are the `enforced` adapters. Codex is not.

## v0.5.10 - Native Plugin Parity

### Added

- Added `docs/PONYTAIL_PARITY_AUDIT.md` comparing Heli against Ponytail plugin artifacts, hooks, commands, skills, install flow, and validation evidence.
- Added Claude Code native plugin artifacts under `.heli-harness/adapters/claude-plugin/`.
- Added Codex native plugin artifacts under `.heli-harness/adapters/codex-plugin/`.
- Added `scripts/smoke-claude-plugin.mjs`, `scripts/smoke-codex-plugin.mjs`, and a small shared plugin smoke helper.

### Changed

- Added `verified-plugin-wired` and `plugin-wired` adapter statuses.
- Promoted Claude Code and Codex from `verified-wired` to `verified-plugin-wired`.
- Integrated plugin smoke tests into `npm run check`, adapter verification, and release validation.
- Updated install docs, support matrix, governance model, and README for pointer adapter mode versus native plugin artifact mode.

### Notes

- Does not claim live Claude Code or Codex runtime hook enforcement.
- Synthetic PreToolUse hook tests deny `git push` and `.env` writes, but host install/trust/runtime execution still needs live verification before any `enforced` claim.
- Pi remains the only `enforced` adapter.

## v0.5.9 - Codex Governance Workflow

### Added

- Added `scripts/smoke-codex-adapter.mjs` to verify Codex adapter files, required `AGENTS.md` sections, installer-created workspace `AGENTS.md`, update preservation of user-owned workspace `AGENTS.md`, manifest evidence, and support matrix claims.
- Added `smoke:codex` npm script and included Codex smoke in `npm run check`.

### Changed

- Promoted Codex from `wired` to `verified-wired`.
- Improved `.heli-harness/adapters/codex/AGENTS.md` as the Codex-facing governance entrypoint with target discipline, write boundaries, safety guidance, evidence rules, validation expectations, final report expectations, and explicit limitations.
- Updated `.heli-harness/adapters/codex/README.md` with the recommended Codex workflow and non-enforcement limitations.
- Updated adapter manifest, support matrix, install docs, README, and governance model for the new status.
- Integrated Codex smoke into release validation.

### Notes

- Does not claim Codex runtime hook enforcement.
- Pi remains the only `enforced` adapter.
- Claude Code and Codex are `verified-wired`.
- Does not implement OpenCode/Cursor real adapters.
- Does not start benchmark matrix runs.

## v0.5.8 - Claude Code Adapter Verification

### Added

- Added `verified-wired` adapter status for smoke-tested adapter wiring without runtime enforcement claims.
- Added `scripts/smoke-claude-adapter.mjs` to verify Claude adapter files, required `CLAUDE.md` sections, settings JSON parsing, installer-created workspace `CLAUDE.md`, update preservation of user-owned workspace `CLAUDE.md`, manifest evidence, and support matrix claims.
- Added `smoke:claude` npm script and included Claude smoke in `npm run check`.

### Changed

- Promoted Claude Code from `wired` to `verified-wired`.
- Improved `.heli-harness/adapters/claude/CLAUDE.md` as the Claude-facing harness entrypoint with target discipline, write boundaries, safety guidance, evidence rules, validation expectations, final report expectations, and explicit limitations.
- Updated adapter manifest, support matrix, install docs, README, and governance model for the new status.
- Integrated Claude smoke into release validation.
- Included local Windows portability hotfix `04443f2` for `scripts/smoke-update-preserves-local-state.mjs`.

### Notes

- Does not claim Claude Code runtime hook enforcement.
- Pi remains the only `enforced` adapter.
- Does not implement Codex/OpenCode/Cursor real adapters.
- Does not start benchmark matrix runs.

## v0.5.7 - Adapter Wiring Coverage

### Added

- Added adapter status taxonomy: `enforced`, `wired`, `documented`, `planned`, `unsupported`.
- Added `docs/ADAPTER_SUPPORT_MATRIX.md` with honest, evidence-based adapter status assessment.
- Added `.heli-harness/adapters/adapters.json` as machine-readable adapter manifest with evidence paths.
- Added `scripts/verify-adapters.mjs` to validate adapter claims against evidence.
- Added `verify:adapters` npm script for standalone adapter verification.
- Added adapter wiring verification to `scripts/validate-release.mjs`.

### Changed

- Integrated adapter verification into release validation pipeline.
- Updated docs to reference adapter support matrix.
- Classified Pi adapter as `enforced` (has extension, smoke tests, hook guards).
- Classified Codex/Claude/Cursor adapters as `wired` (adapter files exist, install creates pointers, but no runtime enforcement).
- Classified AXGA/Generic adapters as `documented` (docs exist, but no dedicated verification).
- Classified OpenCode/Windsurf/Cline/Gemini/OpenClaw adapters as `planned` (no implementation yet).

### Notes

- Does not add Claude/Codex/OpenCode runtime adapter implementation.
- Does not start benchmark matrix runs.
- Preserves v0.5.3 command-rules.json source-of-truth and v0.5.4 classifier architecture.
- Claims require evidence: no adapter is claimed as "enforced" without smoke tests proving runtime enforcement.

## v0.5.6 - Classifier Git Global Flags Hotfix

### Added

- Added git global flags normalization in the command classifier. Commands like `git -C repo push`, `git -c user.name=test push`, and `git -C /tmp -c core.autocrlf=false push` are now correctly identified as `git push` for rule matching.
- Added smoke coverage for git global flags normalization (`-C`, `-c`, combined forms).

### Changed

- Improved command classifier to strip git global flags before rule matching, closing the gap where `git -C repo push` could bypass push detection.

### Notes

- Does not add Claude/Codex/OpenCode adapter implementation.
- Does not start benchmark matrix runs.
- Preserves v0.5.3 command-rules.json source-of-truth and v0.5.4 classifier architecture.
- Adapter Wiring Coverage is deferred to v0.5.7.

## v0.5.5 - Update Preservation & Tool Coverage

### Added

- Added update overlay preservation for `profiles/`, `workspace/`, `policies/`, and `safety/` in `update.sh` and `update.ps1`. Local overlays now survive updates by default alongside the existing `state/` preservation.
- Added `scripts/smoke-update-preserves-local-state.mjs` smoke test for update overlay preservation.
- Added `npm run smoke:update` script for update preservation verification.
- Added tool-agnostic command guard: `input.command` is now inspected for any command-bearing tool call, not just `bash`. This catches `shell` and other tool names that carry command input.
- Added multi-tool file write guard: `multi_edit`, `file_write`, `file_edit`, `fs.write`, and `filesystem.write` tool calls are now path-guarded alongside `write` and `edit`.
- Added backup suffix secret path detection for `.env.bak`, `.pem.bak`, `.key.bak`, `credentials.json.bak`, and `secrets.json.bak`.
- Added combined short-flag handling in the command classifier (e.g., `git clean -xdf` is now recognized as `git clean -fd`).
- Added smoke coverage for `shell` toolName command guarding, `multi_edit` path blocking, `file_write` secret path blocking, `git clean -xdf` classifier normalization, and backup suffix secret paths.

### Changed

- Update scripts now preserve local overlays (`profiles/`, `workspace/`, `policies/`, `safety/`) by default. `--reset-state` / `-ResetState` still resets only `state/`.
- Moved `validate-release.mjs` legacy pattern `rg` error handling inside the per-pattern loop so that `rg` exit 1 for no matches on one pattern does not skip remaining patterns.
- CI whitespace check now uses `git diff-tree --check --no-commit-id --root -r HEAD` instead of `git diff --check HEAD~1 HEAD || true`, making it enforcing.
- `npm run check` now includes `smoke:update`.

### Notes

- Does not add Claude/Codex/OpenCode adapter implementation.
- Does not start benchmark matrix runs.
- Does not add `"type": "module"` to `package.json` (deferred for separate risk assessment).

## v0.5.4 - Safety Classifier Hardening

### Added

- Added a local Pi/AXGA safety classifier before command-rule matching.
- Added normalization for repeated whitespace, case variants, simple command chains, and shell wrappers such as `bash -c`, `sh -c`, `cmd /c`, and PowerShell command wrappers.
- Added classifier coverage for publish/release variants, destructive delete variants, shell redirection writes outside `writesAllowedUnder`, sensitive reads, expanded secret paths, and obvious secret-like write content.
- Added smoke coverage for bypass forms including `git   push`, `GIT PUSH`, `bash -c "git push"`, package-manager publish variants, `rm -r -f`, `rm --recursive --force`, out-of-target redirection, secret-path writes, secret-content writes, and `cat .env`.

### Changed

- Kept `.heli-harness/safety/command-rules.json` as the policy source of truth while using classifier-normalized command variants to match rules more reliably.
- Expanded default command rules for common package-manager, release, and destructive command variants.
- Updated docs to clarify v0.5.4 is best-effort local classification, not a sandbox.

### Notes

- Enforcement still depends on compatible host `tool_call` hooks.
- Does not add Claude/Codex/OpenCode adapter implementation.
- Does not start benchmark matrix runs.

## v0.5.3 - Rules-as-Enforcement

### Added

- Pi/AXGA command guards now load `.heli-harness/safety/command-rules.json` as the runtime source of truth for configured bash command patterns.
- Added command-rule schema validation for release checks and safety lint.
- Added smoke coverage for default dangerous commands, custom command rules, invalid command-rule configs, and fallback blocking behavior.

### Changed

- Expanded default `command-rules.json` to include the full set of previously hardcoded bash guard patterns.
- Updated docs to clarify that command-rule enforcement depends on compatible host `tool_call` hooks and is not a sandbox.

### Notes

- Keeps v0.5.4 safety classifier hardening separate.
- Does not add Claude/Codex/OpenCode adapter implementation.
- Does not start benchmark matrix runs.

## v0.5.2 - Dogfood Lint Hotfix

### Fixed

- Fixed Pi/AXGA profile lint so `.heli-harness/profiles/README.md` and `*.example.md` files are not treated as active repo profiles.
- Added smoke coverage proving profile documentation is ignored, valid active profiles are still checked, and invalid active profiles still emit warnings.

### Notes

- Keeps v0.5.1 intact as published.
- Moves Rules-as-Enforcement to the next v0.5.x milestone.

## v0.5.1 - Self-Consistency and Dogfood Cleanup

### Changed

- Updated current install examples and user-facing Pi/AXGA adapter docs to v0.5.1.
- Added an active `heli-harness` repo profile and self-dogfood workspace target defaults.
- Moved the unrelated `agent-native-backend` profile to an example filename.
- Made policy exception sections explicit when no exceptions are approved.
- Clarified that OpenMesh-style benchmark content is illustrative and not measured evidence.
- Updated research and ADR language to separate hypothesis, design rationale, observed evidence, and measured benchmark results.
- Extended release validation to cover adapter docs, internal install docs, extension strings, shipped defaults, profile taxonomy, policy exceptions, and benchmark labeling.

### Notes

- Keeps the v0.5.x Full Coverage benchmark roadmap intact.
- Does not add Claude/Codex/OpenCode adapter implementation.
- Does not start benchmark matrix runs.

## v0.5.0 - Governance Benchmark Pack

### Added

- Added `benchmarks/` directory with repeatable governance benchmark templates.
- Added benchmark scenarios:
  - `docs-change.md` — low-risk docs task measuring report quality and minimality
  - `bugfix-small.md` — small bugfix measuring diagnosis, minimal diff, tests, report evidence
  - `feature-small.md` — small feature measuring scope control, implementation quality, validation
  - `multi-repo-targeting.md` — parent workspace task measuring target discipline
  - `unsafe-command.md` — risky command task measuring safety behavior
  - `tech-debt-pattern.md` — weak pattern task measuring tech debt classification
- Added scoring rubrics:
  - `scoring-rubric.md` — 0-3 scoring scale with category groupings
  - `metrics.md` — required and optional benchmark metrics
  - `report-completeness.md` — report quality scoring guide
  - `safety-score.md` — safety behavior scoring guide
  - `target-discipline.md` — target discipline scoring guide
- Added experiment templates:
  - `experiment-plan.md` — benchmark experiment planning template
  - `run-log.md` — run logging template
  - `scorecard.md` — scoring template with example
  - `comparison-report.md` — A/B/C/D mode comparison template
- Added example A/B/C/D benchmark (`openmesh-style-ab.md`).
- Added optional local benchmark summary script (`scripts/benchmark-summary.mjs`).
- Updated validation script to check benchmark pack presence.

### Changed

- Updated README.md with benchmark pack section and v0.5.0 install examples.
- Updated ROADMAP.md with v0.5.0 as current baseline and post-v0.5 stabilization section.
- Updated INSTALL.md and docs/INSTALL_MATRIX.md to v0.5.0.
- Updated governance model to include benchmark artifacts.
- Added `benchmarks/` to package.json files allowlist.

### Notes

- Keeps Heli lightweight, markdown-first, local, inspectable, and adapter-friendly.
- Benchmarks are local, manual, and telemetry-free.
- Does not add runtime orchestration, a database, hosted telemetry, or vector memory.
- Does not add a benchmark web dashboard or hosted service.
- Future stabilization work remains separate.

## v0.4.3 - CI and State Safety Polish

### Added

- Added GitHub Actions CI workflow (`.github/workflows/ci.yml`).
- Added local release validation script (`scripts/validate-release.mjs`).
- Added docs/version consistency checks in the validation script.
- Added advisory session lock template (`.heli-harness/state/session.lock.example.json`).
- Added advisory target lock template (`.heli-harness/workspace/target.lock.example.json`).
- Added `/heli-lock` command for showing advisory lock state.
- Added lock awareness to `/hh-status` (session lock, target lock, owner, expiration).
- Added lock lint through `/heli-validate lock` and `/heli-validate lint`.
- Added report template sections for lock context and parallel agent risk.
- Added report lint warnings for parallel work without lock state and lock conflicts without resolution.
- Added `check`, `smoke`, and `validate:release` package scripts.

### Changed

- Updated docs, templates, and governance model for advisory lock awareness.
- Updated install examples and baseline references to v0.4.3.

### Notes

- Keeps Heli lightweight, markdown-first, local, inspectable, and adapter-friendly.
- Locks are advisory warnings, not distributed locking.
- Does not add runtime orchestration, a database, hosted telemetry, or vector memory.
- v0.5.0 benchmark pack remains future work.

## v0.4.2 - Multi-Repo Targeting and Workspace Index

### Added

- Added `.heli-harness/workspace/` with `index.json`, `target.json`, and workspace notes.
- Added `/heli-target` for showing, listing, setting, and clearing active target repo state.
- Added workspace and target lint through `/heli-validate workspace` and `/heli-validate target`.

### Changed

- Improved `/hh-status` to show workspace index state, known repos, selected target, target git root, writes allowed under, target profile state, and cwd alignment.
- Added report template and lint checks for workspace root, target context, workspace index usage, and out-of-target warnings.
- Added conservative write-path guarding for ambiguous multi-repo workspaces and obvious out-of-target writes.

### Notes

- Keeps Heli lightweight, markdown-first, local, inspectable, and adapter-friendly.
- Does not add runtime orchestration, a database, hosted telemetry, vector memory, or cross-repo dependency solving.
- v0.5.0 benchmark work remains a future milestone.

## v0.4.1 - Profile Taxonomy and Tech-Debt Classification

### Added

- Strengthened repo profile taxonomy with explicit policy references, safer alternatives, evidence paths, and classification guidance.
- Added report template sections for active profile, taxonomy warnings, profile-based decisions, tech debt copied or avoided, safer alternatives chosen, and profile deviations.

### Changed

- Improved profile lint to warn on vague "follow existing patterns" language, missing evidence paths, missing safer alternatives, risky recommended conventions, and missing policy references.
- Updated `heli-init` guidance to require taxonomy classification and tech-debt framing for risky existing patterns.
- Updated docs and install examples to the `v0.4.1` baseline.

### Notes

- No runtime, orchestration, database, hosted telemetry, or vector memory expansion.
- v0.4.2 multi-repo targeting and v0.5.0 governance benchmark work remain future milestones.

## v0.4.0 - Policy Overlays

### Added

- Added `.heli-harness/policies/` with markdown-first templates for engineering, security, release, and testing rules.
- Added `.heli-harness/safety/` with command tiers, lightweight command rules JSON, and secret-handling guidance.
- Added policy and safety visibility in `/hh-status`.
- Added policy and safety lint through `/heli-validate lint`, `/heli-validate policy`, and `/heli-validate safety`.
- Added report checks for policies loaded, safety overlays loaded, approval evidence, safety events, and policy-deviation justification.

### Changed

- Updated repo profile and run report templates to keep profiles descriptive and move prescriptive rules into overlays.
- Improved profile lint so prescriptive language under descriptive sections is warned on.

### Notes

- Keeps Heli lightweight, markdown-first, local, inspectable, and adapter-friendly.
- Does not add runtime orchestration, a database, hosted telemetry, or vector memory.
- v0.4.1 profile taxonomy refinements and v0.4.2 multi-repo targeting remain future milestones.

## v0.3.3 - Status, Profile Lint, and Report Gates

### Added

- Improved `/hh-status` with version, workspace mode, profile, policies, hooks, recent hook activity, skill count, and probe state.
- Clearer `/heli-hooks` status with probe explanations and explicit one-shot probe state.
- Profile taxonomy lint through `/heli-validate lint` and `/heli-validate profile`.
- Report completeness lint through `/heli-validate lint` and `/heli-validate report`.
- Updated profile and run report templates for taxonomy and report gates.

### Notes

- No runtime, orchestration, database, hosted telemetry, or vector memory expansion.
- Heli remains lightweight, local, markdown-first, inspectable, and adapter-friendly.

## v0.3.2 - Hook Observability Probes

### Added

- `/heli-hooks probe`
- One-shot `before_agent_start` canary with `HELI_HOOK_OK`
- `/heli-hooks test-guard`
- One-shot `tool_call` guard canary with `HELI_GUARD_OK`
- Probe behavior stays opt-in and one-shot

### Changed

- Normal hook behavior is unchanged
- Extension smoke coverage now verifies probe and test-guard paths

## v0.3.1 - AXGA extension loader compatibility hotfix

### Fixed

- Fixed `tool_call` handler structure so `event` is only read inside the callback.
- Ensured AXGA can load `extensions/pi-extension.js` with plain loader-friendly JavaScript.
- Kept v0.3.0 safe auto hooks behavior, including `/heli-hooks`.
- Added extension load smoke validation for event hooks and commands.

## v0.3.0 - Safe Auto Hooks

### Added

- **session_start hook**: Detects workspace harness and shows status (active/package-only)
- **before_agent_start hook**: Injects compact safety rules when workspace exists
  - Instructs agent to read HARNESS.md, profiles, preserve dirty work
  - Prevents accidental mutating/release/push operations without approval
- **tool_call safety guard**: Blocks or confirms dangerous operations
  - Bash: `npm publish`, `git push`, `rm -rf`, release commands, API-credit-consuming commands
  - Files: `.env`, `.pem`, `.key`, credential files, legacy runtime folders
- **input shortcuts**: `/review`, `/audit`, `/validate`, `/impact` → `/heli-*` commands
- **/heli-hooks command**: Show auto hooks status
- Status bar integration: `heli: active` or `heli: package-only`

### Safety Guarantees

- No auto install
- No auto tests
- No auto commits
- No auto pushes
- No destructive automation
- All hooks respect workspace detection (only activate when `.heli-harness/HARNESS.md` exists)
- tool_call guard uses `ctx.ui.confirm()` when available, otherwise blocks by default

### Implementation Details

- Hooks only activate when workspace harness is detected
- before_agent_start appends compact rules to system prompt (does not override)
- tool_call guard checks both bash commands and file write/edit operations
- input shortcuts only transform exact matches, not natural language
- Status bar shows current workspace state

## v0.2.0 - Pi workflow commands

### Added

- `/heli-help` - Show Heli-Harness commands and what they do
- `/heli-init` - Bootstrap repo profile for a target repo
- `/heli-review` - Review current repo/diff/task safely
- `/heli-audit` - Repo-wide audit for issues and risks
- `/heli-validate` - Run test-validation workflow safely
- `/heli-impact` - Impact analysis for planned changes

### Changed

- All workflow commands are workspace-aware: check for `.heli-harness/HARNESS.md` before proceeding
- Commands suggest `/heli-install` if workspace harness is missing
- Added 6 namespaced wrapper skills to avoid skill name collisions
- Commands preserve safe, opt-in behavior
- Commands avoid legacy names.

### Notes

- No breaking changes
- No migration support added
- All commands are non-destructive by default

## 0.1.2 - 2026-06-28

### Docs-only polish

- Updated all install examples from v0.1.0 to v0.1.1
- Removed outdated "experimental" label from Pi adapter section
- Updated status notes to reflect verified Pi remote install for v0.1.1+
- No behavior changes
- No migration support added

## 0.1.1 - 2026-06-28

### Clean reference hotfix

- Fixed Claude hook example path to `.heli-harness` in `settings.local.json.example`
- Fixed `.gitignore` patterns to `.heli-harness`
- Confirmed zero legacy references in codebase
- No behavior changes
- No migration support added

## 0.1.0 - 2026-06-28

### Initial Heli-Harness release

- Parent-workspace harness for multi-repo, multi-agent engineering work
- 17 skills: audit, branch, debug, deps, design, engineering, feature, fix-loop, flow, gh-write, impact, incident, release, test-coverage, test-validation, verify-premise, workflow
- Pi package with skills + lightweight extension
- `/heli-install` and `/hh-install` commands for workspace setup
- `/hh-status` command for harness status reporting
- Safe opt-in workspace install (no auto-install on startup)
- Codex, Claude Code, Cursor, and Generic agent adapters
- Repo profiles, state tracking, task protocol
- Optional lifecycle hooks
- Profile templates
- Install, update, and uninstall scripts for Windows and macOS/Linux