v0.13.0

v0.13.0

Significant release focused on a daemon entity cache, multi-turn session
lifecycle, a new automation subsystem (hooks/schedules/events), split
per-task storage with a required migration, a review records web UI, plan
branches, and a single-command upgrade flow.

New or changed configuration

• daemon.runtime — new kspec.config.yaml key selecting the daemon
  runtime (bun or node). Defaults to node.
• dispatch.sync — new kspec.config.yaml section controlling
  integration branch sync cadence and behavior.
• coverage.scan_paths and coverage.exclude_patterns — new
  kspec.config.yaml section for the AC coverage scanner, making it
  language-agnostic and allowing per-project include/exclude tuning.
• hooks: meta domain — new top-level kspec.meta.yaml section for
  event-driven hook actions, managed via
  kspec hook add/set/list/enable/disable/remove. Distinct from the
  existing kspec.config.yaml#hooks block that controls
  checkpoint/prompt-check hook installation.
• schedules: meta domain — new top-level kspec.meta.yaml section for
  cron-style scheduled agent actions, managed via kspec schedule.
• session_prompt action type — new action input for multi-turn session
  lifecycle, with prompt/prompt_template and skill support.
• kspec setup / kspec init --setup now scaffold kspec.config.yaml,
  default agents, conventions, a session reflection hook (restricted to
  the first idle event), the default module, and gitignore entries on
  first run. Existing setups are preserved.
• kspec release-notes — new top-level command that prints notes for the
  installed version or an inclusive --from <version> --to <version>
  range, reading directly from RELEASE_NOTES.md.
• kspec upgrade now appends release notes for every intervening version
  to its output so behavioral changes surface during upgrade.
• RELEASE_NOTES.md is shipped in the published package; the release
  skill documents the authoring conventions and the pre-release check
  that enforces a non-empty entry for the version being released.

Breaking changes

• Task storage split requires migration. Task data now lives in a
  per-task directory layout (core, notes, history) instead of the single
  project.tasks.yaml monolith. Existing projects must run
  kspec task migrate to convert their task file to the split layout
  and kspec task storage activate to enable the new backend. Tasks
  continue to read from the monolithic format until activation, so the
  migration can be staged, but task writes after upgrade require the
  split layout.

Features & Additions

• Daemon entity cache — tiered in-memory cache for items, tasks,
  meta, plans, reviews, inbox, and triage, with watcher-driven
  incremental invalidation, write-through updates, and cache-backed read
  concurrency. Adds GET /api/debug/cache-status for diagnostics and a
  cache:status WebSocket topic for domain-ready invalidation signals.
• Multi-turn session lifecycle — active session registry, idle-grace
  auto-close, session.idle event, session_prompt action type, and
  dispatch engine integration for continuing work across turns.
• Automation subsystem — hook, schedule, event, composition, and
  action model with CLI commands (kspec hook, kspec schedule,
  kspec event), a schedule tick engine, a hook execution engine, a
  composition join accumulator, and shared action run tracking.
  kspec validate now enforces hook/schedule/composition rules.
• Split per-task storage — per-task directory layout with core data,
  notes, and history files. Adds kspec task migrate,
  kspec task storage activate, kspec task rebuild-index, write
  buffering for multi-file transactions, and an in-file activity
  timeline in task get.
• Review UI in the web app — review list and detail pages with
  thread view, revision selector, inline diff viewer with commenting,
  structured content viewer for plan/spec reviews, verdict/check/
  thread/lifecycle API endpoints, and WebSocket broadcasts for review
  events. Task detail pages link to associated reviews.
• Plan branches — new branch field on plans, kspec plan branch
  command, kspec plan derive tasks by default, and dispatch workspace
  base-branch resolution from plan branch.
• Single-command upgrade — kspec upgrade migrates scaffold,
  skills, and kspec-agents.md in one step, with corruption recovery,
  orphan skill cleanup, and --force that preserves user-removed
  defaults.
• Unified daemon API envelope — all daemon routes return a typed
  ApiResponse<T> wrapper. Read routes now serve from the entity
  cache.
• Dispatch hardening — session lifecycle event emission on terminal
  states, stale integration target detection when base branch changes,
  dispatch branch push lifecycle, and shadow worktree cross-
  contamination guards.
