# Changelog All notable changes to this project are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ## [5.0.1] - 2026-09-23 ### Fixed - `kyro update` automatically migrates redundant legacy `resolvedSprint` debt metadata when it matches `targetSprint`, preserving a recoverable backup and leaving contradictory or invalid records blocked for manual review. ## [5.0.0] - 2026-09-23 ### Added - Global npm installation and update guidance across the CLI help, active agent instructions, and documentation. The Windows CI matrix verifies installation and sync from the packaged tarball on Node 18, 20, and 22. ### Changed - `kyro update` verifies ownership of the active global command, installs an exact npm version, and refreshes the projected runtime from that new package. Preview modes report the planned action without writing files. - Projected CLI entrypoints resolve Windows command shims and retain the standalone Claude plugin route. Runtime-only users receive an explicit migration path to a global npm installation. - Scope identity, title, status, completion, reopen history, and retirement are read from each valid matching `scopes//sprint.json`. Shared `project.json` writes omit `scopes[]`, so creating distinct scopes in separate clones does not modify a shared registry. - Install and sync migrate the legacy shared `scopes[]` cache only when every entry has a valid matching sprint file and no lifecycle or custom metadata would be lost. Unresolved entries stop the migration with a diagnostic and retain the original evidence. - Layered close, completion, reopen, and retirement use scope-local lifecycle state. Older retirement checkpoints remain readable; approvals bind the affected scope and optional successor. - An already-current global CLI can run `kyro update` to sync a workspace with a legacy `scopes[]` cache. Previews remain read-only. ### Fixed - Update failures distinguish unavailable registry data, ambiguous command ownership, incomplete packages, and partial synchronization without reporting success. - Doctor and integrity repair identify unresolved legacy registry entries instead of silently dropping them. ## [4.51.0] - 2026-09-17 ### Added - **Honest live-work handoff.** Kyro never advertises `execute_task` without a dependency-ready task. Dead routes expose a structured `blocker` with a copy-pastable `remedyCommand` on `status`, `context-pack`, and error envelopes (`await_scope_completion` + `no_ready_work`). - **Live requirement and task correction in one `plan --update-active` request.** Remove a requirement or cancel a task atomically with relink/disposal of live consumers; previous evidence is kept and unrelated approvals survive. - **Scope-local `rule update|remove|replace`.** Replaced rules stop being effective while prior text stays in local history (typed and schema-validated). Project-wide `--global` mutation remains out of scope. - **Future-only `plan --roadmap`.** Retitle, add, cancel, or reorder `planned` roadmap entries without renumbering closed or active sprint identities. - **`scope discard`.** One informed approval (`--digest` + `--yes`) orchestrates cancel → abandoned close → retire through existing writers, resuming from the same digest if interrupted. - **Lazy `live-work.md` skill helper with doctor-after.** Agents apply a CLI-named remedy under existing work authority, then verify with `kyro doctor`. ## [4.50.0] - 2026-09-15 ### Added - **Controlled updates to active task definitions through `plan --update-active`.** Read-only diff/digest preview and confirmed, locked atomic apply preserve task identities and closed history while invalidating affected reviews and transitive dependents. Active requirements/scenarios may evolve without direct edits to managed state; no new command or task state is introduced. ### Fixed - Live reviews with changed material now appear as stale in analysis, task packs and status, block sprint close, and cannot be replayed as a current approval with an old digest. Unchanged legacy verdicts remain readable. - Dependency cycles are now reported by analysis and rejected by active-plan updates. Workflow instructions route active contract corrections through the existing planner rather than attempting next-sprint planning. - Temporary task blocks now skip checker review, preserve independent execution, and expose derived dependency blockers in status/context packs. New terminal `blocked` dispositions are rejected while legacy records remain readable. ## [4.49.4] - 2026-09-14 ### Fixed - **Guided active-sprint resolution before scope retirement.** The `/kyro:scope-retire` router no longer ends in an unactionable Forge referral when preparation returns `SPRINT_ALREADY_ACTIVE`: it guides separately approved `cancelled` task dispositions, a truthful `close-sprint --outcome abandoned`, and a fresh digest-bound retirement preparation. `scope retire` itself still never closes or discards an active sprint. ## [4.49.3] - 2026-09-13 ### Fixed - **QA-or-close context packs now expose the required analysis preflight.** When the final task review routes to `qa_or_close`, `context-pack` supplies the scoped `analyze` recipe that verifies no CRITICAL or HIGH findings block the decision. It deliberately does not present host-resolved `kyro qa ` as a CLI subcommand or advertise an automatic `close-sprint`; QA remains a scope-level optional certification and closing still requires explicit human approval. ### Changed - **Clarified QA boundaries in Forge guidance.** Task-level QA uses `review_task`; independent `kyro qa ` certification is available only after all tasks have passed review. ## [4.49.2] - 2026-09-12 ### Added - **Optional post-task QA-or-close routing.** A final passing task review now routes Forge to `qa_or_close`, where the user may invoke the existing read-only `kyro qa ` command/skill or close without QA. Blocking QA findings return to ordinary task execution through failed task reviews or emergent tasks, with mandatory re-QA inside the active session. ### Fixed - **Emergent tasks now restore executable routing.** `kyro add-emergent` updates the handoff to `execute_task` and selects the next executable task, preventing QA remediation added at the close boundary from leaving the router pointed at close. ## [4.49.1] - 2026-09-10 ### Fixed - **Pipeline skips snapshots for no-op directory operations and disposes backups on confirm.** `mkdir` over an existing directory and non-acting `rmdir-if-empty` no longer create recursive `kyro-pipeline-*` backups; mutating operations keep rollback for missing, file, directory, symlink, permission-mode, rmdir-acting and mkdir-new cases. `PipelineOrchestrator` now confirms registered backup roots after total success or clean rollback and retains them as diagnostic evidence when rollback itself fails. Snapshot creation failures (`mkdtemp`/`cpSync`) clean partial backups and fail closed before mutating the target. Adds `check:operation-snapshots` (S1/S1b/S2/S3/S4/S5/S6) to `npm run check` with reproducible time, bytes-copied and residual metrics and no claimed savings. ## [4.49.0] - 2026-09-09 ### Added - **One-step upgrades with `kyro update`.** Replaces the manual two-step flow (`npx kyro-ai install` plus `npm i -g kyro-ai`): checks the registry for the latest release, picks the lane by install mode (durable global `kyro` updates via `npm install -g kyro-ai@`; npx-only setups refresh via `npx -y kyro-ai@`), asks for confirmation unless `--yes`, then refreshes the global package, the runtime, and the current workspace from the fresh package. `kyro update --check` only reports the status, `--dry-run` previews the steps, and the registry query fails soft when offline. Operator surface like `install`/`sync`: not a tool-owned verb, so the capability handshake is untouched. See `docs/cli.md` (Update) and `docs/getting-started.md`. ## [4.48.3] - 2026-09-09 ### Fixed - **Doctor no longer reports a false FAIL on healthy Windows installs.** npm on Windows installs `.cmd`/`.ps1` shims rather than a real `kyro.exe`: Node's spawn without a shell ignores PATHEXT (`spawnSync("kyro")` fails with ENOENT) and spawning `kyro.cmd` directly is blocked since CVE-2024-27980 (EINVAL), so a bare `kyroInvocation: "kyro"` manifest value could never self-spawn via `doctor` — `CLI invocation` and `CLI capabilities` went red on installations where everything else passed. The installer now persists the `node /dist/cli.js` form on Windows, and `doctor` resolves legacy bare values via the projected runtime (`process.execPath` + `/dist/cli.js`) instead of failing. No action needed on existing installs: legacy manifests pass as-is and migrate naturally on the next install/sync. The invocation remedy text now documents the Windows behavior so it no longer points at a dead-end reinstall. ## [4.48.2] - 2026-09-08 ### Fixed - **Forge no longer sends scope creation through repair/recovery.** The router startup used to run `repair integrity prepare` against the resolved scope id before knowing whether the scope exists, so every create-from-plan flow stopped on a false `irreconcilable` blocker. The existence gate now comes first: a scope that is neither registered nor on disk is a creation flow and routes straight to INIT without `repair` or `context-pack`; the repair preflight is existing-scope-only, and recover mode is fenced to scopes that exist. - **Exhausted roadmaps await an explicit decision.** Closing the final roadmap sprint now writes `handoff.nextAction: await_scope_completion`, rather than falsely routing to `plan_sprint`. Forge and context packs present the two valid choices: confirmed scope completion (preview, then explicit confirmation) or explicit expansion with a new sprint. Scope status remains `planning`; no completion is inferred and no planning mode is auto-loaded. - **Historical close checkpoints keep verifying.** The new `await-scope-decision` policy is separate from the exact historical `open-scope` transition, so the verifier still accepts checkpoints written by 4.48.0/4.48.1 (including the legacy `plan_sprint` final close) byte for byte. Tampered after-images are still rejected, including rehashed tampering. - **Real end-to-end coverage for the exhausted-roadmap path.** Adds frozen cross-version close fixtures (with provenance, retries and tamper rejection) plus a real close → checkpoint → decision → explicit expansion regression. `plan --help` now documents both `plan_sprint` and `await_scope_completion`. Compatibility note: Kyro Lens support for the new `await_scope_completion` action is deferred to a later Lens release and is out of scope for this version. Existing scopes are not migrated; use the CLI until then. ## [4.48.1] - 2026-09-07 ### Fixed - **Forge routes finished-scope closure to `scope complete`.** After adaptive lifecycle stopped inferring completion from the last sprint, agents matched "close the scope" to `kyro-scope-retire` because Forge ignored user intent and skill discovery advertised retirement as the only scope-level terminal path. Forge now overlays complete/close/finish (including "cierre del scope") onto `kyro scope complete` before `nextAction`, idle `plan_sprint` packs also offer that recipe, and the retire router refuses completion language. No new slash command or skill. ## [4.48.0] - 2026-08-29 ### Added - **Machine-actionable CLI contract.** Tool-owned CLI verbs accept `--json` before or after the command and return one versioned envelope on stdout. Errors preserve non-zero exit codes while exposing a stable code, remedy, optional command, and structured details. - **Idempotent review requests.** `review --dry-run --json` exposes a canonical request digest; `review --digest --yes` revalidates it under lock. Exact retries are no-ops, while stale reviewed material fails closed with `REVIEW_REQUEST_DIVERGED`. - **Git trackability diagnostic.** Doctor now reports ignored shared Kyro state with exact `.gitignore` remedies, and skips the check outside Git workspaces. ### Changed - **CLI-owned artifact policy.** Canonical and projected workflow assets no longer authorize manual writes to managed state. Missing or incompatible runtimes stop with a precise upgrade command; the Claude `PreToolUse` hook is documented as defense in depth, not portable authority. - **Lifecycle replay** is declarative and linear: sprint and registry projection share transition builders, canonicalize history records once, and accumulate post-checkpoint histories without repeatedly copying growing arrays. ## [4.47.3] - 2026-08-20 ### Fixed - **Adaptive lifecycle replay hardening.** Consolidated digest derivation for scope completion and reopen into shared `lifecycle-state.ts`, so the verifier and every writer use the exact same formula. Added typed verification status constants (`CHECKPOINT_EXACT`, `LIFECYCLE_REPLAYED`, `DIVERGED`, `UNSUPPORTED`) with fail-closed replay validation for post-close scope transitions. Close-sprint now reads the normalized outcome from the sealed transaction checkpoint rather than the CLI argument object, preventing stale outcome propagation through trace events. - **Artifact doctor lifecycle verification** now replays recorded transitions and matches both `sprint.json` and the project registry together against a shared projection. - **MCP handler** lifecycle state routing fix. ### Changed - **Documentation** updates for lifecycle verification trust boundary, selective `.agents/` gitignore patterns (shared `project.json` and `scopes/` tracked; `trace/` and `local.json` ignored), and status coherence contracts. - **Verification scripts** `check:close-handoff` and `check:scope-retire` expanded to enforce lifecycle and retirement handoff contracts. - **Remediation and repair integrity** plan modules updated for lifecycle-aware drift detection and recovery path selection. ## [4.47.2] - 2026-08-18 ### Fixed - **Scope identity now comes from evidence, not from a directory existing.** `listScopeFolders()` treated every directory under `.agents/kyro/scopes/` as a scope, so a notes folder, an editor artifact or a half-finished checkout became an `IRRECONCILABLE` integrity blocker — and install/sync's rehydrate minted it into `project.json` with a fabricated `planning` status, turning a filesystem accident into persisted project state. Directories are now classified as `VALID_SCOPE`, `CORRUPT_SPRINT`, `RECOVERABLE`, `OWNED_DAMAGED` or `FOREIGN`, and the action is derived from that class crossed with whether the registry knows the id. - Ownership is proved only by names Kyro itself writes, and only when they are **regular files**: `sprint.json`, `retirement.checkpoint.json`, an `archive/sprint-NNN-.{json,md,checkpoint.json}` close artifact, any `archive/*.checkpoint.json`, or a record file inside its own directory — `archive/certifications/certification-NNN.json`, `archive/remediations/remediation-NNN.json`, `archive/checkpoint-remediations/canonicalization-NNN.json`. `NNN` is three digits or more, matching what every writer pads to, so `remediation-1.json` is a name Kyro cannot produce and is not recognized. A symlink wearing one of these names is not recognized either: where the name is the whole proof, anything reachable on the filesystem could otherwise claim a directory as Kyro's. A directory alone is never evidence — `archive/` is an ordinary word, so a human's `notes-backup/archive/README.md` stays `FOREIGN`, and an empty `archive/remediations/` holds no history to protect, so it stays `FOREIGN` too. A record whose bytes are corrupt still counts: the recognizable name is what proves Kyro wrote there, not whether the file still parses. - A `FOREIGN` directory is ignored by discovery, resolution, `scope list` and integrity, is never registered, and is reported by a **global** `doctor` as a non-blocking WARN so the user still learns why their folder is not a scope. This includes an unregistered namespace entry whose scope root, `sprint.json` or `archive/` is a symlink: Kyro reports the managed level but never follows or reveals the link target. A scoped `doctor` never mentions it. - `RECOVERABLE` (sprint.json gone, at least one close checkpoint that actually resolves and names this scope) is reported as `recoverable-no-sprint` and points at the checkpoint resume path. `OWNED_DAMAGED` (Kyro artifacts, but nothing resumable) is reported separately and promises nothing — a remediation record, a corrupt checkpoint or a checkpoint symlink is not a recovery path. Checkpoint discovery uses the same safe-path contract as `close-sprint`, so it never advertises a resume that the transaction reader will reject. Scope roots, `sprint.json`, `archive/` and checkpoint candidates are inspected without dereferencing symlinks; any unsafe ancestor on a registered or otherwise Kyro-owned scope is `OWNED_DAMAGED`, produces no repair operations or commitments, and must be restored as a real managed path. - A registered id whose directory is `FOREIGN` is now a `REGISTERED_ORPHAN`, so `repair integrity` can clean up contamination an earlier rehydrate wrote. `unregister-orphan` previously refused whenever the path existed at all, which made that cleanup impossible; it now re-verifies the directory is still foreign, removes only the registry entry, and never touches a byte of the directory. If the directory becomes a symlink, unsafe path or gains Kyro evidence between prepare and apply, apply returns `DIVERGED` without writing. - An explicit `--kyro-scope` pointing at an **unregistered** foreign directory fails `SCOPE_NOT_FOUND` across `status`, `context-pack`, `repair integrity prepare` and `doctor --artifacts`, instead of being reported as a damaged scope. A *registered* id whose directory is foreign stays addressable — it is a registry entry to clean, not a wrong name — so the contamination above can be repaired scoped, not only through a global scan. - A registered scope whose `sprint.json` is invalid no longer classifies as healthy: it previously fell through to `present-and-registered` because identity derivation returned null and nothing checked. - The 4.47.1 special case that skipped `trace/`-only leftovers is removed — the general rule subsumes it. - **State-writer heartbeat startup under load.** The keeper still must complete and durably publish its first renewal before protected work starts, but its startup budget is now derived from the active lease instead of an arbitrary two-second ceiling. This removes false startup failures on loaded filesystems without weakening token, inode, expiry or fail-stop checks. Protected writes also wait for an explicitly fenced heartbeat publication to finish before revalidating ownership, avoiding false lease loss when Windows briefly hides the rename-over-existing target. ## [4.47.1] - 2026-08-16 ### Fixed - **Integrity blast radius.** `repair integrity prepare` invoked with no `--kyro-scope` (the router, the sprint-forge skill, the orchestrator, and recover mode's post-repair `doctor --artifacts`) used to scan every scope before the target scope was even resolved, so drift in one scope could block routing, closing, or recovery of an unrelated, healthy scope. All four startup surfaces now resolve the target scope first and pass `--kyro-scope` through prepare, apply, and the post-repair doctor check. A global scan (no `--kyro-scope`) is still available and still reports every scope — it is just never run implicitly during routing anymore. - **Trace moved out of `scopes/`.** `traceDir` now writes to `.agents/kyro/trace/{scope}/`, a sibling of `.agents/kyro/scopes/`, instead of a child of it. Previously any trace write for a scope name without a `sprint.json` (a stale guard, a retry, a phantom target) could create a directory under `scopes/` that discovery then misclassified as an invalid scope — the same mechanism behind an earlier blast-radius incident. `kyro trace` and `doctor --trace` transparently merge pre-upgrade history from the old location, and `kyro trace --clear` removes both. Scope discovery (`listScopeFolders`) also now ignores any existing directory whose only content is a leftover `trace/` folder, so upgraded installs stop carrying phantom scopes forward. ## [4.47.0] - 2026-08-14 ### Added - **`kyro repair integrity prepare|apply`.** A composed, human-gated repair for registry drift, recoverable legacy checkpoint metadata (append-only overlays; original bytes stay intact), and typed post-close live evolution (`convention.append`, `adr.append`, `ledger.checkpoint.reanchor` on remediations protocol v4). `/kyro:forge` runs a silent prepare *before* scope resolution; empty findings add no user step. Recover mode presents every target, one digest, and applies only after approval. Apply is warrant-first and idempotent for the same digest. Unsupported, diverged, irreconcilable, and identity conflicts are explicit blockers. Overlays carry a `recordCommitment` and are verified by rebuilding the projection from original bytes. ### Changed - Doctor, ledger validation, retire, remediations, and recertify share `resolveEffectiveCheckpoint`. A valid overlay is reported as `CANONICALIZED`, never as a healthy original file. - Forge recover mode no longer authorizes hand-writing `sprint.json`. - `runtimeForgeExecuteTokens` 4180 → 4320 so the execute route can carry the integrity-prepare-first startup step. Trimming that step to keep the old ceiling would leave recovery unreachable when `activeScope` is empty. ## [4.46.0] - 2026-08-14 ### Added - **Human-gated `kyro scope retire`.** Adds a read-only preparation phase with a state-bound digest and a separate `--digest --yes` apply phase. Retirement is locked, CAS-protected, resumable and idempotent; records reason/date/successor, routes to `done`, and never modifies or deletes existing `archive/` checkpoints, snapshots or narratives. The shared write boundary rejects later attempts to mutate a retired `sprint.json`. ## [4.45.0] - 2026-08-10 ### Added - **`kyro clarify --from `.** A tool-owned clarification writer that records one accepted decision at a time or an explicitly deferred batch, validates every target and derived requirement before writing, and advances routing only after all open questions and markers are resolved. ### Changed - **Clarify is now a guided conversation.** The workflow explains why the scope is paused, asks one contextual question at a time, presents evidence-backed options and trade-offs, and never falls back to editing `sprint.json` when a CLI verb is unavailable. ## [4.44.0] - 2026-08-10 ### Added - **`debt.canonicalize` (remediation protocol v3).** A typed append-only operation that repairs a whole legacy debt record — broken or absent canonical fields *and* legacy-only keys such as `detail`, `resolution` and `addedSprint` — producing exactly the seven canonical keys as an explicit after-image and naming the keys it retires. It binds the whole observed debt with a SHA-256 precondition and resolves the record's field issues atomically, without becoming a generic patch. Older readers treat a v3 record as `unsupported` rather than partially understanding it. - **`kyro remediate canonicalize-prepare` and `canonicalize-preview`.** Both are read-only. Preparation reports what is observed, what is still undecided, and the evidence behind each suggestion; it returns `INPUT_REQUIRED` and produces no manifest while any canonical value is unsettled. A suggested value is never an authorization — only values passed explicitly become canonical values. - **`check:original-incident-release`.** A release gate that runs the faithful legacy fixture through the built source *and* through the packed tarball installed into a fresh temporary prefix, inventories every checkpoint, snapshot, narrative and ledger commitment by SHA-256 before and after, and can additionally probe a real local scope read-only while remediating only a temporary copy. It reports the globally installed runtime as a compatibility observation and never writes to it. ### Changed - **Kyro 4.43.5 is documented as origin-only.** It repairs `origin` and nothing else, and cannot remediate a record-level legacy shape. There is no automatic migration: installing this version never rewrites an existing scope, and Doctor never repairs one on your behalf. See [docs/cli.md](docs/cli.md) for the supported operator workflow. ## [4.43.5] - 2026-08-09 ### Added - **Append-only scope remediation and recertification.** `kyro remediate preview|apply` applies explicitly typed, preconditioned corrections without rewriting immutable checkpoints; `kyro recertify` records a chain-bound certification after verification. Replay witnesses are versioned and compact, so verification remains fail-closed without unbounded SprintFile snapshots. ### Fixed - **Newly initialized scopes now become the local active scope.** `kyro plan --from` registers the scope in shared state and selects it in `local.json`, preventing subsequent commands without `--kyro-scope` from silently targeting the prior scope. - **Doctor no longer blesses unaudited post-close drift.** A ledger anchor alone does not prove a live mutation was tool-owned; only a replay-verified append-only remediation can move a closed scope off its checkpoint after-image without `DIVERGED`. ## [4.43.4] - 2026-08-06 ### Fixed - **Doctor false DIVERGED after legitimate post-close mutations (e.g. `kyro rule add`).** Live `sprint.json` may evolve after a successful close while the ledger still anchors the checkpoint. Doctor now reports APPLIED with `sprint=after (post-close evolution)` instead of treating that as a failed close. `repair` still only normalizes derived status — it does not restore checkpoint after-images (and must not wipe intentional post-close rules/debt/ADRs). - **`plan --from` init left `plan_sprint` when `spec.openQuestions` was non-empty.** Init mode now routes `handoff.nextAction` to `clarify` when open questions remain (in addition to `[NEEDS CLARIFICATION]` markers), matching the documented clarify drain for open questions. - **Windows CI: concurrent close holder tests lost a 1s lease under matrix load.** `CI_SAFE_TEST_LEASE_MS` raised to 5s for concurrent close/repair holder cases (reclaim still uses explicit sub-second leases). ## [4.43.3] - 2026-08-05 ### Fixed - **Claude exposed Kyro's internal workflow engines as user slash commands.** Claude Code always auto-discovers a plugin-root `skills/` directory, and the manifest's `skills` field adds paths instead of acting as a whitelist. The plugin therefore registered nine skills: the five public commands plus `sprint-forge`, `seedbed`, `qa-review`, and `kyro-sprint-executor`. Packaged engines now live under `internal/skills/`; Claude registers five provider wrappers that delegate to the canonical routers, while runtime installation still projects the engines to the stable `~/.agents/kyro/current/skills/` path for Standard, Codex, and OpenCode. ### Tests - Added `check:claude-plugin-surface` to enforce exactly five Claude commands, no plugin-root `skills/`, no registered internal agents, wrapper parity with canonical routers, and presence of every internal engine source. - Certified the local marketplace with Claude Code's validator and isolated plugin inventory: five skills (`forge`, `idea`, `qa`, `status`, `task-context`), zero agents, and no internal names. ## [4.43.2] - 2026-08-05 ### Fixed - **The projected runtime TUI advertised install actions that it must reject.** Running the canonical projected invocation without arguments displayed the full-package installer menu; choosing any adapter called `install()` and then failed with `INVALID_INPUT`. The TUI now detects its package-root mode: verified full packages retain adapter installation, while projected and unknown roots show the full-package remedy and expose only Doctor and Exit. Explicit projected `install` and `sync` commands remain fail-closed. ### Tests - Added full-package, projected-runtime, and unknown-root TUI coverage to the packaged runtime smoke, including Doctor routing and proof that restricted Exit does not acquire the writer lock. ### Docs - Documented package-root-aware TUI behavior and added `docs/plans/plan-12-package-root-aware-tui.md`. ## [4.43.1] - 2026-08-05 ### Fixed - **Windows CI: frozen legacy checkpoint fixture reported `snapshot=conflict, narrative=conflict`.** Global `*.json`/`*.md` text attributes checked out CRLF on Windows, breaking `digests.legacySnapshot` / `digests.narrative`. Fixture path now forces `text eol=lf`, and the lossless-check installer normalizes CRLF→LF before writing sandbox artifacts. - **Intermediate sprint close left `projectScopeAfter.status = active` while repair derived `planning`.** Since lossless checkpoint v1 (4.19.0), intermediate closes copied the before scope entry into the after image. `deriveScopeStatus` and `kyro repair` correctly yield `planning` when no sprint is active and roadmap work remains, so `doctor --artifacts` reported `DIVERGED: scope=other` after a correct repair. New closes now set `projectScopeAfter.status` via `deriveScopeStatus` (`planning` for intermediate and empty-roadmap edges; `completed` when every non-empty roadmap sprint is closed). Historical intermediate residual-`active` checkpoints stay immutable: validate and doctor accept only the exact v1 copy-before shape at read time (active before, canonically identical active after; live `planning` counts as applied after) without rewriting archives or bumping `schemaVersion`. Self-consistent before/after transitions that v1 could not emit remain `CORRUPT` even when their internal digests and ledger commitment are recomputed. ### Docs - Documented intermediate/final/empty-roadmap scope status and historical v1 residual compatibility in `docs/sprint-close-checkpoints.md`. - Implementation plan: `docs/plans/plan-10-intermediate-close-scope-status.md`. - Post-implementation semantic hardening: `docs/plans/plan-11-legacy-checkpoint-semantic-hardening.md`. ## [4.43.0] - 2026-08-05 Second field incident. 4.42.0 worked as intended — the agent ran the Step 0 handshake and materialized `sprint.json` through `plan --from` — but the same failure reappeared one file over: it hand-wrote `project.json` and `local.json`. It did so because Kyro told it to. ### Fixed - **`plan --from` reported success over project state that `doctor` rejects.** `registerScopeInProjectState` returned early when the scope was already in the registry, skipping the write and with it the normalization. A workspace whose `project.json` had been hand-authored but already listed the scope survived untouched, and the command still printed "Scope initialized" — while `kyro doctor` failed on that same state. The agent read the success line, concluded Kyro had not written the files, and hand-patched them. The shape is now verified on every run and a bad state fails with `INVALID_PROJECT_STATE` instead of riding along under a success message. - **`install --init-workspace` silently destroyed content.** The clone helpers picked only canonical keys, so a hand-authored entry (`name` for `title`, `principle` for `rule`, `non_negotiable` for `severity`) collapsed to `{ id }` — the rule text gone — and `doctor` still failed afterwards because the required field was now missing. This was the remedy `doctor` itself printed. Known aliases are now mapped, and anything with no recoverable text is named in a warning rather than quietly dropped. - **`docs/getting-started.md`** referenced `kyro delegate`, a verb that does not exist. Found by the new check on its first run. - **Windows CI flake in `check:lossless-checkpoints`.** The raw-heartbeat-exit case waited on a file the worker only writes on its 2nd renewal, under a 1000ms lease. The worker renews every `lease/3`, so two renewals consumed 666ms and left ~334ms of absolute slack for Worker spin-up — enough on Linux, not on a loaded Windows runner, where the owner fail-stopped with "Lease heartbeat expired or changed" before the injected exit ran. The test read that as "worker did not perform injected raw exit", so the same commit went green on one run and red on the next. The lease for cases that must *observe* a heartbeat event is now 5000ms (~1667ms slack) with the arithmetic documented; cases that merely assert the owner was fenced keep the short lease, since they pass under either failure path. ### Added - The `PreToolUse` guard now covers `project.json` and `local.json`, not just `sprint.json`. Both are CLI-owned; a hand-write that leaves them invalid is blocked with the command that owns them. - `check:cli-verbs` fails the build when any asset references a CLI verb the dispatcher does not accept, reading the real list from `src/cli/app.ts` so it cannot drift. Agents have twice closed a session by telling the user to run a command Kyro never had (`execute`, then `execute_task`); both exit `UNKNOWN_COMMAND`. Lines that name a verb in order to deny it are allowed. - `execute-task.md` states plainly that no verb executes a task, and gives the three handoff lines to use instead — the gap agents were filling by inventing. ## [4.42.0] - 2026-08-05 Closes the path that let an agent hand-author a whole Kyro scope. Observed in the field: a session invoked `kyro-ai:sprint-forge` directly (never through `/kyro:forge` → orchestrator), never ran the CLI once, and wrote a 14.7 KB `sprint.json` with no `schemaVersion` and no `handoff` — an artifact `context-pack` cannot route at all. ### Added - `sprint-forge/SKILL.md` now carries the full startup handshake as a mandatory **Step 0**: resolve `{{KYRO_CLI}}`, read project state, resolve scope, run `capabilities --json`, route via `context-pack`, load one mode. The skill is invocable on its own, and on that path the orchestrator — which previously held the only copy of these steps — is never loaded. - The `PreToolUse` guard now blocks creating a scope `sprint.json` whose shape is not routable (missing `schemaVersion: 4`, `scope`, `handoff.nextAction`, or an `activeSprint` that is neither a sprint object nor `null`). The gate is minimal by design: the hand-write fallback INIT.md authorizes when the CLI cannot run, and recover.md's rebuild, both still pass. - `check:startup-contract` keeps the handshake in sync across `agents/orchestrator.md` and `skills/sprint-forge/SKILL.md`; `check:sprint-guard` covers the guard's 20-case allow/block matrix. ### Added - `check:token-budgets` runs the token-audit assertions inside `npm run check`. Previously the only budget gate was `check:tokens` (`doctor --tokens`), which also runs environment-dependent doctor checks — installed runtime version, CLI capabilities, project state — so it could not be wired into the local suite without going red for unrelated reasons. Budget regressions therefore surfaced only in CI, which is exactly how 4.42.0 shipped a `SKILL.md` 363 words over its ceiling. ### Fixed - The token auditor measured a different runtime path depending on the machine. With no runtime installed it fell back to a hand-written 34-word stub for the projected command router, while the real projection is ~134 words — so CI read ~134 tokens lower per path than any machine with Kyro installed. The fallback now comes from `buildCommandSkill()`, the same generator install uses; CI and a real machine agree to within a token. ### Changed - Token budgets raised to fit the Step 0 startup contract, which `SKILL.md` now carries on every route: `sprintForgeSkillWords` 800 → 1280, and the six forge path ceilings plus `runtimeStatusBriefTokens` re-sized with the 10% headroom the policy already declared. Trimming the contract to fit the old ceiling was the wrong trade — a scope hand-authored without the handshake costs far more than the tokens it saves. - Path budgets are now sized against a machine with the runtime **installed** (projected router ~180t), not a bare checkout (stub router ~46t). CI measures the stub and reads ~134 tokens lower per path, so the previous sizing would have left `kyro doctor --tokens` failing for every real user while CI stayed green. ### Fixed - Plugin/marketplace installs never ran the `{{KYRO_CLI}}` substitution, so agents entering through the skill read command tables full of literal `{{KYRO_CLI}}` tokens and concluded no CLI existed. Step 0's resolution ladder (`kyro --version` → `~/.agents/kyro/current/dist/cli.js` → STOP) makes the skill self-sufficient on that channel. - `INIT.md` Step 6 told agents to create `.agents/kyro/kyro.json` in the monolito shape — the exact file install is forbidden to leave behind. It now verifies the layered `project.json` + `local.json` that `{{KYRO_CLI}} plan --from` already writes, and never authors project state. `principles[]` references corrected to `project.json` in `plan-sprint.md` and `review-task.md`. - The guard only matched on basename, so it policed any `sprint.json` anywhere on disk. It is now scoped to `.agents/kyro/scopes/`. - `kyro plan --help` said it registers the scope in `kyro.json`; it writes `project.json`/`local.json`. ## [4.41.5] - 2026-08-04 ### Fixed - Claude Code plugin no longer fails to load with `Duplicate hooks file detected` for `hooks/hooks.json`. The standard plugin-root path is loaded automatically; `plugin.json` must not re-declare it. Bump past 4.41.4 so marketplace installs pick up the fix. ## [4.41.4] - 2026-08-04 ### Fixed - Claude Code plugin hooks live at the plugin root (`hooks/hooks.json`) so the manifest path resolves correctly after marketplace install. - State-writer lock: retry transient Windows heartbeat I/O errors (`EPERM`/`EACCES`/`EBUSY`) from the published lease — including the first renewal — and clean orphaned heartbeat temps on release so install smoke no longer dies with silent SIGKILL or `ENOTEMPTY`. ## [4.41.2] - 2026-08-01 ### Fixed - Windows installations no longer fail with `EPERM: operation not permitted, fsync` while acquiring or renewing the state-writer lock. Directory `fsync` treats Windows `EPERM` as an unsupported durability enhancement while file `fsync`, lock ownership, heartbeat, lease, and fencing remain strict. - Failed lock initialization, release, and stale-lock reclaim now attempt verified directory removal even when a directory sync fails, preventing empty lock or reclaim directories from wedging later writers. - Stale-lock reclaim keeps Windows `dev`/`ino` identities as lossless `bigint` values through verification, avoiding false ownership changes when NTFS file IDs exceed JavaScript's safe integer range. - The directory-sync policy test can explicitly force strict non-Windows behavior, so Windows CI validates both the strict and portable `EPERM` branches. - ESM-based verification scripts convert absolute module paths with `pathToFileURL`, preventing Windows drive letters such as `D:` from being misread as unsupported URL schemes. ### Added - Windows CI covers Node.js 18, 20, and 22 with the lossless checkpoint suite, an `lstat`/`fstat` identity probe, and two consecutive workspace installs that must leave no state-writer lock residue. ## [4.41.1] - 2026-08-01 ### Added - `kyro rule add` registers an operational convention in the active scope without hand-editing `sprint.json`. Agents now ask whether the rule should also persist globally; `--global` writes it to shared `project.json.conventions[]`, and `context-pack` inherits global rules into every scope. - `scripts/check-rule.mjs` covers scope-only registration, global promotion, cross-scope inheritance, duplicate refusal, missing layered-state refusal, and the agent-facing “ask before global” contract. ### Changed - Sprint-forge, the standalone sprint executor, and the orchestrator now define “register a Kyro rule” explicitly and prohibit `RULES.md`/`rules.md` fallbacks. Missing `rule` capability is an upgrade blocker, never permission to edit managed JSON manually. ## [4.41.0] - 2026-07-29 Follow-up to 4.40.0 from a second Codex field test (~7h, 6 sprints closed). The 4.40.0 handshake and close gate both held; this release closes the three defects the run exposed instead. ### Added - `kyro capabilities` now advertises `status`, `scenario`, and `adr`. `status` was already invoked by the shipped assets (`{{KYRO_CLI}} status full`) while absent from the payload, so an agent validating its verbs strictly would abort on a verb the CLI has. `scenario` and `adr` are tool-owned `sprint.json` writers documented for agent use. - `scripts/check-capabilities.mjs` enforces the capability contract in both directions, so it cannot silently drift again: every `{{KYRO_CLI}} ` the shipped assets invoke must be advertised (exempting `capabilities` itself, which cannot verify itself), and every advertised verb must be dispatchable by the CLI. ### Changed - `kyro doctor` escalates an unpinned projected full skill from WARN to FAIL. Command stubs predate the `runtimeVersion` pin, so an unpinned one is legacy (still WARN); full skills only ever shipped with a pin, so an unpinned file at that managed path is foreign or hand-edited content shadowing the projected skill. That is how an old `kyro-sprint-executor` draft with no capability handshake and no close gate ran unnoticed for two sprints — both closed without the user approval the gate requires. ### Fixed - `kyro close-sprint` no longer hangs outside a TTY. It is the only verb that confirms interactively; in an agent harness, CI, or a piped shell the `[y/N]` prompt blocked on stdin that never arrives until the caller timed out. It now fails immediately with `CONFIRMATION_REQUIRED` and a remedy naming `--yes`. The MCP path is unaffected (it calls `buildClosePlan` directly). ## [4.40.0] - 2026-07-29 Closes the three integrity gaps surfaced by the Codex field test: version drift with no handshake, no fail-closed path when a tool-owned verb is missing, and hand-forged evidence that the checker could not distinguish from tool-written evidence. ### Added - New skill `skills/kyro-sprint-executor` — strict standalone sprint executor for external hosts (Codex, OpenCode, …) that don't load the full plugin. Thin by design: defers routing to `context-pack` and never duplicates sprint-forge modes; opens with the Step 0 capability handshake, gives exact tool-owned CLI usage lines per stage (pack → implement → validate → `record-evidence` → `review`), covers `--status blocked` after three failed rounds, emergent tasks, debt, the clarification gate, and checker-veto semantics, and gates `close-sprint` behind explicit user approval. Projected to every agent skill root (`~/.agents/skills/`, OpenCode skills dir) on install/sync with `{{KYRO_CLI}}` substitution and a `runtimeVersion` pin, managed like the command stubs (sync replaces, uninstall/preflight/drift/doctor cover it, `skill/runtime version` skew check includes it). - `kyro capabilities [--json]` — runtime capability handshake. Lists the tool-owned verbs this CLI exposes plus its version. The orchestrator runs it at forge start; an `UNKNOWN_COMMAND` failure on the command itself proves the installed runtime predates the handshake, so fail-closed works even against old binaries. New `scripts/check-capabilities.mjs` in the `npm run check` chain. - `kyro doctor` — new `CLI capabilities` check: probes the installed runtime (persisted invocation) with `capabilities --json` and FAILs when any verb the shipped skill assets invoke is missing. Catches exactly the field failure: new skill assets projected next to an old installed binary. ### Changed - Skill assets now define the fail-closed path for a missing CLI verb (`agents/orchestrator.md` startup handshake step; `skills/sprint-forge/SKILL.md` invariant 9; `execute-task.md`, `review-task.md`, `delegated-execution.md`, `delegates/implementer.md`, `delegates/checker.md`): if `record-evidence`/`review` is unknown to the CLI, ABORT the forge and report `kyro --version` — hand-writing evidence or verdicts is never a permitted fallback. Previously the assets prohibited hand-edits but named no action for the missing-verb case, which is the gap the field agent rationalized through. ### Fixed - Checker now vetoes hand-forged evidence timestamps: `evidence.recordedAt` more than 5 minutes ahead of the review clock — or unparsable — is a HIGH finding that blocks `kyro review --verdict pass`. `record-evidence` stamps its own clock, so a future `recordedAt` proves a hand-edit; no write-time change was needed. The pre-existing verdict-predates-evidence ordering check gained the same 5-minute skew tolerance so honest cross-host clock drift does not false-positive. - `kyro review` and `kyro close-sprint` reject `--dry-run --yes` as mutually exclusive (`INVALID_INPUT`). Previously dry-run silently short-circuited and the `--yes` was ignored. ## [4.39.0] - 2026-07-27 ### Fixed - **`docs/delegation-flow.md`, `docs/getting-started.md`, `docs/maker-checker.md`** — add explicit warnings that `record-evidence` does not accept `--yes`/`--confirm` (those flags belong to `review`); prevent orchestrator CLI flag trap. - **`skills/sprint-forge/assets/helpers/delegated-execution.md`, `skills/sprint-forge/assets/modes/execute-task.md`** — document CLI flag restriction on `record-evidence` to prevent `INVALID_INPUT` errors. ## [4.38.0] - 2026-07-25 ### Added - **`docs/delegation-flow.md`** — practical end-to-end overview (7 sections + Mermaid diagrams) from scope/sprint/task planning through execute/review with optional L0/L1 delegates; linked from architecture and getting-started. - **Delegation terminology** — rename `minion` / `minionEnabled` to `delegate` / `delegationEnabled`; move role helpers to `delegates/`; update docs, modes, CLI, and eval fixtures (`context-pack-delegation-*`). - **Delegation protocol in core docs** — L0/L1 behavior consolidated into `architecture.md`, `maker-checker.md`, `context-management.md`, `teams.md`, and `cli.md`. ### Changed - **Delegation fail-safe on slim modes** — `execute-task` / `review-task` keep a hard safety contract on the opt-in path (must load protocol + role helpers; CLI owns SoT; no invented evidence/verdict) so L0/L1 still works if the lazy helper is skipped; orchestrator lists delegated-execution under Lazy Protocols. - **Slim execute/review modes under token budgets** — move full L0/L1/L2 protocol into lazy `helpers/delegated-execution.md` so eager `kyro-forge:execute` / `kyro-forge:review` runtime paths stay under doctor token ceilings. ### Fixed - **Bare `kyro` CLI literals in sprint-forge assets** — use `{{KYRO_CLI}}` placeholders so `check:no-placeholder` and projected runtimes resolve the installed CLI path. ## [4.37.0] - 2026-07-25 ### Added - **L0 delegated execution protocol** — opt-in task delegation documented on `execute-task` and `review-task` modes: lean brief from `context-pack --task`, structured status JSON, write matrix (orchestrator + CLI own workflow state), single-agent fallback when subagents are unavailable. Overview in `docs/architecture.md`; manual eval checklist in `docs/evals.md`. - **L1 delegation opt-in** — personal `local.json` `execution.delegationEnabled` flag (default off), `delegationEnabled` on `context-pack`, `delegates/implementer` and `delegates/checker` role helpers, and conditional mode routing when enabled. Documented in `docs/teams.md` and `docs/cli.md`. ## [4.36.0] - 2026-07-24 ### Added - **Optional scope `author` on init** — `kyro plan` (init mode) captures `sprint.json.author` from git `user.name` and/or a schema-valid `user.email` when at least one is set (`source: "git"`, `capturedAt`; present fields only). Malformed git email is dropped (name-only still captured when present). Omits the field when nothing usable remains. **Never blocks init** — author is best-effort enrichment only. Not accepted from the lean plan file. Sprint mode preserves an existing author. Surfaced on `kyro scope inspect` and `kyro status full`. ## [4.35.0] - 2026-07-22 ### Added - **Layered multi-dev project state** — shared `.agents/kyro/project.json` (principles, team policy, scopes registry cache) + personal `.agents/kyro/local.json` (`activeScope`, installed adapters). Install/sync migrate legacy monolito `kyro.json`, write `.agents/kyro/.gitignore` for local-only files, and rehydrate on-disk scopes. - **`docs/teams.md`** — multi-dev commit matrix, clone bootstrap, dual-read/migration, optional `team.minPackageVersion`. - **Doctor layered health** — validates shared/local shapes, WARNs on leftover live monolito, optional non-blocking WARN when runtime is older than `team.minPackageVersion`. - **Read-only bootstrap remedies** — `status` / `context-pack` / `doctor` never create project state files; they surface `install --init-workspace` when layers are missing. ### Changed - **README, getting-started, cli, architecture, adapters** document layered state as the multi-dev default (supersedes gitignore-entire-`kyro.json` as the only team strategy). - **Codex / AGENTS.md projected block** points at `project.json` + `local.json` instead of monolito-only `kyro.json`. - **`close-sprint` project-scope CAS** writes shared `project.json` on layered workspaces (monolito `kyro.json` only while dual-reading a live monolito). ### Fixed - **Sprint close no longer diverges on layered-only workspaces** that lack live `kyro.json` after install/migrate (`STATE_DIVERGED … kyro.json: missing`). - **`listScopeNames` dual-reads layered project state** so scope listing works when only `project.json` + `local.json` exist. - **`uninstall` clears `installedAdapters` on layered state** (`local.json` / `project.json`) instead of rewriting live monolito `kyro.json`. ## [4.34.0] - 2026-07-22 ### Added - **`kyro scenario add` / `kyro scenario link`** — tool-owned scenario graph mutations after a sprint is active (append `spec.scenarios`, attach `task.scenario_refs`) so agents do not hand-edit `sprint.json` for post-plan coverage refine. - **`kyro adr add`** — tool-owned full v4 ADR append (`title`/`context`/`decision`/`consequence`/`alternative`, optional id/status/date). - **`context-pack.cliRecipes[]`** — copy-paste CLI commands for the current `nextAction` using the canonical agent entrypoint (plus status/doctor preflight). - **Projected skill stubs pin `metadata.runtimeVersion`** and print the durable **CLI** invocation line so agents discover the entrypoint without tribal knowledge. - **`kyro doctor` skill/runtime version check** — WARN when projected `kyro-*` skill stubs lag or lack a pin vs `manifest.packageVersion`. ### Changed - **`kyro analyze` scenario coverage is ledger-aware.** Scenarios linked on tasks in closed sprints (via ledger `checkpoint` / `snapshot` archives) no longer report MEDIUM "has no task coverage" on the next active sprint. Truly uncovered scenarios still MEDIUM. - **`kyro doctor` CLI invocation PASS line** now labels the **canonical agent entrypoint** explicitly. - **ADR shape validation** names missing fields and includes a full example object plus `kyro adr add` remedy. - **`kyro status` human output** clarifies that `activeSprint.status: planned` with `nextAction: execute_task` is coherent (progress vs routing). ### Fixed - **`check:lossless-checkpoints` heartbeat stall cases use a CI-safe 1s test lease** (was 300ms) and a longer readiness budget, so Worker renewals under loaded GitHub runners are not fail-stopped before the first post-ready tick. ## [4.33.2] - 2026-07-22 ### Fixed - **`kyroInvocation` is global-only (no more per-project drift).** Install/sync still probe PATH and persist the runnable form on `~/.agents/kyro/current/manifest.json`, and still substitute `{{KYRO_CLI}}` into projected modes under `current/`. Project `.agents/kyro/kyro.json` no longer stores `kyroInvocation`; any legacy copy is stripped on the next install/sync of that workspace (same pattern as the retired project-local `runtimeVersion`). Consumers use `getPersistedKyroInvocation()` (manifest first, then live resolve) and never read project state for the CLI string. One machine-wide install/sync is enough for all workspaces; you no longer need to re-sync every repo solely to fix a stale bare `"kyro"` left in each `kyro.json`. Multi-version runtime (retiring the `current` singleton) remains deferred and is out of scope for this change. - **State-writer lock reclaim claims stay selectable under short test leases.** `publishReclaimClaim` now floors claim TTL at 2s (`MIN_RECLAIM_CLAIM_MS`) so CI/`check:lossless-checkpoints` reclaim races do not expire the claim before the winner can select it under sub-second lease windows. ## [4.33.1] - 2026-07-22 ### Fixed - **Install/sync no longer persists bare `kyro` from ephemeral npx PATH.** `npx kyro-ai install` temporarily puts `…/.npm/_npx/…/bin/kyro` on PATH; the probe treated that as durable and wrote `kyroInvocation: "kyro"` into `manifest.json` / `kyro.json` / projected modes. After npx exited, agents got `command not found` and fell back to hand-writing `sprint.json`. Ephemeral package-manager paths (`_npx`, yarn/pnpm dlx) are now rejected; install falls back to the stable `node ~/.agents/kyro/current/dist/cli.js` form. `kyro doctor` fails closed when a persisted bare `kyro` is missing or still resolves only to an ephemeral path. Re-run `npx kyro-ai sync` (or install) once to refresh workspaces that already have a stale `"kyro"` invocation. ## [4.33.0] - 2026-07-21 ### Added - **Install/sync rehydrates scopes from disk into `kyro.json`.** When workspace state is written, Kyro unions directories under `.agents/kyro/scopes/` into `scopes[]` (title/status from `sprint.json` when readable). Existing registry entries are never clobbered. If `activeScope` is null and exactly one scope is known, it is set automatically; with multiple scopes it stays null so each developer chooses with `kyro scope set-active`. This unblocks the multi-dev pattern where `kyro.json` is gitignored (personal `activeScope`) but `scopes/` is shared. - Interactive `npx kyro-ai install` prompt now lists on-disk scopes when present, so answering **y** clearly registers them. - `kyro doctor` WARNs when scope folders exist on disk but are missing from `kyro.json.scopes[]`, with a remedy to re-run install/sync. ## [4.32.0] - 2026-07-21 ### Removed - **`wrap_up` is gone.** Closing the last sprint now sets `handoff.nextAction: "done"` (with `status: "completed"`). `done` is a terminal handoff: empty routing modes, budget class `brief`, no close-mode load, no post-close action. Pre-existing artifacts that still say `wrap_up` are normalized to `done` on read/validation so customer scopes keep loading without a mass migration. ## [4.31.0] - 2026-07-20 ### Fixed - `kyro repair` now consumes the confirmation guard like every other mutating verb instead of prompting interactively. Previously, with no TTY and no `--yes`/`--confirm`, it printed `Normalize sprint.json? [y/N]`, read an empty answer, and **exited 0 having done nothing** — which a non-interactive agent reads as success. It now routes through `evaluateGuard('repair_scope', …)` and exits non-zero with `CONFIRMATION_REQUIRED` when unconfirmed, matching `kyro review` and `kyro scope set-active`; `kyro repair --yes` still normalizes. The interactive `[y/N]` helper was removed. Surfaced by a field-test review of a client's Codex sprint session. - Read-only / permission durable-write failures now report an actionable `WRITE_NOT_PERMITTED` error with a remedy instead of an opaque message. A new `describeWriteFailure` helper (`src/cli/core/errors.ts`) classifies `EROFS`/`EACCES`/`ENOSPC` and is applied at every durable-write site: the operation pipeline (`review`, `repair`, and any tool-owned write) via `formatPipelineError`, and all three of `close-sprint`'s writers (`atomicReplace`, `publishExclusive`, and the `ensureDurableDirectory` mkdir, which are now inside the guarded try). Under Codex's default read-only sandbox the previous errors (`Apply failed and rollback completed: EROFS…`, `Durable file operation failed and temporary cleanup also failed`, raw `EACCES: … mkdir …`) gave the agent no remedy and cost repeated failed retries; the new message names the cause and tells sandboxed agents (Codex/OpenCode) to re-run with write access to `.agents/kyro`. ### Changed - Clarified in the runtime instructions and architecture docs that `sprint-forge` is a **skill loaded as instruction files**, not a spawnable subagent — the only Kyro agent is `orchestrator`. A field-test agent driving planning outside `/kyro:forge` tried to invoke `kyro-ai:sprint-forge` through the Task/Agent tool (which fails, then self-recovers to `orchestrator`); the plan-sprint mode and `docs/architecture.md` now state that a sprint is materialized via `/kyro:forge` or the tool-owned `kyro plan --from` verb, never by spawning `sprint-forge` as an agent. ## [4.30.2] - 2026-07-19 ### Fixed - Documentation QA follow-up: corrected stale narrative that still described the agent hand-writing state, which a keyword-grep pass had missed because the phrasing ("record compact task evidence **directly on the task object** in `sprint.json`", "one safe write back to `sprint.json`") did not contain the searched terms. Updated `docs/getting-started.md`, `docs/architecture.md` (the `/kyro:forge` flow steps + the artifact-layout mutation note), `docs/cost-model.md` (Write Policy table), `docs/context-management.md`, `docs/programmatic-usage.md` (Artifact Contract), and `README.md` to describe the tool-owned verbs (`kyro plan`, `record-evidence`, `review`, `debt`, `add-emergent`, `close-sprint`) as the way state is written. No behavior change — documentation accuracy only. ## [4.30.1] - 2026-07-19 ### Changed - Documentation polish. Removed two dead, unreferenced docs that shipped to npm: `docs/agents-reference.md` (described a superseded verbose orchestrator model that contradicted the current lean `agents/orchestrator.md`) and `docs/cost-optimization-audit.md` (a point-in-time audit fully superseded by `docs/cost-model.md`). Extended the multi-agent guides — `docs/agent-adapters.md`, `docs/HOW-TO-USE-CODEX.md`, `docs/HOW-TO-USE-OPENCODE.md` — to document the tool-owned CLI verbs (`kyro plan`, `record-evidence`, `review`, `debt`, `add-emergent`) and to state the portability boundary explicitly: the deterministic gates live in the CLI and are identical on Codex and OpenCode; only the two `PreToolUse` hooks are Claude-only reinforcements. `docs/status-coherence.md` was reviewed and kept (still accurate). ## [4.30.0] - 2026-07-19 ### Added - `kyro add-emergent` — tool-owned append of an emergent task to `activeSprint.emergentTasks[]`, so the agent no longer hand-edits the full sprint file to record required work discovered mid-sprint. Takes `--title`, `--description`, one or more `--acceptance` (a task needs acceptance criteria), optional `--file`/`--context`/`--depends-on`. The new task gets a fresh sequential id (`E1`, `E2`, …), `status: pending`, `evidence: null`, `verdict: null`, so `kyro record-evidence` and `kyro review` then operate on it like any planned task. Requires an active sprint (`NO_ACTIVE_SPRINT` otherwise) and validates every `--depends-on` against existing task ids (`TASK_NOT_FOUND` otherwise); recomputes `activeSprint.status` and leaves the handoff untouched (an emergent task does not reroute the flow). With this, the residual hand-edit paths flagged by the field test are closed for debt and emergent tasks; clarification-answer application stays agent-driven by design. ## [4.29.0] - 2026-07-19 ### Added - `kyro debt ` — tool-owned mutation of `sprint.json.debt[]`, so the agent no longer hand-edits the full sprint file to track technical debt. Five operations: `add` (appends `{ id: debt-, origin, priority, status: open, ... }` with a never-reused sequential id and origin derived from the current sprint), `start` (open/deferred → in_progress; refuses to restart resolved debt), `resolve` (→ resolved, optional `--note`), `defer` (→ deferred; requires both `--target` and a non-empty `--note` — deferring without a concrete reason is the anti-pattern the debt discipline exists to prevent), and `escalate` (raises priority only; refuses to lower). Debt is never deleted — only its status/priority/target/note change. Each op validates the sprint, mutates only the target item, and re-verifies the written file. `kyro status debt` remains the read-only inspector, and its remedy now points at these commands instead of a hand-edit. ## [4.28.0] - 2026-07-19 ### Added - `kyro plan --from ` now has a **sprint mode** (increment 2 of the tool-owned planning path). The command auto-detects mode from scope state: no `sprint.json` → init/bootstrap (unchanged); an initialized scope with `activeSprint: null` and `handoff.nextAction: "plan_sprint"` → sprint mode, which materializes the next `activeSprint` from a compact lean sprint-plan file (`sprint`, `phases`/`tasks`, `definitionOfDone`, optional `scenarios`). It expands each task to `status: "pending"` / `evidence: null` / `verdict: null`, derives `activeSprint.status` (`"planned"` for an all-pending sprint — never hardcodes `"executing"`, which the hand-write path did and which tripped an analyze coherence finding), merges scenarios into `spec.scenarios` by id, flips the matching `roadmap.sprints[]` entry to `state: "active"`, wires `handoff` to `execute_task` (or `clarify` when `[NEEDS CLARIFICATION]` markers are present), and reconciles the `kyro.json` scope-status cache so the written artifact is fully coherent (zero stale-status findings). It refuses with `SPRINT_ALREADY_ACTIVE` when a sprint is already active and `NOT_READY_TO_PLAN` when the handoff is not `plan_sprint`. Validates `sprint.n` against the expected next number (ledger max + 1), unique task/phase ids, and `depends_on`/`scenario_refs` referential integrity. ## [4.27.0] - 2026-07-19 ### Added - `kyro plan --from ` — tool-owned scope bootstrap (init mode). The planning phase previously had no CLI write path: the agent hand-authored the whole fat `sprint.json` per the INIT contract (read→parse→mutate→write the monolith, ~63% of which is static spec/roadmap). `kyro plan` takes a compact lean plan JSON (`scope`, `title`, `objective`, `successCriteria`, `spec`, `roadmap`) and materializes the full validated v4 `sprint.json` (`activeSprint: null`) plus registers the scope in `kyro.json` — so the agent writes only the essential fields and never touches the full document by hand. It refuses with `SCOPE_ALREADY_INITIALIZED` rather than overwrite an initialized scope, allows `[NEEDS CLARIFICATION]` markers at planning (routing `handoff.nextAction` to `clarify`) without the execute-phase block, and is portable — any host driving the CLI gets a deterministic, schema-owned bootstrap. Per-sprint `activeSprint` materialization is a later increment; INIT mode's guidance now points at this command with the hand-write contract kept as fallback. ## [4.26.2] - 2026-07-19 ### Fixed - `kyro review` no longer rejects acceptance criteria over cosmetic differences. Coverage matching (`missingCheckedCriteria`, plus the waiver-exclusion in `review.ts`) previously compared `--checked-criterion`/`--waive-criterion` against stored `acceptance_criteria` byte-for-byte, so a one-character paraphrase — a stray space, a backtick, different case — marked the criterion uncovered and failed the review, looping the agent through opaque rejections. Matching is now normalization-insensitive via a shared `normalizeCriterion` (NFC, strip backticks, collapse whitespace, trim, lowercase); the written verdict still stores the agent's original strings. When a supplied criterion matches no acceptance criterion even after normalization, `kyro review` now fails fast with `INVALID_INPUT` listing the exact expected criteria to paste, instead of surfacing an indirect coverage finding. ## [4.26.1] - 2026-07-19 ### Fixed - Clarification gate no longer false-positives on prose that *documents* the marker syntax. The detector (`countClarificationMarkers`, shared by `kyro analyze`, `kyro doctor --artifacts`, `kyro record-evidence`, and `kyro review`) previously did a raw substring scan of the whole serialized `sprint.json`, so any spec/task text that merely *mentioned* `[NEEDS CLARIFICATION]` — e.g. when the project being built is itself a tool with such a gate — blocked execution. It now counts only unresolved markers: the closed colon form `[NEEDS CLARIFICATION: ]`, excluding backtick-wrapped references (the repo-wide documentation convention) and placeholder payloads (``, `...`). Real markers still block on every host; the three duplicated inline scans (analyze, doctor, eval predicate) were unified onto the single detector. ## [4.26.0] - 2026-07-18 ### Added - Portable clarification gate: `kyro record-evidence` and `kyro review` now fail with `CLARIFICATION_REQUIRED` while `sprint.json` still contains unresolved `[NEEDS CLARIFICATION]` markers. The deterministic marker check already existed but only ran at the close gate; moving it into the two execute-phase CLI commands (which run on every agent host) blocks execution the moment it starts with unresolved unknowns, instead of surfacing them late at close. This is portable — no host-specific hook. ## [4.25.0] - 2026-07-18 ### Added - `kyro record-evidence ` writes `task.evidence` and sets `task.status` through the CLI, so the maker no longer hand-edits the 10–20k-token `sprint.json` to record a task (each hand-edit was a whole-file read + rewrite). It sets `status` (`done` by default, `--status blocked` after repeated failures), routes `handoff` to `review_task`, and never touches `task.verdict` (the checker still owns that via `kyro review`). Accepts repeatable `--validation`/`--file`, optional `--notes`, and `--by` (defaults to `maker`). The evidence it writes is validated end-to-end: `kyro review --verdict pass` accepts it without `--yes`. ### Changed - The execute-task mode now records evidence via `kyro record-evidence` instead of a hand-edited safe-write. Hand safe-writes remain only for emergent tasks and debt. ## [4.24.0] - 2026-07-18 ### Removed - Deleted a pre-v4 legacy documentation subsystem that nothing in the current workflow loads or references: `contexts/` (old context-mode files), `rules/` (pre-v4 rule files, superseded by JSON `conventions[]`/`principles[]` and the runtime `.agents/kyro/scopes/rules.md`), `templates/split-claude-md/` (unused CLAUDE.md-splitting templates), `docs/rules-guide.md`, and the orphaned `skills/sprint-forge/assets/modes/analyze.md` mode doc (the `analyze` step is a CLI command, not a loaded mode). Removed the now-empty `rules`/`contexts`/`templates` entries from the npm `files[]` and the README link to the rules guide. No runtime behavior changes; the `wrap_up` routing and all live modes/helpers/protocols are unaffected. ## [4.23.0] - 2026-07-18 ### Removed - The `/kyro:wrap-up` command (projected skill `kyro-wrap-up`) is removed. Its only unique job was writing a resume note into `sprint.json.handoff`, which is already covered: `close-sprint` refreshes the handoff at every sprint boundary, `/kyro:task-context` regenerates a resume prompt from live state on demand, and `review`/`execute` keep `nextAction`/`nextTaskId` current. Dropping it removes a redundant command surface and the naming collision with the `wrap_up` routing state. Command count is now 5. **The `wrap_up` `nextAction` routing state is unchanged** — closing the last sprint of a scope still routes there. ## [4.22.0] - 2026-07-18 ### Added - `kyro close-sprint` now recommends starting the next sprint in a fresh session when sprints remain (`plan_sprint`), and prints paste-ready handoff facts (scope, `sprint.json` path, `nextAction`, note). Carrying one session across a multi-sprint run is the biggest token-cost amplifier; a fresh session reloads only the lean handoff. When no sprints remain (`wrap_up`) it points at `/kyro:wrap-up` instead. The close-sprint mode directs the agent to generate the continuation prompt for the user. Portable to every agent (deterministic CLI output — no host hooks). ## [4.21.0] - 2026-07-18 ### Added - PreToolUse Bash guard (`guard-bash-output.mjs`) blocks a recursive `rg`/`grep -r` search only when it has no output bound at all — no cap, no scope, no redirect — which is the single biggest measured token cost in real runs (an uncapped repo-wide search can pull tens of thousands of tokens into context in one call). Bounded/scoped searches, tests, and non-search commands pass untouched, and the guard fails open on anything ambiguous. Its block message hands back the bounded form to re-run. ### Changed - Execute and review modes and the reviewer helper now direct validation to the touched area: tests scoped to the changed files instead of a full-suite re-run, and searches capped/scoped rather than repo-wide. ## [4.20.1] - 2026-07-16 ### Fixed - Release CI now rejects versions that already exist as a GitHub Release, Git tag, or npm package, so reused versions fail visibly during PR validation instead of producing a green run with skipped publish jobs. - `kyro doctor` no longer fails npm-package packaging checks (`agents/orchestrator.md`, `.claude-plugin/`) when the CLI is invoked via the projected runtime (`node ~/.agents/kyro/current/dist/cli.js`). Those checks run only against the full package layout; projected-runtime roots report an explicit PASS and a light runtime shape check instead. - Root classification is fail-closed across verified full-package, projected-runtime, and unknown/corrupt layouts. Multiple independent runtime markers (`manifest.json`, `KYRO.md`, `core/agents/`, `core/WORKFLOW.yaml`) keep partial runtimes mode-aware, while marker-less or conflicting roots skip package checks and report an explicit root failure. - `install` and `sync` run only from a positively verified full npm package. Projected, partial, conflicting, and unknown roots return `INVALID_INPUT` with an actionable `npx kyro-ai` remedy instead of reaching a cryptic `ENOENT` on `agents/`. - `doctor --tokens` from the projected runtime fails with a clear package-only message rather than packaging `ENOENT` noise. - Doctor remedies for missing runtime files, adapters, or a broken CLI invocation point at `npx kyro-ai` (full package) rather than bare `kyro install`/`kyro sync`, which are blocked from the projected fallback. ### Changed - Project state no longer stores a stale `runtimeVersion` snapshot. The active version is read from `~/.agents/kyro/current/manifest.json.packageVersion`; install and sync remove the legacy field while preserving project-owned state and metadata. - INIT, projected command skill stubs, and CLI docs clarify the two CLI roots: full npm package for install/sync/token audit; projected runtime for agent workflow commands (`status`, `doctor --artifacts`, `analyze`, `repair`, `close-sprint`, …). ## [4.20.0] - 2026-07-15 ### Added - Scope-local JSON ADRs now live in `sprint.json.adrs[]`, giving each Kyro scope durable architectural decision records with status, context, decision, consequences, alternatives, and typed links. - `kyro context-pack` includes ADR records, `kyro status full` reports ADR status counts and recent ADRs, and `kyro doctor --artifacts` validates malformed ADR records through the sprint schema. ### Changed - New scope templates include `adrs: []`, while existing scopes remain compatible because the field is optional. Sprint-forge guidance now distinguishes operational `conventions[]` from durable architectural `adrs[]`. ## [4.19.0] - 2026-07-13 ### Added - Sprint close now dual-writes the compatible verbatim ActiveSprint snapshot and an immutable `SprintCloseCheckpointV1` containing complete scope state before and intended after close, affected project scope state, frozen close inputs, and canonical SHA-256 digests. - Artifact doctor classifies checkpoint transactions as `PREPARED`, `PARTIAL`, `APPLIED`, `DIVERGED`, `CORRUPT`, or `UNSUPPORTED_VERSION`, including when live `sprint.json` is missing or invalid. ### Changed - Sprint close uses a dedicated durable transaction with exclusive checkpoint publication, atomic mutable replacements, compare-and-swap reconciliation, idempotent resume, and scope-entry-only `kyro.json` patching. - All official Kyro state writers share one serialization lock; checkpoint publication and mutable replacements fsync their parent directories, and managed checkpoint paths reject workspace escapes and symlinked ancestors. - Checkpoint validation derives the authorized intended-after transition from the before image and frozen inputs. Doctor compares live state only with the latest transaction while validating older checkpoints as historical records. - Recovery guidance now distinguishes versioned lossless scope checkpoints from legacy sprint-level snapshots; historical archives are never backfilled with invented state. ## [4.18.0] - 2026-07-12 ### Changed - Refactored `/kyro:idea` and the Seedbed skill into a plan-grade pre-scope flow with rough/mature lanes, evidence grounding, a material-question gate, and a Forge-compatible handoff. Documentation and adapter metadata were synced to describe the new behavior, and `check:seedbed` now covers the Seedbed contract fixtures. ## [4.17.1] - 2026-07-11 ### Fixed - `/kyro:qa` command is now properly registered in adapter fixtures (standard, OpenCode, Codex). The kyro-qa command skill was missing from the list of expected command skills projected for adapters, preventing it from being discovered in non-Claude environments. ## [4.17.0] - 2026-07-11 ### Added - `/kyro:qa` is now available as a dedicated slash command. It exposes the `qa-review` skill to run certification audits on any scope, independent of the forge cycle. The QA command validates code quality, architecture alignment, security, testing, reliability, performance, and planning artifact synchronization against the scope specification. Audit verdicts (APPROVED, APPROVED WITH NOTES, CHANGES REQUIRED, REJECTED) are review-level conclusions and do not get written into `sprint.json` task verdicts, which continue to use the binary `pass`/`fail` schema for the forge gate system. QA can be run anytime — during active sprints, after completion, or as a one-off validation check. ### Changed - Command documentation now lists 6 slash commands (was 5, now includes `/kyro:qa`). - `AGENTS.md` updated to report accurate counts: 6 commands, 3 skills (was understated as 4 commands, 2 skills). - Marketplace description updated to mention independent QA certification. ### Fixed - `/kyro:qa` command now includes all required declarative rules matching sibling command patterns (read-only rule, orchestrator-bypass rule, {{KYRO_CLI}} doctor --artifacts reference). - QA verdict vocabulary clearly separated from `sprint.json` task verdict schema to prevent confusion. ## [4.16.2] - 2026-07-09 ### Fixed - `kyro review --verdict pass` no longer accepts a pass verdict on a task that is not `status: done`. Every checker finding was gated behind `status === 'done'`, so a pass written onto a still-pending task produced zero findings and the review gate never fired — leaving the sprint in an inconsistent state (pass verdict + pending status + a handoff stuck on the same task). A new CRITICAL checker finding now blocks that pass and also surfaces the inconsistency in `kyro analyze`. Combined with the existing done-without-evidence check, a pass verdict now requires the task to be executed (done with valid evidence) first. - `kyro analyze` malformed-evidence findings now name the exact failing field (e.g. `evidence.notes must be a string when present`) instead of only the generic "missing or malformed evidence", reusing the schema validator so hand-fixing evidence no longer requires guessing the contract. ## [4.16.1] - 2026-07-08 ### Added - `/kyro:idea` is now projected to CLI hosts (opencode, codex) as the `kyro-idea` command skill. Idea maturation previously shipped only on the Claude plugin; the CLI installer's command set omitted it, so `kyro install --agent opencode/codex` never surfaced it. `idea` is now part of `COMMAND_NAMES` and installs alongside `kyro-forge`, `kyro-status`, `kyro-wrap-up`, and `kyro-task-context`. ### Notes - Existing installs must re-run `kyro install` (or `kyro sync`) to project the new `kyro-idea` skill; `kyro doctor` flags it as missing until then. - Naming stays consistent with the `forge`/`sprint-forge` pattern: the public command is `idea` (`kyro-idea`), backed by the internal `seedbed` skill — the skill name is never projected, exactly like `sprint-forge` sits behind `kyro-forge`. ## [4.16.0] - 2026-07-08 ### Changed - Idea maturation is now its own skill, `seedbed`, instead of a mode inside `sprint-forge`. `skills/sprint-forge/assets/modes/idea.md` and the `matured-idea` template moved to `skills/seedbed/assets/`. This keeps the pre-scope idea workflow fully decoupled from the sprint cycle: `seedbed` loads only when `/kyro:idea` is invoked and shares no state with `sprint-forge`. - `check:command-modes` now validates command→asset references across all skills, not just `sprint-forge`. ### Notes - No user-facing change: `/kyro:idea` behaves identically (same bounded conversation, same pre-scope guarantees, same output path). Only the internal skill location changed. ## [4.15.0] - 2026-07-08 ### Added - `/kyro:idea` — an optional, pre-scope command that matures a rough idea into a structured brief through a bounded, one-question-at-a-time conversation, then writes one markdown document to `.agents/kyro/{docType}/{date}-{slug}.md` (`docType` is `plan`, `analysis`, or `constitution`). The brief can seed a later `/kyro:forge` scope with a richer objective than a one-liner. - New `idea` mode (`skills/sprint-forge/assets/modes/idea.md`) and `matured-idea` template documenting the maturation loop and document shape. - `INIT` mode now optionally reads a referenced matured-idea document to enrich a new scope's `objective`, `successCriteria[]`, and `spec.requirements[]`. - `check:command-modes` — a static guard that every mode file a command references actually exists, preventing command-to-mode drift. ### Notes - Fully additive and backward-compatible: `/kyro:idea` never reads, resolves, or creates a scope, `kyro.json`, or `sprint.json`; it does not go through the orchestrator; and it is kept explicitly separate from `kyro.json.principles[]`. Existing flows are unchanged when no matured-idea document is used. ## [4.14.0] - 2026-07-08 ### Added - `kyro install --verbose` and `kyro sync --verbose` now print the full operation plan only when explicitly requested, keeping normal installs compact. - `kyro install --init-workspace` and `kyro install --no-init-workspace` now make workspace initialization explicit when installing the global runtime. ### Changed - `kyro install` no longer prints every projected path by default; it now shows the plan summary plus the completion footer (`Kyro has been installed.`, `Version`, `State`, `Runtime`). - `kyro install` now always refreshes the global runtime but skips creating `.agents/kyro/**` in new workspaces unless initialization is explicitly requested. ### Fixed - `kyro install` and `kyro sync` now preserve existing project state fields such as `principles` and future top-level metadata while refreshing runtime fields. ## [4.13.0] - 2026-07-08 ### Changed - Installer/runtime projection now keeps a single active runtime at `~/.agents/kyro/current/`. Reinstalling or syncing replaces that runtime and removes the retired `~/.agents/kyro/versions/` layout instead of retaining multiple bundled CLI copies. - `kyro sync --prune` now focuses on obsolete adapter-owned entrypoint files; legacy versioned runtime directories are cleaned automatically by install/sync. ## [4.12.0] - 2026-07-07 **Bundled runtime CLI.** The Kyro CLI now ships inside the projected runtime, so workflow steps (`close-sprint`, `analyze`, …) run without a `kyro` binary on PATH. Agents installed via `npx kyro-ai install` previously received the markdown runtime but no executable and blocked at CLI-owned steps; the runtime is now self-contained. **Action required once:** run `npx kyro-ai@4.12.0 install` (or `kyro sync` if you have a global install) to re-project the runtime with the bundled CLI. Existing scopes and artifacts are preserved. ### Added - Projected `dist/` (plus root `package.json`/`config.json`) into `~/.agents/kyro/versions/{v}/`, mirroring the npm layout so PACKAGE_ROOT-relative assets resolve when the CLI runs from the runtime. - `kyroInvocation` resolver: resolves to `kyro` when on PATH, else `node ~/.agents/kyro/current/dist/cli.js`; persisted to `manifest.json` and `kyro.json`. - `{{KYRO_CLI}}` placeholder substituted into projected skill/agent markdown at install/sync time, so projected CLI references always resolve to a runnable invocation. - `doctor` CLI-invocation self-check: runs ` --version` and reports an actionable remedy when the runtime CLI can't execute. - End-to-end `check:cli-bundle` proving `close-sprint` completes via the projected CLI with no PATH binary. ### Fixed - Codex MCP registration now emits the resolved runnable command instead of a bare `command = "kyro"`, so the MCP server starts when no `kyro` binary is on PATH. ## [4.11.1] - 2026-07-06 Completes the 4.11.0 status-coherence patch so derived status, review waivers, and status-report surfaces behave consistently across CLI and MCP. ### Fixed - `analyze` now reports stale `activeSprint.status` as an advisory MEDIUM coherence finding. - `repair` now normalizes `activeSprint.status` alongside `phase.status` and the `kyro.json` scope-status cache. - `review` now recomputes `activeSprint.status` after verdict writes, preventing a fresh review from creating sprint-level status drift. - MCP `review_task` now accepts `waived_criteria` entries in the same `"criterion::reason"` format as the CLI and stores structured waiver records. - `/kyro:status` router documentation now includes review-debt reporting instead of leaving that behavior only in the full STATUS mode prompt. ## [4.11.0] - 2026-07-06 Status coherence: lifecycle status is derived from task state, review debt is surfaced before close, and accumulated review debt is recoverable one task at a time. Grounded in a real production run of 4.9.0. ### Added - Derived-status core (`src/cli/core/status.ts`): `derivePhaseStatus`, `deriveActiveSprintStatus`, `deriveScopeStatus` compute lifecycle status from the authoritative leaf (`task.status`), plus `normalizeStoredPhaseStatus` for vocabulary synonyms. - `analyze` reports status-coherence findings: a phase whose stored status contradicts its tasks (MEDIUM), and a stale `kyro.json` scope-status cache (MEDIUM). Advisory — they never block a user-invoked close. - `context-pack` surfaces maker/checker debt on every pull: `reviewPending` (done tasks lacking a pass verdict) and `nextTaskReview` (the task's checker findings), so the agent sees the gap before the wall at close. - `kyro review --waive-criterion "::"`: a pass verdict may waive an acceptance criterion obsoleted by an approved scope change; the reason is required and archived. `TaskVerdict.waived_criteria` added. - `PHASE_STATUS_VALUES` constant and `WaivedCriterion` type. ### Changed - **Review recovery (fixes a latent maker/checker bug):** the review gate now blocks only on checker findings scoped to the task under review, not the global set. Accumulated review debt (several `done` tasks without verdicts) is now payable one task at a time; previously reviewing any task was blocked by every other unreviewed task. `analyze` keeps the global view. - `review` recomputes the reviewed task's `phase.status` on write, so phase status stops being an orphan field. - `kyro repair` parses leniently, normalizes each `phase.status` to its derived value, reconciles the `kyro.json` scope-status cache, then validates the result. It can now migrate status drift instead of only reformatting already-valid files. - `TaskEvidence.validation` accepts a string **or** a string array (real runs record multiple validation lines); the close narrative renders both. ## [4.10.0] - 2026-07-05 Sharpens the Agent-Computer Interface (ACI): consistent errors, real verbosity, actionable tool summaries, and a wider MCP surface. ### Added - `verbosity` (`concise` | `detailed`) end to end: CLI `--verbosity` and MCP `context_pack` param now trim long-form advisory prose in concise mode (default stays `detailed`). - `review_task` and `trace_tail` MCP tools, giving agent hosts parity with the CLI `review` and `trace` commands. - Actionable one-line summaries in every MCP tool result (`content[].text`), with the full payload preserved in `structuredContent`. - CLI `--confirm` alias for `--yes`. - Five new typed error codes (`UNKNOWN_COMMAND`, `UNKNOWN_SUBCOMMAND`, `UNKNOWN_TOOL`, `NO_ACTIVE_SPRINT`, `TASK_NOT_FOUND`) and `docs/aci.md`. ### Changed - Every command/app-layer error now carries a typed `code` (and, where actionable, a `remedy`); plain `throw new Error` is gone from the command surface and gated by `check:mcp`. - `check:mcp` now asserts the 9-tool golden catalog, usage guidance in every description, no dead schema params, and the no-plain-error contract. ## [4.9.0] - 2026-07-03 Adds minimal spec traceability inside `sprint.json`. ### Added - Optional `spec` block with requirements, scenarios, non-goals, and open questions. - Optional `task.scenario_refs` links for Requirement → Scenario → Task traceability. - Deterministic `kyro analyze` findings for broken spec references, duplicate ids, coverage gaps, open questions, and done/pass tasks without scenario references. - Spec traceability reporting in `doctor --adapters`. - Context-pack output for scope-level spec details and task-level resolved scenarios. - `check:spec-traceability`, eval fixtures, and `docs/spec-traceability.md`. ## [4.8.0] - 2026-07-02 Adds a deterministic maker/checker boundary for task evidence and verdicts. ### Added - Typed task evidence and verdict contracts with tolerant checker validation. - `kyro review ` tool-owned verdict writer with confirmation guard, safe write, handoff updates, and trace events. - Checker findings in `kyro analyze` for missing evidence/verdict, criteria coverage drift, non-negotiable principle pass violations, verdict/evidence timestamp order, and optional self-review blocking. - `maker_checker.requireSeparateChecker` policy extension. - Maker/checker boundary reporting in `doctor --adapters`. - `check:maker-checker` gate and eval fixtures for happy-path review and blocked self-review. - `docs/maker-checker.md`. ### Changed - `close-sprint` now refuses to close while CRITICAL/HIGH analyze findings remain. - Sprint execution/review mode docs now route verdict writes through `kyro review`. ## [4.7.0] - 2026-07-02 Adds portable guardrail policy enforcement for dangerous operations across CLI and MCP surfaces. ### Added - Built-in guardrail policy with fail-safe `.agents/kyro/policy.json` overrides. - Shared `evaluateGuard` core for guarded operations. - `POLICY_BLOCKED` error code and CLI error-code rendering. - `check:guardrails` gate covering zero-write refusals, confirmation, fail-safe merge, trace, and MCP projection. - Adapter guardrail enforcement-tier reporting in `doctor --adapters`. - Codex MCP config projection for `kyro mcp serve`. - Eval cases for `scope set-active` confirmation and blocked policy behavior. - `docs/guardrails.md`. ### Changed - `kyro scope set-active` now requires explicit `--yes` confirmation. ## [4.6.0] - 2026-07-02 Adds append-only trace events for per-scope observability without making trace a source of truth. ### Added - `kyro trace` command with `--json`, `--tail`, `--type`, and explicit-scope `--clear`. - `doctor --trace` informational trace summaries. - Append-only best-effort trace core with `KYRO_TRACE=0` kill switch and `KYRO_TRACE_DEBUG` diagnostics. - Seven-versioned trace event catalog and golden drift check. - `check:trace` conformance gate for append-only writes, non-fatal failures, stdout purity, NDJSON validity, crash-tolerant reads, and no routing reads. - Eval cases pinning `close_snapshot` emission and trace kill-switch behavior. - `docs/trace.md` with trace-vs-ledger disambiguation. ### Changed - Eval replay steps now support scoped environment variables for behavioral checks. ## [4.5.0] - 2026-07-02 Adds a tools-only MCP typed tool surface over Kyro's deterministic CLI core. ### Added - `kyro mcp serve` stdio server with JSON-RPC lifecycle, tools/list, tools/call, ping, protocol negotiation, and stdout purity. - `kyro mcp tools` for printing the tool catalog. - Seven typed MCP tools: `context_pack`, `doctor_artifacts`, `analyze_scope`, `close_sprint`, `scope_list`, `scope_inspect`, `repair_scope`. - Shared core layer for scope resolution, analysis, scope listing, and structured `KyroCoreError` envelopes. - Two-phase mutation protocol for MCP mutations: dry-run plan by default, apply only with `confirm: true`. - `check:mcp` conformance gate and `fixtures/mcp/tool-catalog.golden.json`. - `docs/mcp.md` with host registration examples. ### Changed - `kyro analyze` now uses the shared analysis core; CLI behavior remains pinned by evals. - `close-sprint` double-close errors now expose the stable `SNAPSHOT_EXISTS` code. ## [4.4.0] - 2026-07-02 Adds deterministic behavioral evals for agent-facing Kyro contracts. ### Added - `kyro eval` command with strict `case.json` manifests, isolated temp sandboxes, route assertions, CLI step expectations, final-state normalization, human output, and `--json` reports. - `fixtures/evals/` seed suite with 15 replay cases covering all routes, known guardrail failures, close-sprint happy path, task-mode context packs, and adapter filtering. - `check:eval` and `check:eval-harness` regression gates, now included in `npm run check`. - Code-owned routing contract (`src/cli/routing.ts`) plus `check:routing` to prevent drift between `agents/orchestrator.md` and runtime route resolution. - `context-pack --json` now includes `routing.modes` for machine-checkable route assertions. ### Changed - `agents/orchestrator.md` now documents the `clarify` route explicitly. ## [4.3.0] - 2026-07-01 Documentation audit, bug fixes, and token optimization. Eliminates all artifact model drift and removes stale forward-looking docs. ### Fixed - **Critical (schema/runtime contract):** `kyro doctor --artifacts` now validates every field the runtime consumes from `activeSprint` (`objective`, `definitionOfDone`, `phases[].id/title`, `tasks[].title`) and from `roadmap.sprints[]` (`n`, `slug`, `title`, `state`). Previously an incomplete `sprint.json` could PASS the doctor and then crash `close-sprint`. Regression fixtures added. Contract: if the doctor says PASS, no downstream command may crash on a missing field. - **Critical:** `kyro analyze` error message no longer references the removed `kyro migrate` command. - **High:** `package-lock.json` was stale (pinned 3.4.3); regenerated at the release version and now enforced by `check:versions`. Removed the non-canonical `pnpm-lock.yaml` (CI uses `npm ci`). - **High:** 10 documentation files rewritten to reflect the `sprint.json`-only model; eliminated all references to pre-4.0 artifacts (`state.json`, `index.json`, `ROADMAP.md`, `events.ndjson`, `phases/`). - Docs no longer reference removed scripts (`check:artifact-fixtures`, `check:context-pack`) in `cli.md`, `release-checklist.md`, and `cost-model.md`. - `KYRO_WORKFLOW.stateModel` public export corrected from `markdown` to `sprint-json`. - Removed dead `checkTemplateBudget` helper; strict `tsc --noUnusedLocals --noUnusedParameters` is clean. ### Removed - `docs/harness-migration.md` — described v4.x features (CLI runtime, install, doctor, sync) as future work; no longer needed. - Historical v3.4.0 release notes — shipped as `docs/releases/` but not relevant to current users. ### Changed - Trimmed `INIT.md` (623w → 526w, −97w) and `close-sprint.md` (610w → 529w, −81w) for runtime efficiency; gates and safety contracts preserved. - Runtime token budgets now have tighter but sustainable margins across all paths. ## [4.2.0] - 2026-06-30 Kyro is now a single-model tool: everything is `sprint.json`. Internal cleanup plus a repaired release pipeline. ### Removed - **`kyro migrate` command.** Kyro reads and writes only the `sprint.json` model; there is no separate conversion step. ### Fixed - Repaired the CI `validate` pipeline (build now runs before the checks; removed references to scripts that no longer exist) so tags publish cleanly again. ### Changed - Recalibrated runtime token budgets to the real footprint of the lean runtime, with ~10% headroom; they remain a meaningful ceiling that flags a mode/helper growing too large. - Renamed the runtime verification gate to `check:runtime-artifacts` (runtime must reference only the `sprint.json` model). ## [4.1.0] - 2026-06-30 Adds the **input discipline** that the v4 execution engine lacked, borrowing the proven mechanisms from spec-kit but keeping Kyro's single-source-of-truth model. The rule throughout: what must happen is enforced deterministically by the CLI, not left to prose a weak model can ignore. ### Added - **Clarify discipline.** A new `clarify` mode and `handoff.nextAction` resolve ambiguity before planning (≤5 questions, one at a time, recommended option first), recording each answer in `sprint.json.clarifications[]`. Agents write `[NEEDS CLARIFICATION: ...]` instead of guessing, and `kyro doctor --artifacts` **fails** while any such marker remains — a deterministic gate that works in any harness. - **`kyro analyze`** — semantic cross-check of a scope (where `doctor` checks shape, `analyze` checks meaning). Severity-triaged findings (CRITICAL/HIGH/MEDIUM/LOW): unresolved clarifications, coverage gaps, missing acceptance criteria, broken `depends_on`, overdue debt, principle violations. Exits non-zero on CRITICAL/HIGH. Gate before `close_sprint`. `--json` supported. - **Project-level principles.** `kyro.json.principles[]` (authored, immutable — spec-kit's "constitution"), distinct from learned `conventions[]`. Each `{ id, rule, severity, rationale, check? }`; principles with a built-in `check` are enforced deterministically by `kyro analyze`, free-text ones are agent gates at `plan-sprint`/`review-task`. - `successCriteria[]` on `sprint.json` — technology-agnostic, measurable outcomes (the WHAT/WHY layer). ### Changed - `INIT` seeds `successCriteria[]` and (optionally) `principles[]`; `plan-sprint` and `review-task` enforce clarity and principle gates before advancing. - The `sprint.json` template carries `successCriteria`, `clarifications`, and the previously missing `activeSprint.title`. ## [4.0.0] - 2026-06-30 Major release. Kyro adopts a single source of truth per scope — `sprint.json` — and makes the irreversible operations (sprint close, narrative rendering) tool-owned and deterministic instead of agent-rendered prose. ### Highlights - **Single source of truth.** Each scope is one `sprint.json` plus the global `kyro.json` registry. Agents read two files and route on `handoff.nextAction`. - `kyro.json.scopes[]` entries are objects `{ id, title, status }`, never bare strings. ### Added - **`kyro close-sprint`** — deterministic sprint close. Writes the verbatim ActiveSprint JSON snapshot to `archive/` **before** clearing `activeSprint`, renders the human narrative `.md` (title sourced from `roadmap.sprints[]`, so it can never be `undefined`), appends the `ledger[]` entry, updates `previousSprint`/`roadmap`/`handoff`, and flips the `kyro.json` scope status on the last sprint. Refuses to run if a snapshot already exists (double-close protection). New `--learning` flag. - **PreToolUse guard** (Claude Code) that blocks any hand edit nulling `activeSprint`, redirecting to `kyro close-sprint`. - **`kyro doctor --artifacts`** now audits verbatim ActiveSprint snapshots, archive narratives (catches `Sprint N: undefined`), `activeSprint.title`, and non-object task `evidence`. - Runtime-artifact verification gate and doctor fixtures wired into `npm run check`. ### Changed - Runtime (orchestrator, commands, modes, helpers) and the CLI both speak only the `sprint.json` model. - Sprint narratives are rendered by the CLI, not hand-written by the agent. - `activeSprint` now carries `title`, making each snapshot self-contained. - `INIT` creates a complete v4 `kyro.json` when none exists (all required fields, not just `scopes`/`activeScope`). ### Fixed - `kyro doctor`, `kyro install`, and `kyro sync` no longer crash on an incomplete `kyro.json` (missing `installedAdapters`); they report a clean diagnostic and `install`/`sync` self-repair the file while preserving existing scopes. - Sprint archive narratives no longer render `Sprint N: undefined` — the title is carried through the model and rendered deterministically by the CLI. [4.1.0]: https://github.com/SynapSync/kyro-ai/releases/tag/v4.1.0 [4.0.0]: https://github.com/SynapSync/kyro-ai/releases/tag/v4.0.0