openplanr 1.22.0 → 1.23.0

package/CHANGELOG.md

@@ -0,0 +1,1388 @@
+# Changelog
+
+## 1.23.0
+
+### Minor Changes
+
+- [`4353b7d`](https://github.com/openplanr/OpenPlanr/commit/4353b7d727cf5312ee684eb4dc96252ccc9f5f43) Installed-tuple reconciliation and a safe, honest upgrade path (SPEC-006).
+
+Until now the CLI could tell you your install had drifted and then leave you to
+derive the fix yourself across two package managers. `doctor` already computed
+component, digest, adapter, and CLI drift correctly — nothing acted on it, and
+nothing read back the compatibility ranges the ecosystem manifest already
+publishes.
+
+**Reconcile the installed tuple, not "is something newer".** A new
+`planr upgrade status [--json]` reads the published compatibility manifest,
+compares it against the real installed tuple — this CLI plus both host-plugin
+versions — and reports `aligned`, `upgrade-available`, `incompatible`, or
+`unknown`. The warn-versus-fail distinction is not re-derived: `doctor`'s inline
+lock-drift classification is extracted into a single exported
+`classifyComponentDrift` that both surfaces call, so a CLI merely trailing an
+upgrade stays a warning while a genuinely incompatible tuple fails. Every
+pre-existing `doctor` assertion passes unchanged as proof the extraction
+preserved its behaviour. An absent plugin is recorded as absent, never as a
+violation, so a planning-only install does not read as broken.
+
+**Offline capability is preserved by construction.** The manifest fetch trusts a
+short-TTL cache without any network round-trip, carries a hard timeout that wins
+even when a fetch hangs, falls back to a stale cache when the network fails, and
+reports `unknown` when there is neither — so a captive portal, a VPN, or an
+airplane can never make `planr` block. Proven by offline and hung-network tests
+and by a packed-install end-to-end test that reads the real installed version
+rather than a fixture.
+
+**Execute the half it owns; prescribe the half it cannot.**
+`planr upgrade apply [--yes] [--json]` performs `npm install -g openplanr@<target>`
+and prints the plugin commands it structurally cannot run — plugin installation is
+a host command, not something a CLI can own. The prescription is rendered from the
+plugin integration's own operation list, so the printed commands can never drift
+from what an apply would really run, and the marketplace-refresh command is always
+placed first: without it the installer reinstalls the stale version and the user
+believes they upgraded. A grep gate proves the upgrade service never imports the
+plugin-apply path, and an end-to-end test proves no mutating plugin command is
+ever spawned.
+
+**A partially-upgraded install can never report success.** The previously
+installed version is captured as a restorable backup before any mutation, and the
+on-disk version is re-read afterwards. A clean exit that did not land the target
+restores the previous version automatically and states exactly what was restored
+and how to retry. On success, the changelog entries strictly between the old and
+new version are summarised verbatim — never inventing a change the changelog does
+not carry — and `CHANGELOG.md` now ships in the package so that summary works on a
+real installation rather than only in-repo.
+
+**The offer comes to you.** An available upgrade now surfaces on an ordinary
+interactive command as a four-way choice — upgrade now · always keep me current ·
+not now · never ask — so nobody has to run a diagnostic to discover they are
+stale; accepting resumes the command you originally invoked. "Not now" snoozes
+with escalating backoff (24 hours, then 48, then a week) so it never nags.
+`auto_upgrade` and `update_check` are real settings, neither inferred from a bare
+invocation, and "never ask again" is a permanent opt-out that always states the
+exact command reversing it. A snooze, a never-ask, or a disabled check
+short-circuits before any reconcile, so a command that already declined touches no
+network and adds no delay; the state file is read fail-open, and the offer never
+surfaces for machine-readable or non-interactive invocations.
+
+**Upgrades can now carry state forward.** Idempotent migrations keyed to a version
+run automatically when an upgrade crosses that version, for state a reinstall
+cannot repair — stale config, orphaned files, a changed on-disk layout. A strict
+lower bound means a migration at or below the installed version never re-runs, and
+one migration failing neither aborts the others nor is swallowed into an overall
+success. The legacy operating-profile migration is registered as the proving case
+by delegating to the existing implementation, reusing its exact-backup, journalled
+write with rollback, and idempotency guarantees rather than forking them; the
+standalone `operate profiles migrate` command keeps working unchanged. A migration
+failure reports failure while still reporting the npm step's real success, so a
+half-migrated install can never claim to be clean.
+
+## 1.22.0
+
+### Minor Changes
+
+- [`5b525e2`](https://github.com/openplanr/OpenPlanr/commit/5b525e29c4843535f68a013c4d658b91ad9ed0d6) Operate durable orchestration (SPEC-005): per-role durability, honest state, and a
+  one-invocation review gate. Bundled pipeline dependency pinned to
+  `planr-pipeline@0.39.0`. Every claim below is backed by a named passing test;
+  coordinated sibling releases still in flight under this same version are described
+  as landing with the release, never as a phase this repository has already verified.
+
+**The field fix that matters most: the advisor fan-out no longer deadlocks on a
+hung lens.** The pre-driver fan-out awaited every advisor together, so one lens
+stalling left the whole `Promise.all` unresolved while completed analyses sat
+unrecorded and the shared lease expired underneath them. Dispatch now runs through
+a deterministic lifecycle driver with bounded per-role retry, a per-attempt
+timeout, and an automatic lease heartbeat that renews independently of any role
+recording. A stalled non-required lens is resolved `not_evaluated` with a governed
+gap while its siblings record and the cycle reaches Chair. Proven by
+`tests/integration/operate-lifecycle-chair-wiring.test.ts` ("terminates a stalled
+lens not_evaluated while siblings record, renews the lease, and reaches Chair") and
+`tests/unit/operate-lifecycle-driver.test.ts` ("resolves a role past its retry
+budget to not_evaluated with a governed gap without blocking siblings" and "renews
+the lease as the window approaches without any role completing").
+
+**Immediate per-role commit and an engine-managed heartbeat lease.** Each advisor
+result is validated, recorded, persisted, and reflected in cycle progress the
+moment it returns, and survives a sibling stalling; recording never waits on the
+batch. Proven by the lifecycle-driver state-machine and heartbeat suites in
+`tests/unit/operate-lifecycle-driver.test.ts`.
+
+**Partial validated progress and honest status/report.** Every recorded lens is
+inspectable before Chair finalizes, and a mid-cycle report renders recorded lenses
+with their real analysis plus the exact recovery action for pending roles — an
+active advising cycle is never described as quiet. Proven by
+`tests/integration/operate-partial-report.test.ts` ("renders recorded lenses with
+their real analysis and the exact recovery action for pending roles").
+
+**Chair works with partial valid boards.** Chair consolidates the recorded,
+verified board and surfaces an absent lens as an explicit gap; it never invents a
+missing lens's conclusions, and it stays closed while a structurally-required role
+is only `not_evaluated`. Proven by `tests/unit/operate-lifecycle-driver.test.ts`
+("holds the Chair closed while a structurally-required role is only
+not_evaluated") and the chair-wiring happy-path test above ("records a five-lens
+board and reaches Chair with no fabricated gap on the happy path").
+
+**Owned scratch storage with a `doctor --fix` cleanup.** Operate scratch lives
+under an OpenPlanr-owned, project-and-machine-keyed path recorded in an ownership
+manifest, cleaned automatically after record/finalize, detected by `doctor` when
+abandoned, and removed by the FR7-named `planr doctor --fix` — which acts only on
+scratch a valid ownership manifest confirms is ours, never on an unrelated file
+under the scratch tree. Proven by `tests/unit/operate-doctor-staleness.test.ts`
+("warns on abandoned owned scratch and removes only it, leaving other
+machine-local caches") and `tests/unit/operate-doctor-fix-wiring.test.ts`
+("removes abandoned OpenPlanr-owned scratch and leaves an unrelated file
+untouched").
+
+**Completion discipline.** Completion requires on-disk verification of every
+phase-F artifact and flips to incomplete when any is removed or abandoned owned
+scratch remains. Proven by `tests/unit/operate-completion.test.ts` ("reports
+complete only with every phase-F artifact, and flips when any is removed").
+
+**Legacy operating-profile migration.** `planr operate profiles migrate
+inspect|apply` detects a legacy profile, previews and converts the supported
+subset, writes an exact pre-migration backup, and is idempotent — the CLI never
+suggests a profile it will reject. Proven by
+`tests/unit/operate-profile-migration.test.ts` ("writes an exact pre-migration
+backup and rewrites the profile to the supported subset" and "is idempotent: a
+second apply reports already-applied and makes no further change").
+
+**Bundled pipeline pin.** The packed CLI carries
+`optionalDependencies.planr-pipeline = 0.39.0`, asserted by
+`tests/e2e/operate-packed-install.test.ts` and
+`tests/e2e/operate-guided-packed-install.test.ts`.
+
+Coordinated, not yet released with this changeset: `@openplanr/skills@1.24.0`
+(thin workflow regeneration) and the marketplace ledger and real-runtime canary
+land only after `planr-pipeline@0.39.0` and this `openplanr` version publish.
+
+## 1.21.2
+
+### Patch Changes
+
+- [`2bc31c4`](https://github.com/openplanr/OpenPlanr/commit/2bc31c48c46912f542c1a52a143492d81e013e48) Align the bundled pipeline dependency with planr-pipeline 0.38.0.
+
+## 1.21.1
+
+### Patch Changes
+
+- [`3c1101b`](https://github.com/openplanr/OpenPlanr/commit/3c1101b6699d1b7f0bdaedce3a41f37941228811) Align the bundled pipeline with planr-pipeline 0.37.2 so released Operate canaries execute correctly through the Windows command shim.
+
+## 1.21.0
+
+### Minor Changes
+
+- [`fd81cd9`](https://github.com/openplanr/OpenPlanr/commit/fd81cd94ca4a13c3b590544b242cf7fe21078824) Rebuild `planr operate` around agent-native, runtime-bound research, six advisory roles, expressive cited reports, and approval-gated canonical proposal drafts across Claude Code, Codex, and Cursor.
+
+## 1.20.0
+
+### Minor Changes
+
+- [`9a536c4`](https://github.com/openplanr/OpenPlanr/commit/9a536c47b36430bf0d8700d63fc11d3259b97bc7) The Operating Board harness pivot for `planr operate` (SPEC-004), the `openplanr` minor
+  bump 1.19.0 → 1.20.0 — the agent is the engine; the CLI harnesses, verifies, and records.
+  Every landed claim below is backed by a named proof; coordinated sibling work still
+  completing under this same version is described as landing with the release, never as a
+  phase this repository has already verified.
+
+**The mandate replaces the collector as the unit of dispatch.** A per-role operating
+mandate carries the lens question, declared read boundaries (workspace roots — including
+the `.planr/` tree — a sensitivity ceiling, and forbidden paths), a required response
+schema, and a citation requirement, and it carries no evidence bodies and no evidence
+index — structurally forbidden rather than merely omitted. Proven by
+`tests/unit/operate-adapter-mission-dispatch.test.ts` ("prepares a mandate (not a pack)
+with declared boundaries and no evidence body ..."), whose fixture fails if any file body
+ever leaks into the body-free, index-free mandate.
+
+**Evidence is an output, not an input, and citation resolution is the universal gate.**
+`adapter record` resolves every citation in a response fail-closed and mints the
+evidence-of-record from what was actually cited. A fabricated path, a wrong line range, a
+moved revision, or a citation above the role's sensitivity ceiling each becomes a governed
+gap — on every dispatch path and every source — and a response resolving zero citations
+records its role `not_evaluated` with a governed gap naming the empty grounding. Proven by
+`tests/unit/operate-citation-resolution.test.ts` ("rejects a fabricated path, a wrong line
+range, and a moved revision with distinct reasons and one gap each" and "commits a role
+not_evaluated with a governed gap when its citations resolve zero evidence") and by the
+above-ceiling refusal in `tests/unit/operate-mission-honeytoken-isolation.test.ts`
+("refuses a read above the sensitivity ceiling inside a granted root").
+
+**Hard-blocked secrets in cited content are rejected, not redacted-and-accepted.** A
+citation whose snapshot contains a hard-blocked secret category is refused as an
+unresolvable citation gap instead of being persisted in redacted form. Proven by
+`tests/unit/operate-citation-resolution.test.ts` ("rejects a citation into
+HARD-blocked-secret content as unresolvable, never redacted-and-accepted"), with a
+soft-secret assignment still redacted-and-accepted so the distinction is exercised both
+ways.
+
+**A gitignored `.planr/` tree is fully citable — by architecture.** The dispatched agent
+reads the filesystem directly rather than `git ls-files`, so a project that gitignores its
+`.planr/` control surface can still ground the three lenses (CPO, CMO, COO) that the
+fourth field audit found unsatisfiable when candidates came only from tracked files — the
+defect that starved three of six lenses is gone by construction, not by repair. Proven by
+`tests/unit/operate-mission-honeytoken-isolation.test.ts` ("reads a gitignored .planr/
+tree — the mission tool walks the filesystem, not git ls-files (finding 2)").
+
+**Guided init has no livelock, no dead-end advice, and a revise path.** An answer envelope
+is accepted on its binding validity (session id, questionnaire digest, project head)
+rather than on wall-clock ordering, a transiently stale session un-latches when the tree
+is restored, a genuinely terminal rejection names the resumable session id and its exact
+`--resume` command, a previously answered question can be re-answered before apply, and the
+questionnaire advertises `--answers-file` as a stdin-parity transport alternate with
+per-question renderability metadata. Proven by
+`tests/unit/operate-question-session.test.ts` ("accepts an answer envelope whose
+submittedAt predates the session (livelock regression)" and "un-latches a transiently
+stale session when the tree is restored"),
+`tests/integration/operate-question-resume.test.ts` (the resume command surfaced in the
+next actions), and `tests/unit/operate-question-engine.test.ts` ("advertises
+--answers-file as a stdin-parity transport alternate with its exact argv" and "carries
+repeated-text renderability metadata sufficient to present without improvisation").
+
+**Completing the pivot in the same coordinated release.** Sibling work landing under this
+version retires the now-dead evidence collector — its walks and budgets, role packs,
+mission packets, and the `pack|mission` dispatch-mode split — behind the mandate contract;
+renders cycle integrity (citation rejections, boundary refusals, `not_evaluated` roles) as
+a first-class section of the readable tree and a `doctor` check; makes the persisted
+`cycles/<id>/report.md` a self-contained record with complete registers; corrects the
+"commit-safe root" claim to an honest, redaction-based statement; and collapses runtime
+classification to mandate-capable-or-unsupported with no silent structured fallback. On the
+same schedule, the CLI's own structured-provider advisor path and its `--ai` planning
+surfaces are deprecated (FR4) — functional this release, pointed at the harness flow, and
+scheduled for removal, never broken and never silently removed. These items land with this
+release rather than ahead of it; their per-task proofs live under
+`.planr/specs/SPEC-004-operate-agent-harness-architecture/`.
+
+**Pins the optional `planr-pipeline` runtime to the exact `0.36.1`** — the build that
+publishes the additive operating-mandate schema (the same additive pattern as
+`create-quick-task`/`create-epic`), the regenerated mandate-flow command/skill
+instructions, the registry investigation mandates, and the reclassified adapter capability
+rows this release dispatches against. Verified:
+`optionalDependencies["planr-pipeline"] === "0.36.1"`, the three workflow `ref: v0.36.1`
+pins, and both packed-install e2e assertions.
+
+## Unreleased
+
+### Deprecations
+
+- CLI-managed Operating Board structured-provider dispatch and the legacy
+  `--ai` planning surfaces remain functional in this release, but now emit one
+  shared deprecation notice. Agentic investigation and advisory work belongs in
+  the native runtime harness through Protocol v1.3 mandates. Both legacy surfaces
+  are scheduled for removal in OpenPlanr 2.0.0; see
+  https://openplanr.dev/docs/operate/agent-harness.
+
+## 1.19.0
+
+### Minor Changes
+
+- [`acbdfed`](https://github.com/openplanr/OpenPlanr/commit/acbdfed8ab0fce13a65f7fd9c4ff58dc705c62ea) Operating Board outputs and epic-loop release for `planr operate` (SPEC-003), the
+  `openplanr` minor bump 1.18.0 → 1.19.0. Every claim below is backed by a named proof;
+  nothing describes a phase this repository has not actually reached.
+
+Cycle reports and boards are now persisted as truthful on-disk artifacts: a single rich
+assembly drives both `cycles/<id>/report.md` and every `board/<role>.md`, so `report.md`
+is byte-identical to the review rendering and each evaluated board file carries its lens
+recommendations with impact/confidence/ease (I/C/E) scores — proven by
+`tests/unit/operate-projection-persistence.test.ts` ("renders cycles/<id>/report.md and
+rich board files from the assembled lens artifacts"). The readable tree is consolidated:
+the legacy `projections/` directory is retired (never written), the parked-findings
+`backlog.md` is promoted to the top level, and `state.json` moves under `.state/` —
+proven by `tests/integration/operate-preview-boundaries.test.ts` and the persistence
+suite's asserted paths (`.planr/operate/backlog.md`, `.planr/operate/.state/state.json`,
+no `projections/`).
+
+Evidence loss is never silent. A capped repository walk names the last path it reached
+and the top-level directories it never scanned, mission-index drops are counted and
+surfaced as cycle warnings, sensitivity narrowing is scoped to the offending items, and a
+starved role is gated not-ready with a governed data gap while every ready role still
+dispatches — proven by `tests/integration/operate-evidence-recovery.test.ts` ("gates a
+starved repository role with a governed gap while other roles still dispatch (FR2)").
+Collection is prioritized and fair: per-top-level-directory round-robin plus git-recency
+ordering, with split repository/planr file budgets replacing the shared `maxFiles`
+counter — proven by `tests/integration/operate-evidence-monorepo-fairness.test.ts`
+("samples every product top-level directory under a cap the tree exceeds combined" and its
+deterministic re-selection check).
+
+Mission budgets are sized for real repositories: the derived mission-budget clamp ceiling
+rises from 9 to 32 KiB against real index-item costs, per-role `maxEvidenceItems` caps are
+enforced, and an oversized index is truncated to fit with the drop reported as a cycle
+warning — never a silent drop and never an unexplained fail-closed on a healthy repo —
+proven by `tests/unit/operate-mission-packet.test.ts` ("truncates a monorepo-scale index
+to the cap, fits the budget, and reports the drop (FR4)" and "leaves a healthy repository
+under its cap untouched — no warning, no fail-closed (FR4)"), with the field-scale pack
+path still failing closed with no provider invocation in
+`tests/unit/operate-advisor-pack-scale.test.ts`.
+
+Re-initialization preserves machine-local preferences: a no-flag re-init carries
+`dispatchModeOverrides`, `adapterLeaseDurationMs`, and `lastRunAt` forward, and the init
+preview names exactly which preference a re-init will change — proven by
+`tests/unit/operate-initialization-replay.test.ts` ("carries dispatchModeOverrides,
+adapterLeaseDurationMs, and lastRunAt forward on a re-init with no flags (field repro)")
+and `tests/integration/operate-guided-init.test.ts` ("names exactly which machine-local
+preferences a re-init will change in the preview").
+
+The epic loop closes: the report groups related accepted findings into a ready-to-run
+`planr epic create --title …` suggestion naming the member findings, and the `create-epic`
+route applies a real `.planr/epics/EPIC-NNN-<slug>.md` artifact through the write-ahead
+journal with byte-exact rollback while never invoking PLAN or SHIP (R1 intact) — proven by
+`tests/integration/operate-decision-brief-render.test.ts` ("renders one planr epic create
+suggestion naming both accepted findings") and `tests/integration/operate-route-lanes.test.ts`
+("elects, applies, and byte-exact rolls back a grouped-finding epic without ever invoking
+PLAN or SHIP").
+
+Pins the optional `planr-pipeline` runtime to the exact `0.35.0` — the build that ships the
+FR4 packet-enforcement half, the additive FR8 `create-epic` operating-route-plan schema,
+the reviewed registry role budgets, and the regenerated operate assets this release proves
+against (`optionalDependencies["planr-pipeline"] === "0.35.0"`, mirrored by the three
+workflow `ref: v0.35.0` pins and both packed-install e2e assertions).
+
+## 1.18.0
+
+### Minor Changes
+
+- [`0bd9c2a`](https://github.com/openplanr/OpenPlanr/commit/0bd9c2a8859631085c121bcd819e6cf45a4c33d1) Field-fix release for the `planr operate` Operating Board (SPEC-002), hardening the
+  Protocol v1.3 agentic engine against issues found once real field incidents drove the
+  board. Native mission dispatch is now wired end to end: a bound role prepares a mission
+  packet (not a v1.2 pack) and hands back a v1.3 mission record action on a claude-code
+  runtime, threading v1.3 citation-bearing responses through the recorded-proposal gate,
+  while codex/cursor fail closed to the pack path — proven by
+  `tests/unit/operate-adapter-mission-dispatch.test.ts` ("native mission dispatch reaches
+  the record action"). Advisor pack budgets now fail closed at field-incident scale:
+  `createOperatingAdvisorPack` throws before returning a field-scale pack, and both the
+  dispatch and adapter-lifecycle prepare call sites refuse with no provider invocation and
+  persist no session, with checkpoints holding at 10,000 events. The human review renderer
+  presents the write-free `review` stage — question, evidence, options, and blockers —
+  before any initialization is applied. Guided continuations return `ok: true` and hand the
+  runner a directly executable `confirmArgv` on a digest-confirmable action. Adapter sessions
+  bind to board identity so a re-inited board never collides with a prior generation, and
+  `doctor` gains two staleness diagnostics (FR11): a stale adapter session bound to a
+  superseded board generation and a stale incremental baseline whose `workspaceDigest`
+  drifted, each with a scoped fix. Provider bootstrap failures surface as typed
+  `E_OPERATE_ADVISOR_FAILED` errors with a remedy, the readiness preflight names a missing
+  provider key before a cycle starts, and runtime detection resolves the real host from env
+  markers instead of stamping `unknown`/`none`. The init questionnaire is on a diet with
+  preselection (only unanswered canonical questions are returned; the decision owner is
+  suggested from the git user) and accepts `--answers-file` as a bounded stdin-parity alias
+  under the same 64 KiB cap. Adapter leases surface their expiry and remaining time in prepare
+  output and the handoff (default 15 minutes), refresh on each successful record, and honor a
+  machine-local configured lease duration. Pins the optional `planr-pipeline` runtime to
+  `0.34.0`, the build that ships the regenerated v1.3 templates this release proves against.
+
+## 1.17.0
+
+### Minor Changes
+
+- [`5e2fac8`](https://github.com/openplanr/OpenPlanr/commit/5e2fac89bd61d4095acb421fa26b987113573c65) Advance `planr operate` to the Protocol v1.3 agentic engine (OPERATE-SPEC-004):
+  automatic, lossless `.state/` layout migration that is journal-driven
+  (crash-safe) and byte-exactly reversible; a live evidence index with
+  digest-bound mission packets; bounded, read-only native dispatch guarded by a
+  mission honeytoken refusal suite and per-role `pack`/`mission` dispatch-mode
+  overrides; citation resolution as the audit mechanism, fail-closed and reporting
+  a distinct dirty-working-tree outcome; quick-task routing; self-contained
+  offline decision briefs that fail closed on any non-local reference; cadence
+  status that only reports and never requests an action; a skill-first operate
+  cycle; and v1.3 doctor checks. Pins the optional `planr-pipeline` runtime to
+  0.33.1, the build that ships the `schemas/v1.3.0` mission-packet surface.
+
+## 1.16.2
+
+### Patch Changes
+
+- [`7d85669`](https://github.com/openplanr/OpenPlanr/commit/7d8566968e6e75aa7f5d2fce05157b0257498e08) Manage compatible Claude Code marketplace plugins during confirmed setup and
+  runtime updates, and diagnose stale versions or invalid plugin identities.
+
+## 1.16.1
+
+### Patch Changes
+
+- [`935e43b`](https://github.com/openplanr/OpenPlanr/commit/935e43b2ca4c07b2053a728ae2f90af24a151e6d) Complete bare Planr Operate invocations through the native runtime cycle, prevent Unicode evidence truncation from corrupting state, quarantine advisor-ineligible excerpts before readiness, make cancellation retry-safe, and diagnose stale questionnaire-first runtime skills.
+
+## 1.16.0
+
+### Minor Changes
+
+- [`e1f5127`](https://github.com/openplanr/OpenPlanr/commit/e1f5127d7250ca785723c91cdf03c2ab08a2e614) Run Operating Board cycles through bounded native runtime advisors, quarantine unsafe evidence without blocking unrelated lenses, and add actionable Markdown/JSON executive reports.
+
+## 1.15.1
+
+### Patch Changes
+
+- [`656b673`](https://github.com/openplanr/OpenPlanr/commit/656b673f5506c49e18b5ca3759027d6150cd7c9c) Make direct Operating Board initialization previews return a self-contained, digest-bound replay command that applies without restarting the questionnaire, and route focused integration gates through their executable Vitest configuration.
+
+## 1.15.0
+
+### Minor Changes
+
+- [`1b829e8`](https://github.com/openplanr/OpenPlanr/commit/1b829e8ccd8b025a214811ecf02cc2ac9adb1b89) Add CLI-owned guided Operating Board questionnaires, resumable typed-answer
+  sessions, digest-scoped actions, deterministic charter assistance, value-free
+  evidence recovery, runtime-native presentation contracts, and setup/doctor
+  diagnostics without weakening PLAN, SHIP, provider, or route authority gates.
+
+## 1.14.4
+
+### Patch Changes
+
+- [`e4fdfb3`](https://github.com/openplanr/OpenPlanr/commit/e4fdfb3ba9c44ac7da13de9ae9fbab52836048d6) Prevent Operating Board evidence redaction from quarantining safe assignments or reprocessing its own redaction sentinels.
+
+## 1.14.3
+
+### Patch Changes
+
+- [`e986fc0`](https://github.com/openplanr/OpenPlanr/commit/e986fc02e552f6c9741bd9117bc02a1503335953) Derive Operating Board producer provenance from the installed OpenPlanr package version instead of a copied release literal.
+
+- [`08349b3`](https://github.com/openplanr/OpenPlanr/commit/08349b3be8aa8acdc1b5c636f279550b291a4703) Report a missing OpenPlanr configuration as the actionable advisor error instead
+  of an unexpected internal failure. `planr operate init` writes
+  `.planr/operate/config.json`, not the project-wide `.planr/config.json`, so a
+  project that ran only the operate initializer reached the structured adapter
+  with no config at all and surfaced "an unexpected internal Operating Board
+  error" on the primary first-run path.
+
+## 1.14.2
+
+### Patch Changes
+
+- [`0e792eb`](https://github.com/openplanr/OpenPlanr/commit/0e792ebed92f0d7e4a424388390236bb96b0e78e) Reject secrets in native Operating Board advisor results before any commit-safe event or projection is persisted, and pin Changesets' development-only YAML parsers to patched versions.
+
+## 1.14.1
+
+### Patch Changes
+
+- [`c0136af`](https://github.com/openplanr/OpenPlanr/commit/c0136afcadef87fe9d3795e6223fea0cb5f559f0) Point `test:operate:packed` at the config that owns the packed-install suite.
+  The suite moved out of the default vitest project so it could not saturate the
+  shared worker pool, but the script still used the default config, where the file
+  is now excluded — so it exited "No test files found" instead of running.
+
+- [`5c7c05b`](https://github.com/openplanr/OpenPlanr/commit/5c7c05b5188312e461e3464e8c7c27bf5d100ff8) Stabilize the native Operating Board lifecycle under parallel CI load and close
+  the operating lock file safely when its initial durable write fails.
+
+## 1.14.0
+
+### Minor Changes
+
+- [`8e95efb`](https://github.com/openplanr/OpenPlanr/commit/8e95efbfedc0e23e341de1d130ab9df558d6a9d5) Add `planr operate`, an evidence-to-decision operating control plane with safe
+  workspace initialization, event-sourced cycles, isolated advisory lenses,
+  separate finding acceptance and route application, typed outcomes, recovery,
+  strict JSON automation, and cross-runtime workflow support.
+
+## 1.13.3
+
+### Patch Changes
+
+- [`a4c61dc`](https://github.com/openplanr/OpenPlanr/commit/a4c61dc2bb09527783f44ed51d3cfabce3027cc2) Bundle artifacts from their own directory by default, and report safely vendored remote assets in local review output.
+
+## 1.13.2
+
+### Patch Changes
+
+- [`d3e9314`](https://github.com/openplanr/OpenPlanr/commit/d3e9314bd0d3655a65b645d7a63c6dae23f45972) Update the optional `planr-pipeline` runtime to 0.29.0 so `planr artifact`
+  uses the released minimal document review chrome with the floating comments rail.
+
+## 1.13.1
+
+### Patch Changes
+
+- [`ace659d`](https://github.com/openplanr/OpenPlanr/commit/ace659d7afcf55834e0a6f4610881863a4947b7c) Update the bundled pipeline to 0.28.5 so document artifacts use a single outer scrollbar instead of competing iframe scrolling.
+
+## 1.13.0
+
+### Minor Changes
+
+- [`004ca3f`](https://github.com/openplanr/OpenPlanr/commit/004ca3f16451ceb7a47dd95ae897c473587a2ec4) Allow Linear setup to configure one, several, or all accessible teams, select a default, and target configured teams per push with `--team`.
+
+## 1.12.4
+
+### Patch Changes
+
+- [`4f6c4c5`](https://github.com/openplanr/OpenPlanr/commit/4f6c4c51c62ad93447fc0caed64d20ad11fd30c5) Update the bundled pipeline to 0.28.4 for stable live-room sharing, clearer fragment limits, visible copy confirmation, reviewer identity feedback, and keyboard comment submission.
+
+## 1.12.3
+
+### Patch Changes
+
+- [`ed010b3`](https://github.com/openplanr/OpenPlanr/commit/ed010b35fa57c855af89432fb622d1a31f34594d) Make `planr doctor --fix` preview and safely remove stale Planr-owned design and dashboard daemon state. Missing runtimes are now informational unless the current setup selected them.
+
+## 1.12.2
+
+### Patch Changes
+
+- [`0784dbd`](https://github.com/openplanr/OpenPlanr/commit/0784dbd1d311a46f56451188199ab12c4f080407) Decode feedback from existing encrypted live artifact review rooms whose persisted events predate the room-event version field.
+
+## 1.12.1
+
+### Patch Changes
+
+- [`a2b22ec`](https://github.com/openplanr/OpenPlanr/commit/a2b22ec0bbeb5131b6f2a2d5f6d0a99be3558dfa) Use planr-pipeline 0.28.1 so live collaborative rooms encrypt the compressed artifact payload correctly, including rooms created from legacy artifact shares.
+
+## 1.12.0
+
+### Minor Changes
+
+- [`60fd19c`](https://github.com/openplanr/OpenPlanr/commit/60fd19cccd15fecf3cb00c189b8719dc92ee6fcf) Make encrypted live artifact review rooms the default sharing workflow, retain
+  immutable snapshots behind `--snapshot`, support live-room feedback imports,
+  and bundle `planr-pipeline` 0.28.0.
+
+## 1.11.0
+
+### Minor Changes
+
+- [`0c14c9b`](https://github.com/openplanr/OpenPlanr/commit/0c14c9bbe05909da130d5e0bb03aa143444a7b56) Add headless document and zoomable canvas presentations to `planr artifact`,
+  including `--presentation auto|document|canvas`, resolved JSON output, and the
+  planr-pipeline 0.27.1 compatibility update.
+
+## 1.10.0
+
+### Minor Changes
+
+- [`4438a9a`](https://github.com/openplanr/OpenPlanr/commit/4438a9a046beeaa1a0ac9201fc24fa635c36b470) Add `planr artifact` for secure local HTML review, private fragment or encrypted short-link sharing, returned-review import, and live-session export.
+
+## 1.9.1
+
+### Patch Changes
+
+- [`392b50c`](https://github.com/openplanr/OpenPlanr/commit/392b50c26d31d4d3bc680471e7864ec1f1d8beca) Make installation quiet and configuration explicit, add guided runtime setup with safe user-scope defaults, prevent accidental project writes outside Git or initialized OpenPlanr projects, and diagnose legacy home-directory setup files.
+
+## 1.9.0
+
+### Minor Changes
+
+- [`05a3088`](https://github.com/openplanr/OpenPlanr/commit/05a3088ef0af8628f0a38562062192c62fbbbf66) Add the unified cross-runtime distribution flow: `planr setup`, runtime adapter
+  lifecycle management, pipeline routing, unified doctor diagnostics, exact
+  runtime locks, and append-only planning provenance. The full
+  `planr-pipeline` package is installed by default with `--minimal` as the
+  planning-only escape hatch. Codex skills and Cursor rules now come from the
+  shared portable registries, while migrations preserve hand-written content,
+  back up exact bytes, retain shared user assets safely, and support conflict-safe
+  rollback and removal.
+
+## 1.8.1
+
+### Patch Changes
+
+- [`29e89e6`](https://github.com/openplanr/OpenPlanr/commit/29e89e684c915a98603a715030f71ae8c2c7dc2b) Update generated rule templates to reference **Sonnet 5** (was Sonnet 4.6) for the analysis/decomposition tier, matching planr-pipeline v0.24.10. The cursor (`planr-pipeline.mdc.hbs`, `agents/designer-agent.md`, `agents/qa-agent.md`, `agents/specification-agent.md`) and codex (`_pipeline-section.md.hbs`) rule-generator templates now render the current analysis-tier model. The DEV/codegen tier stays on Opus 4.8.
+
+## 1.8.0
+
+### Minor Changes
+
+- Add `planr graph --json`, a read-only artifact graph export for dashboard and
+  ecosystem conformance. The command emits the shared OpenPlanr Protocol graph
+  shape `{ nodes, edges }`, namespaces spec-local story/task ids, and preserves
+  `contains` and `depends_on` edges from frontmatter.
+
+## 1.7.2
+
+### Patch Changes
+
+- [`e60983c`](https://github.com/openplanr/OpenPlanr/commit/e60983c02d49106d11c61c11719788ed1aace7eb) `planr status` is now the **whole-project delivery report**. With no argument it rolls up every Spec / Backlog item / Quick Task (or the agile epic→task tree) by status — **done** · **promoted/superseded** (addressed, never counted as done or outstanding) · **outstanding** — cross-referenced with the GitHub issue/PR and Linear identifiers recorded in frontmatter, ending with a Summary and an **Outstanding work** section. New: an optional `[scope]` argument (one spec/epic/feature id or slug), `--md` (paste-ready markdown report), `--json` (machine-readable for agents/CI), and `--github` / `--linear` to live-resolve PR + issue states (offline frontmatter by default). Powered by the new `delivery-status-service` (deterministic aggregation over the existing artifact/GitHub/Linear services); the previous truncated tree view is superseded by the delivery view (`--all` still controls terminal truncation).
+
+## 1.7.1
+
+### Patch Changes
+
+- [`1c7b70a`](https://github.com/openplanr/OpenPlanr/commit/1c7b70a6d115f43389c3477d01aa8f895e505b25) Align generated rule templates and the spec-schema reference to **Opus 4.8** (was Opus 4.7). The cursor (`planr-pipeline.mdc.hbs`, `agents/specification-agent.md`) and codex (`_pipeline-section.md.hbs`) rule-generator templates, plus `docs/reference/spec-schema.md`, now render the current DEV-tier codegen model — matching the planr-pipeline plugin v0.10.0 bump to `claude-opus-4-8[1m]`.
+
+## 1.7.0
+
+### Minor Changes
+
+- [`2a97c04`](https://github.com/openplanr/OpenPlanr/commit/2a97c04042591e4195bb4b84a4ae3486812877ed) feat: artifact integrity + rules generator managed-block markers
+
+### Managed-block markers for `rules generate` (fixes AGENTS.md clobber bug)
+
+`planr rules generate --scope pipeline` no longer overwrites the entire AGENTS.md / CLAUDE.md. Generated content is now wrapped in `<!-- ##planr-pipeline:begin## -->` / `<!-- ##planr-pipeline:end## -->` HTML comment markers. On regeneration, only the content between markers is replaced — project headers, agile content, and hand-written sections are preserved. Same treatment for `--scope agile` via `<!-- ##planr-agile:begin## -->` markers.
+
+### Write-time artifact validation
+
+`updateArtifact()` now validates structural invariants before writing: frontmatter fences present, YAML parses, `id:` field unchanged, and checkbox IDs preserved. On violation, throws `ArtifactInvariantError` with the specific violation. This stops AI-driven corruption from `planr refine` / `planr revise` at the door — the file on disk is never poisoned by malformed AI output.
+
+### AI contract: structured deltas for `planr refine`
+
+`planr refine` now asks the AI for structured deltas (`frontmatterChanges` + `bodyChanges`) instead of a whole-file `improvedMarkdown` blob. Our code applies deltas deterministically — the AI never holds a pen on raw bytes. Legacy `improvedMarkdown` responses are validated and rejected if they break structural invariants.
+
+### Migration
+
+- First run of `planr rules generate` on an existing project wraps content in markers automatically (non-destructive).
+- `planr refine` change is transparent to users (AI contract is an implementation detail).
+- Files previously corrupted by refine must be manually repaired or restored via `git checkout`.
+
+## 1.6.0
+
+### Minor Changes
+
+- [`d56c9a7`](https://github.com/openplanr/OpenPlanr/commit/d56c9a73a68a302eb0bc10aaa6a00c72630fc3ef) feat(types): widen `TaskStatus` to include `'blocked'` for v0.8.0 plugin alignment
+
+The planr-pipeline v0.8.0 task schema enum is `['pending', 'in-progress', 'done', 'blocked']`. Prior CLI versions silently coerced `blocked` → `pending` via `asTaskStatus()`, dropping the R6-failure signal that the pipeline writes alongside `T-NNN-error-report.md`.
+
+Changes:
+
+- `TaskStatus` union now includes `'blocked'` (`src/models/types.ts`)
+- All four `asTaskStatus()` normalizers accept and preserve `'blocked'` (linear-pull, linear-push, scope-loaders)
+- `DEFAULT_LINEAR_STATE_TO_OP` adds `['blocked', 'blocked']` so a Linear "Blocked" workflow state pulls back into a blocked task file
+- `buildNameToStatusMap` accepts `'blocked'` from user `linear.statusMap` overrides
+- `aggregateTaskStatus()` adds top-precedence rule: any blocked child → blocked parent (escalation, not averaging)
+
+Migration: zero-friction. Tasks that don't carry `blocked` are unaffected. The CLI no longer demotes blocked back to pending on Linear pull.
+
+## 1.5.2
+
+### Patch Changes
+
+- [`1eec762`](https://github.com/openplanr/OpenPlanr/commit/1eec7627c6d95167644d88f884716a1537a1fb0f) Fix a leftover `OpenPlanr-pipeline-aware` phrase in the cursor master rule template that the v1.5.1 rename sed missed (mixed-case compound adjective). After upgrade, regenerated `.cursor/rules/planr-pipeline.mdc` files use `planr-pipeline-aware` consistently with the renamed plugin.
+
+No behavioural change. Run `planr rules generate --target cursor --scope pipeline` to refresh existing projects.
+
+## 1.5.1
+
+### Patch Changes
+
+- [`03aa928`](https://github.com/openplanr/OpenPlanr/commit/03aa9289be7e784c3cd5b904af7459f7ee185dfa) Plugin rename: `openplanr-pipeline` → `planr-pipeline`. Brand convergence on the `planr` CLI binary. The CLI's TypeScript API is unchanged — only generated artifact names + slash command identifiers.
+
+**What changes for users:**
+
+- Generated cursor rule filenames: `openplanr-pipeline.mdc` → `planr-pipeline.mdc` (also `-plan.mdc` and `-ship.mdc` variants)
+- Claude sibling reference card: `openplanr-pipeline.md` → `planr-pipeline.md`
+- Slash commands: `/openplanr-pipeline:plan` → `/planr-pipeline:plan` (same for `:ship`)
+
+**Migration:** re-run `planr rules generate` to pick up the new files. Legacy filenames trigger a one-line cleanup hint pointing at safe-to-delete paths — never auto-deleted.
+
+**Pairs with:** `planr-pipeline` Claude Code plugin v0.7.0 (renamed from `openplanr-pipeline` v0.6.0); `openplanr` skill v1.4.0; marketplace pin updated to v0.7.0.
+
+## 1.5.0
+
+### Minor Changes
+
+- [`b8e018c`](https://github.com/openplanr/OpenPlanr/commit/b8e018c895907bdb9bf69052d55552e3efec0229) Multi-runtime rules: extend `planr rules generate` with a `--scope` flag for cross-runtime pipeline support.
+
+`planr rules generate` now accepts `--scope <agile|pipeline|all>` (default: `agile` — preserves existing behaviour byte-for-byte). The new `pipeline` scope generates rule files that drive the openplanr-pipeline two-phase spec-driven flow on the chosen runtime, giving Cursor and Codex first-class parity with the Claude Code plugin.
+
+**Cursor (`--target cursor --scope pipeline`):**
+
+- `.cursor/rules/openplanr-pipeline.mdc` — master rule (mode detection, R1 human gate, runtime parity notes)
+- `.cursor/rules/openplanr-pipeline-plan.mdc` — PO Phase orchestration (Composer subagent dispatch)
+- `.cursor/rules/openplanr-pipeline-ship.mdc` — DEV Phase orchestration (parallel subagents, qa gate, snapshot, marker)
+- `.cursor/rules/agents/{db,designer,specification,frontend,backend,qa,devops,doc-gen}-agent.md` — 8 role bodies vendored verbatim from `openplanr-pipeline/agents/` (frontmatter stripped; Cursor uses different permission model)
+
+**Codex (`--target codex --scope pipeline`):**
+
+- `AGENTS.md` extended with a `## OpenPlanr Pipeline Orchestration` section. Roles modelled as personas (Codex doesn't have separate subagent processes); R1, R2, R5, R6, R8, R9 declared at prompt level with conformance-test enforcement.
+
+**Claude (`--target claude --scope pipeline`):**
+
+- `CLAUDE.md` gets a conditional `## OpenPlanr Pipeline (Path A)` block under `{{#if pipelineScope}}`
+- Sibling `openplanr-pipeline.md` reference card with install commands, slash command list, and cross-runtime pointer
+
+`--scope all` produces both agile and pipeline rules side-by-side.
+
+**Compatibility matrix and OpenPlanr Protocol v1.0.0** documented in `openplanr-pipeline/docs/protocol/` and `openplanr-pipeline/docs/compatibility-matrix.md` (pipeline plugin v0.6.0+).
+
+**`planr init` now auto-generates pipeline rules by default.** The init flow asks "Generate openplanr-pipeline rules?" with default `Yes` — meaning a single `planr init` produces a complete, ready-to-use cross-runtime project (Cursor + Codex pipeline rules pre-installed; Claude Code skill activates the same workflow via the plugin). Opt out with `planr init --no-pipeline-rules` to preserve the previous agile-only behaviour. This closes the cross-runtime DX gap so each tool (Cursor, Codex, Claude Code) is self-sufficient after a single command — no manual `planr rules generate --scope pipeline` step required for the common case.
+
+**Migration:** none. Existing projects can either re-run `planr init` (it auto-detects existing config and asks to overwrite) or run `planr rules generate --scope all` to add pipeline rules without touching config. `--scope agile` (the previous default for `planr rules generate`) keeps producing the existing 6 Cursor `.mdc` files, single CLAUDE.md, single AGENTS.md outputs unchanged.
+
+## 1.4.3
+
+### Patch Changes
+
+- [`e625a3b`](https://github.com/openplanr/OpenPlanr/commit/e625a3b69c331a45806fc3ff8197b0115f14b1f0) Four improvements that close real workflow gaps in `planr linear push`, `planr linear tasklist-sync`, and the per-type `update` commands.
+
+**Granular push scope (BL-012).** `planr linear push` adds `--no-cascade` and redefines `--push-parents` to be upward-attachment only.
+
+- `--no-cascade` on EPIC/FEAT pushes skips descendants (stories, tasklists, linked QT/BL). No-op for leaves.
+- `--push-parents` no longer drags in the parent's other children. Pushing `TASK-004 --push-parents` now creates EPIC + parent FEAT + this tasklist only — not the feature's sibling stories.
+
+**TASK status now propagates to Linear (BL-014).** `planr linear push` resolves a workflow stateId for the merged TaskList issue using an aggregation rule across all task files under the feature: all `done` → Linear Done, any `in-progress` → Linear In Progress, mix of done+pending → In Progress, all `pending` → Linear Todo. Closes the gap where `TASK-006 status: done` locally left Linear's TaskList in Backlog.
+
+**Bulk subtask completion (BL-015).** `planr task update`, `planr quick update`, and `planr update` add `--all-done` and `--all-pending` flags that set the frontmatter status AND flip every `N.M` task checkbox in the body in one operation. Replaces the manual `sed`-or-edit-each-box workflow when shipping a feature.
+
+**tasklist-sync no longer skips healthy issue UUIDs (BL-016).** `planr linear tasklist-sync` previously rejected every task file whose `linearIssueId` was a UUIDv4 — the entire population of healthy task files — because a shape-based pre-screen flagged them as "looks like a workflow state UUID." Linear issue ids and workflow-state ids are both UUIDv4 and indistinguishable by shape, so the pre-screen has been removed; the existing `isLikelyLinearIssueId` check still rejects truly malformed values like `ENG42`.
+
+Backward-compat note: scripts that relied on `--push-parents` cascading downward will see fewer entities pushed.
+
+## 1.4.2
+
+### Patch Changes
+
+- [`45f2714`](https://github.com/openplanr/OpenPlanr/commit/45f2714c45a8148f23de32ec10c6a07b04ae30cc) Spec-driven workflow polish: clearer errors, schema reference, readiness check.
+
+- **Friendlier `planr spec decompose` error** when AI is unavailable — surfaces two actionable paths (configure AI, or hand-author from the schema reference) instead of one terse line.
+- **`planr config show` now includes a "Spec-driven readiness" section** — at-a-glance view of whether `planr spec decompose` can run given the current AI config.
+- **`planr init --no-ai` prints a warning** listing the AI-dependent commands (`spec decompose`, `refine`, `backlog prioritize`) that will be unavailable, with a one-liner to re-enable later.
+- **Canonical schema reference at `docs/reference/spec-schema.md`** — single source of truth for spec / story / task frontmatter, body sections, lifecycle states, and the `.pipeline-shipped` marker. To be hosted at `openplanr.dev/docs/reference/spec-schema`.
+- Spec template footnote updated with concrete pipeline / CLI handoff routes.
+
+## 1.4.1
+
+### Patch Changes
+
+- [`2e36aee`](https://github.com/openplanr/OpenPlanr/commit/2e36aeec579dcac0e212eaabdce24a578f51f9c4) Fix `planr spec shape` UX — replace `$EDITOR`-opening prompts with single-line prompts.
+
+Previously, `planr spec shape <SPEC-id>` opened `$EDITOR` (vim by default for many users) for the Context, Business Rules, and Decomposition Notes questions. This was hostile UX — users unfamiliar with vim couldn't navigate, and a single accidental Enter on an empty buffer aborted the entire interactive flow.
+
+**v1.4.1 changes:**
+
+- **Question 1 (Context)** is now three single-line prompts: primary user, problem solved, expected outcome. Each is optional; provide what you can. The shape skill composes the Context section from your answers using markdown subheadings.
+- **Question 3 (Business Rules)** is now a single line. Hint guides the user to edit the spec markdown file directly for longer-form rules.
+- **Optional Decomposition Notes** is now a single line. Same guidance — edit file directly for longer prose.
+- Functional Requirements (Q2) and Acceptance Criteria (Q4) are unchanged — they were already comma-separated lists.
+
+Net effect: the entire shape flow now runs in the terminal with single-line prompts only. No `$EDITOR` open. No accidentally-empty-buffer aborts.
+
+For users who genuinely want long-form prose, the recommended path is: run `planr spec shape` for quick capture, then edit `.planr/specs/SPEC-NNN-{slug}/SPEC-NNN-{slug}.md` directly in your editor of choice afterward.
+
+Origin: surfaced by real-world testing where a user pressed Enter past the vim buffer without writing anything and lost the entire shape flow.
+
+## 1.4.0
+
+### Minor Changes
+
+- [`00e91df`](https://github.com/openplanr/OpenPlanr/commit/00e91dfc5020826bc9c180f057082daab4ebf14f) Add spec-driven planning mode — third planning posture alongside agile + QT, designed for humans planning _for_ AI coding agents.
+
+A new `planr spec` command namespace authors specs that decompose into User Stories and Tasks with the **same artifact contract as the [openplanr-pipeline](https://github.com/openplanr/openplanr-pipeline) Claude Code plugin** — file Create/Modify/Preserve lists, Type=UI|Tech, agent assignment, DoD with build/test commands. The two products share one schema; no conversion adapter ever.
+
+**Subcommands shipped:**
+
+- `planr spec init` — Activate spec-driven mode in the current project
+- `planr spec create [title]` — Create a self-contained `.planr/specs/SPEC-NNN-{slug}/` directory
+- `planr spec shape <id>` — Interactive 4-question SPEC authoring (Context, Functional Requirements, Business Rules, Acceptance Criteria)
+- `planr spec decompose <id>` — AI-driven generation of User Stories + Tasks; matches openplanr-pipeline schema; works with all 3 AI providers (Anthropic, OpenAI, Ollama). Flags: `--force`, `--no-code-context`, `--max-stories <n>`
+- `planr spec sync [id]` — Validate spec integrity (orphaned tasks, stories without tasks, missing `specId`, schema drift); auto-fixes safe issues; `--dry-run` reports without writing
+- `planr spec list` — List all specs with status + decomposition counts
+- `planr spec show <id>` — Print a spec + its US/Task tree
+- `planr spec status [id]` — Decomposition state across one or all specs
+- `planr spec destroy <id>` — `rm -rf` of a single self-contained spec directory
+- `planr spec attach-design <id> --files <png>...` — Attach UI mockups for the pipeline's designer-agent
+- `planr spec promote <id>` — Validate completeness, mark `ready-for-pipeline`, print the `/openplanr-pipeline:plan {slug}` handoff command
+
+**Directory layout (per spec, self-contained):**
+
+```
+.planr/specs/SPEC-NNN-{slug}/
+├── SPEC-NNN-{slug}.md         # the spec document
+├── design/                    # PNG mockups + design-spec.md (written by pipeline's designer-agent)
+├── stories/US-NNN-{slug}.md   # US-NNN scoped to this spec
+└── tasks/T-NNN-{slug}.md      # T-NNN scoped to this spec
+```
+
+**ID scoping:** US-NNN and T-NNN are scoped to their parent SPEC (not project-globally unique). Two specs can each have their own US-001. Disambiguate via path or via `specId` frontmatter.
+
+**Coexistence:** purely additive — agile (epic/feature/story/task) and QT modes work unchanged. Activate spec mode per project via `planr spec init`. Modes are independent; pick the posture that fits the work.
+
+**Decompose AI behavior:**
+
+- Always scans the project codebase via the existing `buildCodebaseContext()` so generated tasks reference real file paths matching the user's stack
+- Reads `input/tech/stack.md` (best-effort) for stack-specific hints
+- Detects `ui_files` in SPEC frontmatter to drive 1-vs-2 tasks per US (per openplanr-pipeline rule R2)
+- Refuses to overwrite an existing decomposition unless `--force` is passed
+- Status: pending|shaping → decomposing → decomposed
+
+**Pipeline integration:** When this CLI marks a spec `ready-for-pipeline`, the openplanr-pipeline Claude Code plugin (v0.3.0+) reads `.planr/specs/SPEC-NNN-{slug}/` directly — no conversion. See `docs/proposals/spec-driven-mode.md` for the full design proposal and BL-011 for the original strategic feedback.
+
+## 1.3.0
+
+### Minor Changes
+
+- [`61dc183`](https://github.com/openplanr/OpenPlanr/commit/61dc183e2a1ef7397682b6d7ba871c37c82c2c7a) **`planr linear`** — full Linear.app integration for OpenPlanr (EPIC-004).
+
+### Subcommands
+
+- `planr linear init` — validate a Linear PAT, pick a team, save settings.
+- `planr linear push <artifactId>` — create/update Linear entities at any scope:
+  - `EPIC-XXX` → project + features + stories + tasklists
+  - `FEAT-XXX` → feature + its stories + its tasklist
+  - `US-XXX` → one story sub-issue
+  - `TASK-XXX` → one tasklist sub-issue
+  - `QT-XXX` → quick task in the standalone project
+  - `BL-XXX` → backlog item (auto-labeled) in the standalone project
+- `planr linear sync` — pull workflow status + bidirectional task checkboxes.
+- `planr linear tasklist-sync` — sync TASK checkbox lines with Linear issue bodies.
+- `planr linear status` — local mapping table (no API calls).
+
+### Flags on `push`
+
+`--dry-run`, `--update-only`, `--push-parents`, `--as <strategy>`.
+
+### Epic mapping strategies (chosen once, stored in `linearMappingStrategy`)
+
+- `project` (default) — Epic = Linear Project, one-to-one.
+- `milestone-of:<projectId>` — Epic becomes a `ProjectMilestone` in an existing project; descendants carry `projectMilestoneId`.
+- `label-on:<projectId>` — Epic becomes a team-scoped label; descendants carry `labelIds` (merged with user-added labels, never stomped).
+
+First-time push prompts interactively. CI consumers use `--as` or `linear.defaultEpicStrategy`.
+
+### Parent-chain pre-flight
+
+Granular pushes (`FEAT-/US-/TASK-`) refuse to run when the parent chain is not yet in Linear — unless `--push-parents` is set, which cascades up. Unsupported prefixes (`ADR-/SPRINT-/checklist-`) error with a pointer to the parent epic.
+
+### Standalone project for `QT-` / `BL-`
+
+Quick tasks and backlog items push as top-level issues in a user-chosen Linear project (`linear.standaloneProjectId`, set once via an interactive first-push prompt). Backlog items auto-apply a team-scoped `backlog` label for filtering.
+
+### Security & reliability
+
+- Linear IDs validated before every API call — accepts UUID or `ENG-42` identifier; corrupted frontmatter falls through to create instead of 404-ing.
+- Frontmatter writer preserves regex-special sequences (`$1`, `$&`, `$$`) literally — Linear values can contain them.
+- SDK error fallback sanitizes raw GraphQL bodies; known error types keep their user-friendly guidance.
+- Rate-limit retries honor Linear's `Retry-After` (never retry sooner than the server asked, never faster than our exponential backoff).
+- Non-interactive conflict decisions audited to `.planr/reports/`.
+- Three-way checkbox merge warns when a baseline looks corrupted.
+- PATs stored via keychain-first credentials service, never in `config.json`.
+
+### Bidirectional status sync with three-way merge (fixes silent data loss)
+
+`planr linear sync` now reconciles workflow status in **both directions** via a three-way merge:
+
+- **Local changed, Linear unchanged** → pushes local to Linear (fixes the data-loss bug where `planr quick update --status done` followed by `planr linear sync` silently reverted local back to Linear's stale state).
+- **Linear changed, local unchanged** → pulls Linear to local (existing behavior, preserved).
+- **Both changed** → conflict resolved per `--on-conflict prompt|local|linear`. Interactive runs prompt per artifact; CI/non-interactive runs auto-resolve to `linear` and log the decision to `.planr/reports/linear-sync-conflicts-<date>.md`.
+
+Baseline is stored per-artifact in new frontmatter fields `linearStatusReconciled` and `linearStatusSyncedAt`, written on every successful sync. `planr quick update --status` and `planr backlog update --status` automatically clear `linearStatusReconciled` so the next sync recognizes the local change and pushes it up.
+
+`--on-conflict` now applies to both status and checkbox conflicts (previously checkbox-only). Applies to FEAT / US / QT / BL. TASK stays deferred (aggregate issue, needs its own aggregation rules).
+
+### Status sync now covers QT + BL (zero-config)
+
+`planr linear push QT-XXX` and `planr linear push BL-XXX` now write local status to Linear's workflow state. `planr linear sync` pulls state changes back into QT and BL frontmatter alongside features and stories.
+
+- **Zero-config:** push auto-derives the status→stateId map from Linear's canonical state types (`backlog` / `unstarted` / `started` / `completed` / `canceled`) on every run. `linear.pushStateIds` is now an optional override, not a requirement.
+- Quick tasks use the task vocabulary (`pending` / `in-progress` / `done`), plus transparent aliases for Linear-native wording (`completed` / `cancelled` / `canceled` / `todo`).
+- Backlog items use their own vocabulary (`open` / `closed` / `promoted`). Pull is asymmetric by design: any Linear "in flight" state maps to `open`, `Done`/`Cancelled` maps to `closed`, and local `promoted` is never overwritten (it implies a target pointer Linear can't know about).
+- TASK status sync stays on the TODO list. One Linear TaskList issue aggregates many task files, so a 1:1 status mapping doesn't apply; use `planr linear tasklist-sync` for per-checkbox state.
+
+**Fix:** Linear's API rejects `stateId: null` on update (`InvalidInput`). All push paths — feature, story, QT, BL — now omit the `stateId` field entirely when unmapped instead of sending an explicit null, so pushes without any state configuration continue to succeed.
+
+### `planr revise` — unchanged-content short-circuit
+
+Revise now detects when the agent returns content that is effectively identical to the original (byte-exact, or differs only in trailing whitespace that LLM markdown serializers routinely strip). Behavior in that case:
+
+- No file write, no backup sidecar produced, no confirm prompt.
+- New audit outcome `unchanged-by-agent` (distinct from `skipped-by-agent` / `flagged`).
+- UI renders "(no changes — agent's revised output matches the current file; nothing to apply)" in place of an empty diff block.
+
+Prevents the confusing `Outcome: applied` report when the only on-disk delta was a trailing newline strip.
+
+### `planr linear status` — full URLs, no truncation
+
+Reordered the table so the URL column is last and never truncated. Clickable URLs are the primary value of the table; the previous 28-char ellipsis made them useless for copy-paste.
+
+### Estimate sync for FEAT / US / QT / BL
+
+`planr linear push` now writes local `estimatedPoints` (from `planr estimate --save`, or hand-edited `storyPoints`) to Linear's native Issue estimation field, snapped to the team's configured scale:
+
+- **Fibonacci** — snap to `{0, 1, 2, 3, 5, 8, 13, 21}` (e.g. `4 → 5`, `7 → 8`).
+- **Linear** — snap to `{0, 1, 2, 3, 4, 5}`.
+- **Exponential** — snap to `{0, 1, 2, 4, 8, 16}`.
+- **tShirt** — skipped with one-per-run warning (no reliable numeric → XS/S/M/L/XL mapping).
+- **notUsed** — skipped silently.
+
+Zero-config: the team's `issueEstimationType` is auto-detected per push run (one extra API round-trip, cached). TASK is deferred — one Linear TaskList issue aggregates multiple task files, so 1:1 estimate mapping doesn't apply.
+
+### Story body fixes
+
+- **Empty role/goal/benefit no longer renders `As a \*\***, I want \***\* so that \*\***.`\*\* Suppresses the "As a" sentence entirely when any of the three fields is blank (or whitespace-only).
+- **Gherkin scenarios now push to Linear.** Stories following the OpenPlanr convention store acceptance criteria as Gherkin in a sibling `<storyId>-gherkin.feature` file. Before this fix the push path never loaded the `.feature` content and Linear stories rendered empty for convention-following teams.
+- **Epic project description trims whitespace-only fields** — no more empty `**Risks**` headers.
+
+### Linear label case + workspace-scope fix
+
+`ensureIssueLabel` lookup is now **case-insensitive and workspace-wide** (matching Linear's own uniqueness rule). Previously a workspace with a `Feature` label blocked creation of `feature` with an `InvalidInput: Label already exists` error. Push now adopts the existing cross-team label instead of failing.
+
+### Revise — next-step guidance + rejected-proposal preservation
+
+- Flagged outcomes now print actionable next steps (read the audit log, hand-edit, re-run with `--scope-to prose`, re-run with `--no-code-context`) instead of leaving users in a dead end.
+- Demoted `revise → flag` decisions preserve the agent's rejected rewrite in the audit log as a `REJECTED by verifier` diff so users can inspect and hand-apply the parts that make sense. The file is still not written (action remains `flag`); the markdown is kept for audit purposes only.
+
+### BL → QT promote is now AI-driven
+
+`planr backlog promote BL-XXX --quick` feeds the full BL markdown body (description, acceptance criteria, notes, threat models) through the same AI pipeline used by `planr quick create`, producing a realistic task breakdown instead of a single checkbox that restates the title. The new QT carries `sourceBacklog: "BL-XXX"` as provenance and inherits `epicId` from the BL (or an explicit `--epic` override) so `planr linear push EPIC-XXX` cascades to it. Use `--manual` to opt out of AI and keep the legacy single-task behavior.
+
+### Config additions
+
+```jsonc
+{
+  "linear": {
+    "teamId": "UUID",
+    "teamKey": "ENG",
+    "defaultProjectLead": "UUID",
+    "pushStateIds": {
+      "pending": "UUID",
+      "in-progress": "UUID",
+      "done": "UUID"
+    },
+    "statusMap": { "In Review": "in-progress" },
+    "standaloneProjectId": "UUID",
+    "standaloneProjectName": "Planr",
+    "defaultEpicStrategy": "project"
+  }
+}
+```
+
+## 1.2.8
+
+### Patch Changes
+
+- [`2d9c113`](https://github.com/openplanr/OpenPlanr/commit/2d9c113627c0eae69611af7ee2adbde366c2799f) Add `planr revise` — agent-driven alignment of planning artifacts with codebase reality
+
+New command complementing `planr refine` (prose polish) with a focus on _factual_ alignment:
+
+- `planr revise <ID>` — revise a single artifact (epic / feature / story / task)
+- `planr revise <ID> --cascade` — top-down revision of an artifact and its descendants (epic → features → stories → tasks); children see the _revised_ parent in their context
+- `planr revise --all` — revise every epic in the project, with a content-hash cache that skips unchanged artifacts
+- `--dry-run`, `--yes`, `--allow-dirty`, `--scope-to prose|references|paths|all`, `--no-code-context`, `--no-sibling-context`, `--audit-format md|json`, `--max-writes-per-run`
+
+Four-layer safety pipeline (every run):
+
+1. **Clean-tree gate** — refuses to run on a dirty git working tree (override with `--allow-dirty`)
+2. **Evidence verification** — every AI citation uses a typed kind (`file_exists`, `file_absent`, `grep_match`, `sibling_artifact`, `source_quote`, `pattern_rule`); unverifiable citations are dropped. When a majority of evidence fails to verify, the decision is demoted from `revise` to `flag` so a human reviews instead of silently applying
+3. **Diff preview + confirmation** — per-artifact menu: `[a]pply / [s]kip / [e]dit rationale / [d]iff again / [q]uit`; `--yes` still requires typed "YES" at start in an interactive TTY, skipped in non-TTY (CI) environments
+4. **Post-flight graph-integrity check + git rollback** — after writes, `syncParentChildLinks` runs; if any cross-reference broke, affected artifact paths are restored via `git checkout`. This is the only v1 mechanism allowed to use the word "rollback"; atomic writes are called atomicity
+
+Template-conformance guardrail:
+
+- Revise is taught the canonical `## Section` set for each artifact type (from the Handlebars templates) and instructed to flag rather than add sections outside it. Prevents task-level conventions like `## Relevant Files` from leaking into epics
+- Existing user-maintained custom sections are preserved byte-for-byte
+
+Other safety properties:
+
+- **Atomic writes** with sidecar backups (`.planr/reports/revise-<scope>-<date>/backup/`) — no partial files ever on disk
+- **Facts win from code, plan wins on intent** — concrete paths and symbols are rewritten to match the repo; what the feature is _supposed to do_ is never rewritten (intent conflicts surface as `flag` with ambiguous entries)
+- **Graceful mid-cascade interrupt** — Ctrl+C and `[q]uit` let any in-flight atomic write complete, stop cleanly, and flush the audit log immediately; already-applied artifacts stay applied
+- **SIGINT closes the audit log cleanly** with an `interrupted: sigint` footer, so Ctrl+C at the confirmation prompt doesn't leave a half-written log
+
+Every run emits a Markdown or JSON audit log under `.planr/reports/` capturing applied / skipped / flagged / failed artifacts with rationale, evidence, ambiguities, and unified diffs — dry-run included.
+
+After a successful apply, revise prints:
+
+```
+git commit -am "chore(plan): revise <SCOPE> against codebase"
+```
+
+See the [README section on `planr revise`](https://github.com/openplanr/OpenPlanr/blob/main/README.md#planr-revise--align-planning-with-reality) for workflow examples.
+
+## 1.2.7
+
+### Patch Changes
+
+- [`57d07b3`](https://github.com/openplanr/OpenPlanr/commit/57d07b324cd34bc8461d09ae3fc2225dc5da610f) Add stakeholder reporting & PM intelligence layer
+
+New commands:
+
+- `planr report <type>` — generate `sprint`, `weekly`, `executive`, `standup`, `retro`, or `release` reports from `.planr/` artifacts and (optionally) recent GitHub commits/PRs, written as Markdown + HTML under `.planr/reports/`
+- `planr report-linter [file]` — validate stakeholder markdown against configurable rules (vague language, evidence density, required sections per report type) with coaching hints
+- `planr context` — emit the report context pack (artifacts + sprint state + GitHub signals + flat evidence index) as JSON for piping
+- `planr voice standup` — convert a transcript file or stdin into a structured Yesterday / Today / Blockers standup, with optional `--lint`, `--edit`, `--reload-file`, and `--append-story`
+- `planr story standup --story <ID>` — append linted standup notes onto an existing user story
+
+Reporting features:
+
+- `--lint` and `--strict-evidence` quality gates so vague or unsupported claims do not ship
+- `--push slack` via [Incoming Webhooks](https://api.slack.com/messaging/webhooks) (`distribution.slackWebhookUrl` in `.planr/config.json`); `--dry-run` works without a webhook configured
+- `--push github` archives the report as a `planr:report` GitHub issue via the local `gh` CLI
+- Optional org branding and extra sections via the `reports` block in config; optional rule overrides via the `reportLinter` block
+
+Out of scope for this release (deferred):
+
+- Bundled PDF rendering (`--format pdf` exits with a clear "not in this build" message)
+- SMTP email delivery (the email path is a documented stub)
+- Live microphone capture and bundled speech-to-text — pair `planr voice standup` with any STT or OS dictation tool
+- Per-segment audio replay, Slack OAuth / multi-channel routing, native git-tree report commits, persistent cross-session coaching history
+
+See [docs/EPIC-PM-REPORTING-LAYER.md](https://github.com/openplanr/OpenPlanr/blob/main/docs/EPIC-PM-REPORTING-LAYER.md) for the design and shipped-vs-deferred matrix.
+
+## 1.2.6
+
+### Patch Changes
+
+- [`4cf5bcc`](https://github.com/openplanr/OpenPlanr/commit/4cf5bcc5e6e4f56bb0d59cda9cb9ba7f57115277) Replace gray-matter with yaml package to eliminate eval() vulnerability
+
+- Remove gray-matter dependency (+ 6 transitive deps including js-yaml with eval)
+- Add yaml package (zero deps, YAML 1.2 spec, no eval, maintained by YAML spec editors)
+- Custom frontmatter parse/stringify in ~15 lines with robust regex handling
+
+## 1.2.5
+
+### Patch Changes
+
+- [`97e34be`](https://github.com/openplanr/OpenPlanr/commit/97e34bee794585c50d6ba774d1ba0b586a130030) Add artifact update commands and GitHub issue type auto-assignment
+
+- Add `planr update <ids...>` top-level command with batch support, status validation, and `--force` override
+- Add `update` subcommand to all artifact types: epic, feature, story, task, quick, backlog
+- Supported fields: `--status` (all types), `--owner` (epic/feature), `--priority` (backlog)
+- Auto-set GitHub issue types (Task, Feature) via GraphQL when pushing with `planr github push`
+- Extract shared `updateArtifactFields()` using regex-based replacement to preserve file formatting
+- Harden environment variable access with explicit allowlist in credentials-service
+
+## 1.2.4
+
+### Patch Changes
+
+- [`64a0f80`](https://github.com/openplanr/OpenPlanr/commit/64a0f80fda6d6d44faff957d7064a55d6833682c) Code quality and performance improvements
+
+- Faster sprint and sync commands via parallelized artifact loading
+- Consistent error messages across all AI-powered commands
+- Shared formatting utilities to reduce internal code duplication
+- JSDoc documentation added to all core service functions
+
+## 1.2.3
+
+### Patch Changes
+
+- [`5551aea`](https://github.com/openplanr/OpenPlanr/commit/5551aea8113ae17af67306219c9eb22bd5405667) Add prompt injection protection with input boundary delimiters and file size validation for --file arguments
+
+## 1.2.2
+
+- [`45836f9`](https://github.com/openplanr/OpenPlanr/commit/45836f99ad88605ba4aac5fab4f318b20badf5b0) Reduce AI over-engineering in plan generation with scope discipline rules, count guidance per artifact level, and anti-enumeration batching ([#62](https://github.com/openplanr/OpenPlanr/pull/62))
+
+## 1.2.1
+
+- [`696da73`](https://github.com/openplanr/OpenPlanr/commit/696da735d7cdb88c3d11022233d2b17bb274ca02) Fix project root resolution for monorepos — planr now walks up the directory tree to find `.planr/config.json`, so commands work from any subdirectory ([#55](https://github.com/openplanr/OpenPlanr/pull/55))
+
+## 1.2.0
+
+- [`3f47e3c`](https://github.com/openplanr/OpenPlanr/commit/3f47e3c7524cd54827cc4e63830de4bacb9f2df6) Add agent-friendly non-interactive mode and API key UX improvements
+  - Add `--yes`/`-y` flag for fully unattended planning workflows (Claude Code, Cursor, Codex)
+  - Auto-detect non-interactive terminals via TTY detection
+  - All prompts return sensible defaults when non-interactive
+  - Add `planr config remove-key` command to delete stored API keys
+  - Show clear multi-line guidance when API key is not configured
+  - Detect existing API keys (env var, OS keychain, encrypted file) during init
+  - Replace magic numbers with named CHECKLIST constants
+  - Fix TOCTOU race condition in checklist reads
+
+All notable changes to this project will be documented in this file.
+
+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).
+
+## [1.1.0] - 2026-04-06
+
+### Added
+
+- **`.planr/` directory** — all config and planning artifacts now live under `.planr/` instead of polluting the project root with `planr.config.json` and `docs/agile/`. IDE-required files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`) remain at their mandated locations
+- **Auto-generate AI agent rules on `planr init`** — creates `CLAUDE.md`, `AGENTS.md`, and `.cursor/rules/` immediately so users get working agent rules without a separate `planr rules generate` step
+- **`planr checklist toggle 1 3 5`** — direct argument support alongside interactive mode, with validation of item indices
+- **Auto-check checklist items** — `checkItem()` automatically marks checklist items as done when relevant commands complete (epic→1, feature→2, story→3, task→10)
+
+### Changed
+
+- **Config path** — `planr.config.json` → `.planr/config.json`
+- **Artifact root** — `docs/agile/` → `.planr/`
+- **Cursor rule templates** — renamed from numeric prefixes (`2000-agile-checklist.mdc`) to clean descriptive names (`agile-checklist.mdc`) to avoid colliding with user's existing rule files
+
+### Fixed
+
+- **Broken checklist paths** — `{{agilePath}}` template variable was missing from `createChecklist()` template data, producing broken file references
+- **Checklist toggle reporting** — direct-args mode now validates indices against actual checklist items and reports accurate update counts
+
+### Breaking Changes
+
+- Existing v1.0.x projects need to re-run `planr init`
+
+## [1.0.0] - 2026-04-05
+
+### Added
+
+- **`planr backlog`** — capture, prioritize, and promote work items from a lightweight backlog
+  - `planr backlog add` — capture ideas with priority and tags without breaking your flow
+  - `planr backlog list` — filter by tag, priority, or status; sorted by priority
+  - `planr backlog prioritize` — AI scores items by impact/effort and reorders them
+  - `planr backlog promote` — promote to quick task (`--quick`) or story (`--story --feature`)
+  - `planr backlog close` — archive completed or irrelevant items
+- **`planr sprint`** — time-boxed iterations with velocity tracking
+  - `planr sprint create` — create a sprint with name and duration (1–4 weeks); enforces one-active-at-a-time
+  - `planr sprint add` — assign tasks manually or with `--auto` AI selection based on priority and velocity
+  - `planr sprint status` — progress dashboard with per-task completion, progress bars, and days remaining
+  - `planr sprint close` — archive sprint, list incomplete tasks, optional retrospective
+  - `planr sprint list` — all sprints with status badges and task counts
+  - `planr sprint history` — velocity chart with bar visualization across closed sprints
+- **`planr template`** — reusable task templates for common development workflows
+  - `planr template list` — list built-in and custom templates with task counts
+  - `planr template show` — preview template contents and variables
+  - `planr template use` — generate task list from a template with variable substitution
+  - `planr template save` — save an existing task list as a reusable custom template
+  - `planr template delete` — remove a custom template
+- **5 built-in task templates** — `rest-endpoint`, `react-component`, `database-migration`, `api-integration`, `auth-flow`
+- **User-defined AI rules** — `.planr/rules.md` injected into AI prompts as mandatory project rules
+- **Auto-extracted pattern rules** — 5 heuristic detectors (generic CRUD, command registration, central types, ID generation, template rendering) produce explicit rules from architecture files
+- **Post-generation validation** — warns about modify-on-missing, create-on-existing, dependency gaps, and unknown directories before user accepts AI output
+- **Dependency chain detection** — import-based file dependency hints injected into AI context
+- **`display` utility** — 13 methods for formatted user-facing output (tables, progress bars, key-value pairs, status badges)
+- **`ArtifactFrontmatter` type** — shared typed interface for artifact frontmatter across all parsers
+- **Shared task-creation helpers** — extracted `buildTaskItems`, `displayTaskPreview`, `displayValidationWarnings`, and related helpers into reusable module
+- **ESM `exports` field** — `package.json` now declares explicit ESM entry point
+- **Dynamic CLI version** — `planr --version` reads version from `package.json` at runtime instead of hardcoding
+
+### Changed
+
+- **Version** — bumped to 1.0.0
+- **Package description** — updated to reflect full planning platform: backlog, sprints, task templates, estimation, GitHub sync, and AI agent rules
+- **README** — complete rewrite with expanded feature list, backlog/sprint/template quick start, and organized command tables
+- **CLI.md** — added backlog, sprint, template, and quick task command sections; updated ID convention table, config example, workflow diagram
+- **`planr status`** — now shows backlog items with priority badges and active sprint with days remaining
+- **`planr search`** — now searches backlog and sprint artifacts
+- **Codebase context builder** — dynamic `src/` subdirectory discovery instead of hardcoded directory list; pattern rules and dependency hints injected into AI prompts
+- **Rules templates rewritten** — Cursor, Claude Code, and Codex templates replaced with 4-step context-gathering protocol (read task → walk parent chain → read ADRs → scan codebase)
+- **Sprint task entries** — now include task title and relative file link (`- [ ] **TASK-001** title — [view](...)`)
+- **Sprint auto-select** — sends subtask counts and parent feature context to AI for smarter velocity-aware selection
+- **Bare catch blocks eliminated** — 39 bare `catch {}` blocks converted to `catch (err) { logger.debug(..., err) }` for `--verbose` debuggability
+- **Strict Biome rules** — enabled `noExplicitAny`, `noNonNullAssertion`, `noConsole` as errors
+- **`@anthropic-ai/sdk`** — bumped from 0.80.0 to 0.81.0
+
+### Removed
+
+- **`planr task implement` and `planr quick implement`** — coding agents (Claude Code, Cursor, Codex) handle implementation directly via generated rules
+- **`planr task fix` and `planr quick fix`** — replaced by iterative agent workflows
+- **8 agent adapter files** (~1,150 lines) — `agent-factory`, `claude-agent`, `codex-agent`, `cursor-agent`, `implementation-bridge`, `progress`, `prompt-composer`, `types`
+- **Orphaned retry utilities** — dead `MAX_RETRIES`, `isRetryableError`, `sleep` removed after agent deletion
+- **Duplicate `CodingAgentName` type** — consolidated to single definition in `models/types.ts`
+
+### Fixed
+
+- **Hardcoded source inventory directories** — replaced 7-directory list with dynamic `readdir` discovery that expands into leaf directories
+- **Source inventory listing directories as files** — uses `readdir` with `withFileTypes` and `.isFile()` filter
+- **`countInventoryMatches` counting lines** — now parses comma-separated file names per inventory line
+- **Dependency chain warning wording** — "modified but" changed to "referenced but" for accuracy
+- **`displayValidationWarnings` loose typing** — `action?: string` replaced with `action: 'modify' | 'create'`
+- **`--file` flag error handling** — stack trace on bad file path replaced with user-friendly error message in quick.ts and epic.ts
+- **Rules reader empty vs missing** — `!content` replaced with explicit `content === null` check
+- **Slugify `ENAMETOOLONG` crash** — filenames truncated at 80 chars with word-boundary trimming
+- **Backlog title triplication** — title no longer repeated three times in generated backlog items
+- **Task parser bold ID regex** — fixed regex that caused empty template saves when IDs were bold-formatted
+- **Sprint "untitled" filename** — sprint creation now uses sprint name for slug instead of falling back to "untitled"
+- **Plan summary overcounting** — reports only artifacts created in current run; task generation failures no longer miscounted
+- **`truncateTitle` empty input** — guards against empty description producing empty artifact titles
+- **`progressBar` percent clamping** — clamps to [0,100] to prevent `String.repeat()` with negative count
+- **`logger.debug` Error formatting** — formats Error instances with stack traces instead of `[object Object]`
+- **Safer Map access patterns** — guarded `Map.get()` returns in sync and dependency-chains to prevent silent no-ops
+
+### Developer Experience
+
+- **47 new tests** — display utility (22), task-creation helpers (21), E2E smoke (4), edge cases
+- **Coverage thresholds raised** — from 3% to 14% (lines, functions, branches, statements)
+- **`display.*` / `logger.*` separation** — formatted user-facing output vs operational messages
+
+## [0.9.0] - 2026-04-01
+
+### Added
+
+- **`planr github push`** — push planning artifacts to GitHub Issues. Supports single artifact (`planr github push EPIC-001`), all artifacts under an epic (`--epic EPIC-001`), or everything (`--all`). Creates labeled issues with type-aware formatting, metadata tables, and collapsible artifact sources. Stores the GitHub issue number in artifact frontmatter for bi-directional linking
+- **`planr github sync`** — bi-directional status sync between local artifacts and GitHub Issues. Supports `--direction pull` (GitHub→local), `push` (local→GitHub), or `both` (interactive conflict resolution). Detects open/closed state changes and maps them to artifact status fields
+- **`planr github status`** — show sync status of all linked artifacts (local status vs GitHub issue state)
+- **`planr export`** — generate consolidated planning reports in markdown (`--format markdown`), JSON (`--format json`), or HTML (`--format html`). Supports epic scoping (`--scope EPIC-001`) and custom output path (`--output ./reports`). HTML reports are self-contained with collapsible sections, status badges, and inline CSS
+- **`planr epic create --file <path>`** — read epic description from a file (e.g., a PRD or requirements document) instead of single-line input. Supports multi-line documents of any size
+- **Type-aware GitHub issue formatting** — different body builders for task, epic, feature, and story artifacts with metadata tables, section reordering, and collapsible details
+- **Temp file body delivery** — uses `--body-file` for GitHub issue creation/update to avoid OS argument length limits on large artifacts
+- **Graceful deleted issue handling** — when a linked GitHub issue has been deleted, falls back to creating a new one instead of failing
+- **HTML export template** — self-contained Handlebars template with collapsible `<details>` sections, color-coded status badges, and full hierarchy rendering
+
+### Changed
+
+- **Epic prompt framing** — `buildEpicPrompt()` detects detailed input (>5 lines) and uses document extraction framing instead of "brief description" framing, so AI faithfully processes large PRDs
+- **Epic system prompt** — updated to explicitly handle detailed PRD input: "extract and incorporate ALL sections — do not summarize or ignore content"
+- **Epic token budget** — increased from 4096 to 8192 to support richer output from detailed PRD input
+
+## [0.8.0] - 2026-03-31
+
+### Added
+
+- **`planr estimate <id>`** — AI-powered effort estimation for any artifact (task, story, feature, epic, quick). Returns story points (Fibonacci 1-21), estimated hours, complexity, risk factors, and reasoning
+- **`planr estimate --epic <id>`** — Estimates all tasks under an epic and produces a rollup table with total points and hours
+- **`planr estimate --calibrate`** — Accuracy report from past estimates on completed artifacts
+- **`planr estimate --save`** — Persists estimate to artifact frontmatter (`estimatedPoints`, `estimatedHours`, `complexity`) and appends a full `## Estimate` section to the artifact body
+- **Interactive estimate prompt** — After displaying results, prompts to save, re-estimate, or discard (single artifact) or save all / discard all (epic rollup)
+- **`planr search <query>`** — Full-text search across all artifact types with highlighted snippets and 1 line of context
+- **`planr search --type <type>`** — Filter search by artifact type (epic, feature, story, task, quick, adr)
+- **`planr search --status <status>`** — Filter search results by artifact status
+- **`docs/agile/ESTIMATION.md`** — Estimation rubric generated by `planr init` with the full Fibonacci scale, complexity levels, risk categories, and team calibration guidance
+
+### Fixed
+
+- **Estimate save preserves frontmatter formatting** — Injects estimate fields directly into raw YAML without re-serializing through gray-matter, so original quoting and structure is preserved
+- **Legacy `estimatedEffort` field cleanup** — Free-text `estimatedEffort` fields added by AI during task generation are removed when saving a structured estimate
+
+### Changed
+
+- **Estimation AI prompt** — Embeds the full story point rubric (Fibonacci scale definitions, complexity levels, risk categories) for consistent and calibrated scoring across all artifacts
+
+## [0.7.0] - 2026-03-31
+
+### Added
+
+- **`planr quick`** — standalone task lists without the full agile hierarchy (Epic → Feature → Story → Task). Ideal for prototyping, bug fixes, hackathons, or any work that doesn't need agile ceremony
+- **`planr quick create`** — AI generates a structured task list from a one-line description, with codebase-aware context and relevant file detection
+- **`planr quick --manual`** — interactive task entry without AI
+- **`planr quick list`** — list all quick task lists
+- **`planr quick promote`** — graduate a quick task into the agile hierarchy by attaching to a story or feature
+- **Auto-mark subtasks as done** — after a coding agent completes successfully, implemented subtask checkboxes are automatically checked off in the task markdown
+- **Quick tasks in `planr status`** — standalone quick tasks shown in their own section with completion metrics
+
+### Fixed
+
+- **Claude retry for stdout API errors** — "API Error: 400 due to tool use concurrency" was emitted via stdout (stream-json) rather than stderr, so the retry logic never caught it. Now checks both streams for retryable errors
+
+### Type System
+
+- Added `'quick'` to `ArtifactType` union
+- Made `TaskList.storyId` optional (quick tasks have no parent story)
+- Added `QT` prefix to ID system and `quick/` directory to artifact mapping
+
+## [0.6.0] - 2026-03-29
+
+### Added
+
+- **Error context helper** — truncates large build logs for clearer failure output
+
+### Fixed
+
+- **Agent hangs on large prompts** — implementation prompt is delivered via temp file + stdin pipe instead of a giant CLI argument (avoids OS argv limits and interactive “wait forever” behavior)
+- **Stream backpressure** — prompt delivery uses `createReadStream` → `stdin` pipe instead of buffered `stdin.write`
+- **Codex sandbox** — `--full-auto` and `--json` so Codex can write files and emit structured events (matches Claude-style progress output)
+- **Claude stderr** — retryable 400/429/5xx errors detected while still showing output in real time
+
+### Changed
+
+- **Agent stdout/stderr** — `stdio: inherit` for live agent output where applicable
+- **Safety** — system prompt guidance to reduce destructive cross-project commands
+
+### Developer Experience
+
+- **Linting and formatting** — ESLint and Prettier replaced with [Biome](https://biomejs.dev/) (`biome check` / `biome format`)
+
+## [0.5.0] - 2026-03-28
+
+### Added
+
+- **Secure credential storage** — API keys are now stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) via `@napi-rs/keyring`, with AES-256-GCM encrypted file fallback for environments without a keychain (CI, Docker, SSH)
+- **Automatic credential migration** — existing plaintext `~/.planr/credentials.json` keys are migrated to the secure backend on first access, then the plaintext file is deleted
+- **Credential source display** — `planr config show` now shows where the API key is stored: `(OS keychain)`, `(encrypted file)`, or `(env: ANTHROPIC_API_KEY)`
+- **Per-command token budgets** — each command uses a tuned `maxTokens` limit (epic: 4K, feature/story/refine: 8K, task: 16K, task --feature: 32K) instead of a one-size-fits-all default
+- **Definitive truncation detection** — uses `stop_reason` (Anthropic) / `finish_reason` (OpenAI) to detect truncated responses instead of heuristic token thresholds
+- **8 new truncation unit tests** covering skip-retry, per-attempt token reporting, and streaming truncation
+
+### Changed
+
+- **`planr config set-key`** now shows the storage backend: `"saved to OS keychain"` or `"saved to encrypted file"`
+- **AI service refactored** — `generateJSON` and `generateStreamingJSON` now share a common `generateCore()` function, eliminating duplicated validation/retry/truncation logic
+- **GitHub Actions** updated to v6 (checkout, setup-node) and v7 (upload-artifact) with Node.js 24
+
+### Fixed
+
+- **Task generation from features failing** — `planr task create --feature` was truncating AI responses at 4,096 tokens, producing invalid JSON. Now uses 32K budget
+- **Spinner not stopping on API errors** — spinner animation no longer mixes with error messages when the AI provider throws
+- **Spinner showing ✓ before validation** — `succeed()` now only fires after successful parse/validation, not before
+- **Truncation error over-reporting tokens** — error messages now show per-attempt output tokens instead of cumulative totals
+- **Keychain write failures crashing** — `saveCredential` now catches keychain errors and falls back to encrypted file
+- **Migration flag set before completion** — `migrateCredentials` now resets the flag on failure so it retries next invocation
+- **`resolveApiKeySource` skipping migration** — `config show` now properly triggers legacy credential migration
+
+### Security
+
+- API keys no longer stored in plaintext on disk
+- Encrypted file uses AES-256-GCM with machine-derived key (hostname + username + per-installation salt via scrypt)
+- File permissions set to `0o600` on all credential files
+
+### Developer Experience
+
+- Test coverage: 261 → 269 tests across 23 test files
+- Added `tests/unit/ai-service-truncation.test.ts` (8 tests)
+- Added `tests/unit/credential-backends.test.ts` (8 tests)
+- Expanded `tests/unit/credentials-service.test.ts` with mocked backends (13 tests)
+
+## [0.4.0] - 2026-03-28
+
+### Added
+
+- **Token usage display** — shows input/output token counts after every AI call (`✓ Done (1,240 in → 860 out tokens)`)
+- **`planr refine --cascade`** — refines an artifact then cascades to all children down the full hierarchy (epic → features → stories → tasks)
+- **Parent-aligned refinements** — child refinements receive updated parent content as context so AI aligns changes with the parent
+- **Post-refine next steps** — after applying without `--cascade`, suggests which children may need re-alignment
+- **Cumulative token usage** for cascade operations (`Cascade complete: 7 artifacts refined (12,400 in → 8,200 out tokens total)`)
+- **Spinner `succeed()` method** — shows green checkmark with completion message instead of silently clearing
+
+### Changed
+
+- **Updated all dependencies** to latest major versions: `@anthropic-ai/sdk` 0.80, `openai` 6.x, `zod` 4.x, `commander` 14.x, `@inquirer/prompts` 8.x, `typescript` 6.x, `vitest` 4.x
+- **Removed `fs-extra`** dependency — replaced with Node.js built-in `fs/promises`
+- **Removed `ora`** dependency — replaced with lightweight built-in spinner
+- **Dropped Node 18 support** — minimum Node version is now 20
+- **Refine prompt** now preserves existing cross-reference links instead of adding phantom references
+- **"Suggestions" renamed to "Improvements"** in refine output for clearer UX
+
+### Fixed
+
+- **Refine command** no longer adds feature/story references that don't exist on disk
+- **CI publish workflow** — fixed npm trusted publishing with bypass 2FA token
+
+## [0.3.0] - 2026-03-28
+
+### Added
+
+- **`planr story create --epic <ID>`** — batch-generate stories for all features under an epic
+- **`planr checklist toggle`** — interactively toggle checklist items with multi-select prompt
+- **`planr config set-provider/set-key/set-model/set-agent`** — full AI configuration commands
+- **`--verbose` global flag** — debug logging across all commands
+- **`--all` flag on `planr status`** — show all items without truncation
+- **`--manual` flag** on epic, feature, story, and task create commands
+- **`--feature` filter** on `planr story list`
+- **Integration test suite** with real file system tests for artifact lifecycle and sync
+- **Test helpers** (`createTestProject`, `writeSampleEpic/Feature/Story`) for integration testing
+- **Pre-commit hooks** with husky + lint-staged (runs related tests on commit)
+- **Coverage reporting** with `@vitest/coverage-v8` and CI artifact upload
+- **CODEOWNERS** file for automatic review assignment
+- **Architecture guide** (`docs/ARCHITECTURE.md`)
+- **Troubleshooting guide** (`docs/TROUBLESHOOTING.md`)
+- **Security policy**, issue templates, and PR template
+
+### Changed
+
+- **`planr status`** — enhanced with tree view (epic → features → stories), task completion metrics with color-coded progress, and overall completion summary
+- **`planr refine`** — apply action now works: writes improved markdown to disk with view/apply/skip options
+- **`planr checklist show`** — now displays color-coded completion progress
+- **Documentation** — CLI.md now covers all 25 command variants with complete option tables
+- **README commands table** — expanded from 19 to 25 entries
+
+### Fixed
+
+- **Refine command** returning JSON instead of markdown in `improvedMarkdown` field — added explicit prompt instructions and JSON-detection fallback
+- **ID gap-filling** — `getNextId()` now reuses gaps (e.g., TASK-001 if only TASK-002 exists)
+- **npm bin paths** — added `./` prefix to suppress publish warnings
+
+### Security
+
+- Bumped `handlebars` from 4.7.8 to 4.7.9 (fixes critical vulnerability)
+- Dropped Node 18 support (EOL) — minimum Node 20
+
+### Developer Experience
+
+- Test coverage: 3 → 15 test files, 167 tests passing
+- Unit tests for: task-parser, markdown, fs, id-service, artifact-service, config-service, template-service, prompt-builder, logger, checklist-service
+- Integration tests for: artifact lifecycle, sync command
+- CI runs coverage on Node 22 with summary artifact upload
+- Upgraded to vitest 4.x
+
+## [0.2.0] - 2026-03-27
+
+### Added
+
+- **`planr plan`** — full automated flow (Epic → Features → Stories → Tasks)
+- **`planr refine <ID>`** — AI-powered review and improvement suggestions
+- **`planr sync`** — validate and fix cross-references across artifacts
+- **`planr config show`** — display current configuration
+- **`planr task create --feature <ID>`** — AI task list from every story under the feature, with parent feature and epic, all Gherkin files for those stories, all ADRs, and codebase-derived context (higher output token budget than per-story task create)
+- Feature-level task generation shares the same rich context model as `--story`, aggregated across the feature
+
+## [0.1.0] - 2026-03-26
+
+### Added
+
+- **CLI tool** with `planr` command (alias: `opr`)
+- **`planr init`** — initialize project with config and agile directory structure
+- **`planr epic create/list`** — create and list epics
+- **`planr feature create/list`** — create features from epics
+- **`planr story create/list`** — create user stories with Gherkin acceptance criteria
+- **`planr task create/list`** — task lists from a story or from all stories in a feature (AI mode includes epic, feature, Gherkin, ADRs, codebase context)
+- **`planr checklist show/reset`** — agile development checklist
+- **`planr rules generate`** — generate AI agent rule files
+  - Cursor (`.cursor/rules/*.mdc`)
+  - Claude Code (`CLAUDE.md`)
+  - Codex (`AGENTS.md`)
+- **`planr status`** — project planning progress overview
+- Handlebars template system for all artifact generation
+- Zod schema validation for configuration
+- Auto-incrementing ID system (EPIC-001, FEAT-001, US-001, TASK-001)
+- Full agile hierarchy enforcement (epic > feature > story > task)