• YAML round-trip stability — raw-data preservation for workflow
  runs and triage records.
• CLI ergonomics — kspec item ac update alias, smarter rejection
  messages when kspec task set rejects a status transition, automatic
  dangling-reference cleanup on item deletion, and restore of pre-block
  status on kspec task unblock.
• Web UI — automation view with trigger editing, cache-warming
  loading skeletons, session.idle event rendering, query retry
  ceiling, and WebSocket invalidation replacing polling across more
  surfaces.
• Test infrastructure — smart test runner caching with condensed
  output, per-file progress in non-verbose mode,
  no-source-scanning and no-leaky-test-daemon oxlint rules,
  readTestOutput helper.

Bug Fixes

• kspec setup base-branch fallback now uses the full dispatch fallback
  chain and handles stale remote HEAD.
• Daemon emits cache-invalidation events for new non-active sessions.
• Daemon loads config from worktree root instead of main repo root.
• Batch atomic failures now report rolled_back correctly and include
  a rollback note in output.
• Web UI plan filter resolves via bidirectional ULID-prefix matching.
• CLI auto-start of daemon is suppressed in dispatch sessions and on
  serve commands.

Documentation

• AGENTS.md trimmed to architecture/gotchas/decision frameworks; CLI
  and workflow detail moved into skills.
• New review-plan skill for plan document quality review.

Other Changes

• oxlint + oxfmt replace Prettier in the lint/format pipeline.
• Legacy ralph agent references removed; legacy agent config alias
  retained for back-compat.

v0.12.0

Major feature release with review records, dispatch workspace management, and web UI modernization.

Features & Additions

• Per-cycle review records — review CLI surface for creating, querying, and mutating reviews with verdicts, checks, threads, and gate evaluation
• Dispatch workspace lifecycle — canonical task branch lineage, worktree isolation, bootstrap preflight, orientation prompts, and workspace registry persistence
• Task activity timeline — git query for shadow branch history, activity normalization with commit message and diff parsing, and display in task get
• Fix-cycle diff context — reviewer orientation includes diff summary for fix cycles
• Configurable publication mode — manual_merge or pull_request via kspec.config.yaml
• Portable task submission linkage — dispatch base_branch fallback for upstream_ref
• Session improvements — branch worktree mode, text search, unified filtering, summary stats, and session event detail API
• Web UI: TanStack Query v6 migration — dashboard, core pages, inbox, triage, sidebar, and sessions all migrated; eliminated polling in favor of WebSocket invalidation
• Web UI: Markdown rendering — streaming markdown renderer, ANSI terminal color rendering, prose typography
• Web UI: Session streaming — WebSocket-first live viewing with infinite scroll pagination
• Droid ACP adapter — agent detection, skill import/renderer, and core skill registration
• YAML serialization stability — canonical field ordering, round-trip stability, and anchor/alias crash prevention
• Plan enhancements — derive from specs, import into existing plans, export command, content-only storage
• Daemon APIs — batch item fetch, ref index endpoint, server-side aggregation, title resolution, enriched WebSocket broadcasts
• Validation — AC annotation validation, spec completeness policy, blanket coverage ref rejection

Bug Fixes

• Fixed dispatch workspace provisioning, health reconciliation, and lifecycle state management (50+ fixes)
• Fixed web UI URL state management — use goto() instead of replaceState/pushState
• Fixed shadow branch sync races with per-worktree locks and in-flight dedup
• Fixed YAML anchor/alias crash when sortMapEntries reorders shared references
• Hardened test suite for CI stability across dispatch, session, and daemon tests

Other Changes

• Added test runner script with environment readiness checks
• Regenerated agent instructions with fix-cycle note convention
• Updated review and task-work skills for per-cycle review model

Full Changelog: v0.11.0...v0.12.0

v0.11.0

Comprehensive web UI revamp with 11 new views, a design system foundation, and extensive bug fixes.

Features & Additions

• Dashboard Overview — Active work summary, status counts, needs-attention section with animated counters
• Task Board (Kanban) — Column-based view (Backlog/Ready/In Progress/Review/Done) with task cards, detail modal, and Active Fleet row showing live agent output
• Session Stream — Real-time session viewer with thinking blocks, tool call views, message rendering, and auto-scroll
• Session History — List view of past agent sessions with filtering, dispatch detection, and duration display
• Agent & Dispatch View — Agent cards with edit forms, dispatch status, active invocation monitoring
• Plans View — Plan list with progress tracking and lazy-loaded content expansion
• Workflows Page — Workflow list with step visualization and start action
• Settings Page — Project config, conventions, daemon info, shadow branch health status
• Validation & Alignment View — Spec coverage metrics, trait AC warnings
• Specs Page — Spec item browser with plan filtering
• Enhanced Inbox — Triage status indicators, category/status filters
• Design system — Token contract with semantic color variables, animation utilities (shimmer, breathe, pulse)
• ReferenceLink component — Unified task/spec/item reference display with title resolution
• Shared package — @kynetic-ai/shared with API types and Zod schemas used by daemon and web UI

Bug Fixes

• Fixed automation filter dropdown (was All/Eligible/Blocked, now All/Eligible/Needs Review/Manual Only)
• Removed useless Task/Subtask type filter
• Unified task detail display — kanban modal now used across both views
• Fixed kanban and task list overflowing viewport (responsive layout)
• Fixed kanban board task count and column distribution
• Resolved task titles in sessions and dispatch views (was showing raw IDs)
• Fixed shadow branch health check in daemon (was passing full path instead of directory name)
• Fixed validate page crash from undefined traitCycles
• Fixed inbox/triage filter dropdowns (Svelte 5 migration)
• Gated sidebar badge counts on project store initialization
• Tool calls collapsed by default with truncatable name badges
• Fixed ReferenceLink nested interactive elements and double @@ prefix

CI Fixes

• Added build:shared step to root build script for CI
• Fixed gh-pages deploy workflow to build shared package before web-ui

Full Changelog: v0.10.0...v0.11.0

v0.10.0

Major release introducing the agent dispatch engine — a fully integrated system for autonomous task execution, replacing the external ralph orchestrator.

Features & Additions

• Agent dispatch engine — autonomous task dispatch with configurable agents, dispatch rules, and priority scheduling (kspec agent dispatch start/stop/status/watch)
• Agent invocation lifecycle — structured agent runs with session tracking, budget enforcement, and failure handling
• Agent CLI commands — kspec agent run, kspec agent list, and dispatch management commands
• Dispatch watch streaming — real-time text output from running agent invocations via kspec agent dispatch watch
• Agent runtime streaming — live stdout output during kspec agent run
• Daemon dispatch integration — dispatch engine runs inside the daemon with WebSocket event streaming
• Web UI bundled in npm package — daemon serves the web interface directly from the installed package
• Extended agent schema — dispatch rules, trigger events, and runtime fields for agent definitions
• Extended session model — trigger source, agent_id, and agent lifecycle events
• Stale session management — detect and close stale active sessions with kspec session close-stale
• Web UI triage filters — action filter control with URL-persisted state
• Dispatch-rule CLI flags — configure agent dispatch rules from the command line
• Session log text replay — kspec session log show --text for readable session transcripts
• Batch ergonomics — tags alias for tag, P1/P2/P3 priority aliases
• Task description editing — kspec task set --description support
• Dispatch orientation context — dispatch prompts include project context and review_url field

Bug Fixes

• Fixed serve command safety when running under dispatch (prevents agents from killing their host daemon)
• Fixed concurrent task mutation data loss during agent invocations (atomic writes)
• Fixed spec item save/update concurrency (stale full-object write protection)
• Fixed atomic plan and inbox updates
• Fixed dispatch queue staleness and self-triggering suppression
• Fixed WebSocket disconnect cleanup for dropped clients
• Fixed dispatch watch subscription handling for Node clients
• Fixed EPIPE handling in JSON-RPC framing output
• Fixed batch stdin fail-fast and .kspec read/write buffer bypasses
• Fixed session task count for ACP adapters
• Fixed needs_work→in_progress budget enforcement exemption
• Fixed validation drift detection using Zod schemas at runtime
• Fixed ULID ref disambiguation across CLI/export
• Fixed triage to consume promoted inbox items by default
• Fixed shadow branch auto-push failure warning surfacing
• Fixed rate-limit event noise suppression in agent output
• Fixed out-of-order message chunk streaming
• Fixed skill render hash commit to shadow branch

Other Changes

• Replaced external ralph orchestrator with built-in kspec agent dispatch
• Refactored skill reference token rewriting to use shared resolver
• Improved E2E test isolation with ephemeral ports per test
• Enforced task branch isolation before edits

Full Changelog: v0.9.1...v0.10.0

v0.9.1

Bug fixes and stability improvements for the kspec CLI, ralph orchestrator, and merge driver.

Bug Fixes

• Truncated oversized ACP prompt payloads in ralph to prevent failures (#590)
• Fixed merge driver non-interactive exit code and TTY detection (#601)
• Accepted underscore arg variants in batch payloads (#600)
• Resolved observations slug ambiguity (#599)
• Failed fast for empty batch --commands input (#598)
• Avoided shell-based git command execution in shadow operations (#597)
• Added suggestion for meta observe get when observation refs used with item get (#595)
• Added explicit --agent override support for setup (#594)
• Accepted P1-P5 priority notation in task commands (#593)
• Included package version in agents freshness hash (#592)
• Deleted remote branches on PR merge in workflow (#589)
• Prevented task patch TTY hang without --data (#588)
• Fixed ralph orchestrator memory leaks causing OOM after ~30 iterations (#586)
• Isolated scoped mode checks in validate (#585)
• Updated post-init messaging to be CLI-first and config-aware (#584)
• Aligned observe core skill source-of-truth (#583)
• Improved ralph adapter-not-found error message (#582)

Tests

• Added triage API WebSocket broadcast E2E coverage (#596)
• Added link detection coverage for npm link checks (#591)
• Added explicit session-events ac-7 coverage (#587)

Full Changelog: v0.9.0...v0.9.1

v0.9.0

Session event management and ralph adapter improvements.

Features & Additions

• Added retroactive session event compaction command for managing oversized session histories
• Made ralph skill invocation adapter-aware, formatting commands per adapter type (Claude Code, Codex)

Bug Fixes

• Fixed oversized event payloads in sessions by externalizing them to blob storage
• Routed ralph PR reviews to the dedicated pr-review skill
• Fixed terminal output streaming to session artifacts
• Fixed ralph adapter validation false-negative for codex-acp adapter

Other Changes

• Added lint guard preventing static-analysis source scans in tests
• Tightened conventions and skill guidance documentation

Full Changelog: v0.8.0...v0.9.0

v0.8.0

This release improves Codex integration across setup, skill installation/rendering, and adapter configuration, plus hardens several runtime and CI edge cases.

Features & Additions

• Added first-class codex-acp adapter support and per-role adapter selection for ralph loop execution.
• Added per-adapter auto-approve argument support to make loop automation behavior adapter-aware.
• Enabled Codex core skill install/render support with namespaced skill references.
• Ported project skills to both Claude and Codex render outputs.
• Seeded Codex project_doc_fallback_filenames with kspec-agents.md to improve instruction loading.

Bug Fixes

• Unified Codex detection behavior across setup/status and enforced Codex precedence over Copilot markers.
• Corrected Codex ACP scoped package naming.
• Switched Codex environment injection to TOML and fixed restore handling.
• Fixed shadow git detection for restricted runtime environments.
• Fixed portable skill reference rendering and supporting docs translation for platform targets.

Other Changes

• Bumped package version to 0.8.0 and regenerated kspec-agents.md with the new version marker.

Full Changelog: v0.7.0...v0.8.0

v0.7.0

Added batch usage documentation for agents and improved CLI discoverability, alongside a major test migration from static analysis to E2E tests and several reliability fixes.

Features & Additions

• Added batch usage template (07-batch-usage.md) documenting JSON format, argument rules, and invocation methods for agent instructions
• Added path filter to kspec batch commands — look up a single command's schema with kspec batch commands "task set"

Bug Fixes

• Fixed bootstrap script detecting stale dist/ and rebuilding when source is newer
• Improved session-close-error test reliability
• Added missing AC-6 behavioral test coverage

Test Migration (Static Analysis → E2E)

• Replaced static analysis tests with Playwright E2E tests for daemon Error Handling + Projects API
• Replaced static analysis tests with E2E tests for daemon Server core
• Replaced static analysis tests with E2E tests for daemon WebSocket
• Replaced static analysis tests with E2E tests for daemon watcher
• Deleted remaining static analysis tests for ralph, web-ui-triage, and misc

Documentation

• Clarified task vs inbox agent guidance — explicit user requests always create tasks

Full Changelog: v0.6.0...v0.7.0

v0.6.0

Quality and reliability release — massive test migration from static analysis to E2E, improved validation output, and cross-platform fixes.

Features

• Split trait AC and own AC coverage in kspec validate output for clearer coverage visibility (#542)
• Session-scoped checkpoint hook filtering — checkpoints only fire for the active session (#537)
• Local test sharding — npm run test:shard1/2/3 for ~3x faster dev runs (#536)

Bug Fixes

• Bootstrap always npm-links local kspec build — reliable dev setup on fresh clones (#549)
• Shadow branch detection works in shallow clones — CI and container environments now handled (#548)
• KSPEC_SESSION_ID injected via harness config in ralph loop (#541)
• Checkpoint hook guidance uses task submit instead of task complete (#540)
• Debug logging for malformed hook input in parseHookInput (#535)
• Runtime validation for unsafe type casts in session log commands (#534)
• Cap total notes at --limit in gatherSessionContext (#529)
• Validate --limit option to reject NaN in gatherSessionContext (#527)
• Named handlers replace removeAllListeners() for stdin cleanup (#526)

Test Migration (Static Analysis → E2E)

Replaced static source-analysis tests with real Playwright E2E tests for all daemon APIs:

• Triage API (#547)
• Meta + Validation APIs (#546)
• Inbox API (#545)
• Items API (#544)
• Tasks API (#543)
• Added edge case tests for item set enum validation (#531)

Refactoring

• Split monolithic session.ts into focused modules (#523)
• Single-pass task bucketing in gatherSessionContext (#530)
• Consolidated naming inconsistencies in session modules (#532)
• Removed dead code in session modules (#533)
• Consolidated dual ImplementationStatusSchema import (#538)
• Extracted shared test helpers for session start tests (#525)

Other

• Bootstrap uses npm ci and migrated worktree guard to native kspec command (#539)

Full Changelog: v0.5.0...v0.6.0

v0.5.0

Session management overhaul, ralph loop improvements, and multi-harness support.

Features & Additions

• Rewrote session start output with primer/full modes, hierarchical activity timeline, and computed JSON fields (#515, #519, #514)
• Added triage-aware inbox statistics to session start (#513)
• Added unlocks N dependency display showing what completing a task unblocks (#508)
• Implemented session create command and library function (#500)
• Added session-scoped task claiming with session_id on task schema (#499)
• Added task budget schema, CRUD functions, and enforcement at task start (#498, #501)
• Replaced marker files with session budget in ralph loop (#504)
• Migrated end-loop signal from marker file to session state (#503)
• Replaced bash guard scripts with native kspec guard worktree command (#506)
• Added multi-harness env injection for Gemini CLI and OpenCode (#507)
• Added depends_on, priority, and YAML-safety detection to plan import (#491, #492, #493)
• Added CLI lookup tables to skills for agent self-sufficiency (#521)

Bug Fixes

• Fixed ralph signal handler to properly await async cleanup (#518)
• Added enum validation for item set --status and --maturity (#517)
• Fixed ralph wrap-up agent causing test timeouts (#512)
• Fixed env variable pollution when tests run inside ralph loop (#509)
• Review skills now dig for spec context instead of skipping AC checks (#511)
• Added advisory file locking to prevent concurrent write data loss (#494)
• Fixed task set null clearing for --spec-ref and --meta-ref (#490)
• Fixed task submit counting toward max-tasks limit (#489)
• Resolved batch-exec-engine test timeout flakes (#505)
• Added ralph-loop safety guard to codex skill prompt (#495)

Testing & Documentation

• Added comprehensive session start output tests and AC annotations (#516)
• Documented N/A trait AC annotation format (#520)
• Strengthened batch malformed JSON error tests (#496)

Other Changes

• Removed 6 obsolete project skills superseded by core skills (#488)
• Removed ralph-task-limit-guard shell hook (#502)

Full Changelog: v0.4.0...v0.5.0