@kyaukyuai/linear-cli 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-04-05
+
+### Added
+
+- expanded Automation Contract v7 across remaining high-value write surfaces, including issue assignment, estimate, move, priority, notification read/archive, project create and project-label mutations, and webhook create/update/delete flows
+- enriched `linear capabilities` with more parser-complete metadata such as aliases, repeatability, variadic inputs, defaults, canonical examples, resolution sources, and stronger machine-readable constraints
+- added machine-readable surface classification to `linear capabilities`, distinguishing `stable`, `partial`, and `escape_hatch` runtime surfaces for agent callers
+
+### Changed
+
+- expanded downstream certification from a single generic suite into named startup-monitor, control-plane, diagnostics, compatibility-bridge, and timeout-recovery consumer paths so release gates match real agent-runtime usage more closely
+
+## [3.0.1] - 2026-04-05
+
+### Changed
+
+- published a copy-pasteable v2-to-v3 migration cookbook and strengthened the v3 release guide around startup, diagnostics, and explicit compatibility-mode guidance
+- expanded the v3 release gate to certify both the native startup/discovery path and the explicit compatibility path for diagnostics and human/debug inspection
+
+### Fixed
+
+- improved common v3 compatibility failures so runtime suggestions point callers to `--text`, `--compat v1`, or `--profile human-debug --interactive` instead of forcing migration guidance to live only in docs
+
 ## [3.0.0] - 2026-04-04
 
 ### Added

package/README.md

@@ -40,6 +40,7 @@ Treat `linear-cli` as a shell-native control plane for agents:
 - refs can be normalized with `linear resolve ...`
 - write previews use `--dry-run --json`
 - write results expose `operation`, `receipt`, and structured `error.details`
+- `linear capabilities` classifies commands as `stable`, `partial`, or `escape_hatch`
 - human/debug behavior is explicit with `--text` and `--profile human-debug --interactive`
 
 The practical default loop is:
@@ -68,6 +69,7 @@ Recommended docs:
 - [Agent workflow guide](docs/agent-first.md)
 - [Automation contracts](docs/json-contracts.md)
 - [Agent-only v3 release guide](docs/agent-only-v3.md)
+- [v2 to v3 migration cookbook](docs/v2-to-v3-migration-cookbook.md)
 - [stdin and pipeline policy](docs/stdin-policy.md)
 
 ## migration from 2.x
@@ -80,7 +82,7 @@ If a downstream consumer still assumes the older mixed human/agent behavior, mig
 4. add `--text` anywhere a maintainer still wants terminal-oriented output
 5. add `--profile human-debug --interactive` anywhere a maintainer still wants prompts or pager-oriented debugging
 
-The detailed release and migration guide lives in [docs/agent-only-v3.md](docs/agent-only-v3.md).
+The detailed release and migration guide lives in [docs/agent-only-v3.md](docs/agent-only-v3.md). For copy-pasteable before/after fixes, use [docs/v2-to-v3-migration-cookbook.md](docs/v2-to-v3-migration-cookbook.md).
 
 ## human-debug demos
 
@@ -203,8 +205,9 @@ Use the docs in this order if you are building an agent integration:
 1. [docs/agent-first.md](docs/agent-first.md) for the recommended discover/read/preview/apply/recover loop
 2. [docs/json-contracts.md](docs/json-contracts.md) for stable JSON payloads, exit codes, timeout semantics, and dry-run envelopes
 3. [docs/agent-only-v3.md](docs/agent-only-v3.md) for the `v3.0.0` release contract and downstream migration checklist
-4. [docs/stdin-policy.md](docs/stdin-policy.md) for pipeline and file-input conventions
-5. [`linear capabilities`](#automation-contract) for machine-readable command metadata at runtime
+4. [docs/v2-to-v3-migration-cookbook.md](docs/v2-to-v3-migration-cookbook.md) for consumer-facing before/after upgrade examples
+5. [docs/stdin-policy.md](docs/stdin-policy.md) for pipeline and file-input conventions
+6. [`linear capabilities`](#automation-contract) for machine-readable command metadata at runtime
 
 ## automation contract
 
@@ -212,6 +215,8 @@ for bot and org-wide automation use cases, `linear-cli` defines a stable machine
 
 to discover the curated agent-facing command surface programmatically, use `linear capabilities`. the default shape now returns the richer v2 schema metadata for agent-native startup. when an older consumer still expects the trimmed legacy shape, pin it explicitly with `linear capabilities --compat v1`.
 
+the default capabilities shape now carries parser-oriented metadata for representative commands, including repeatable/variadic inputs, deprecated aliases, default values, composition constraints, and concrete resolution sources such as env vars, config keys, git branch context, jj trailers, and implicit stdin fallbacks.
+
 `agent-safe` is now the default execution profile for agent-controlled runs. it disables pager-by-default behavior, extends the built-in write timeout to `45000ms` unless `--timeout-ms` or `LINEAR_WRITE_TIMEOUT_MS` is set, and keeps destructive confirmation bypass explicit with `--yes`. use `--profile human-debug` when a maintainer explicitly wants prompt-driven or pager-oriented debugging behavior.
 
 non-goals:
@@ -220,13 +225,21 @@ non-goals:
 - it does not auto-confirm destructive actions
 - it does not replace explicit human/debug prompt flows; callers should pass flags, stdin, file inputs, or opt into `--profile human-debug --interactive`
 
+runtime surface classes:
+
+- `stable`: startup-contract or automation-contract surface. safe for primary agent runtime paths.
+- `partial`: agent-usable surface with shared dry-run or machine-readable traits, but not a full stable contract. pin explicit flags and avoid assuming long-term shape stability.
+- `escape_hatch`: intentionally raw or human/debug-only path, such as `linear api`, `--text`, or `--profile human-debug --interactive`.
+
 - v1 in scope: `issue list/view/create/update --json`, `issue relation add/delete/list --json`, `issue comment add --json`, `team members --json`, `issue parent/children/create-batch --json`
 - v2 additions: `project list/view --json`, `cycle list/view/current/next --json`, `milestone list/view --json`
 - v3 additions: `document list/view --json`, `webhook list/view --json`, `notification list/count --json`
 - v4 additions: `team list/view --json`, `user list/view --json`, `workflow-state list/view --json`, `label list --json`, `project-label list --json`
 - v5 additions: `initiative list/view --json`, `project-update list --json`, `initiative-update list --json`
 - v6 additions: `resolve issue/team/workflow-state/user/label --json`
-- out of scope: non-JSON terminal output, `linear api`, and other `--json` commands that are not listed above
+- v7 additions: `issue assign/estimate/move/priority --json`, `notification read/archive --json`, `project create --json`, `project label add/remove --json`, `webhook create/update/delete --json`
+- partial surfaces today include high-value dry-run adopters that do not yet expose a stable apply contract, such as `document create/update/delete`, `milestone create/update/delete`, `project update/delete`, and `issue start`
+- escape-hatch only surfaces include non-JSON terminal flows, `linear api`, and explicit human/debug output paths
 
 the contract fixes top-level success payload shapes and requires machine-readable failure payloads for the automation tier. see [docs/json-contracts.md](docs/json-contracts.md) for the full contract, compatibility rules, and example payloads. that guarantee also covers parser and argument validation failures when the command is in machine-readable mode, whether that is the default or was requested explicitly with `--json`.
 

package/npm-shrinkwrap.json

@@ -23,7 +23,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@kyaukyuai/linear-cli",
-      "version": "3.0.0"
+      "version": "3.1.0"
     },
     "node_modules/@isaacs/cliui": {
       "engines": {
@@ -542,5 +542,5 @@
     }
   },
   "requires": true,
-  "version": "3.0.0"
+  "version": "3.1.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/kyaukyuai/linear-cli/releases/download/v3.0.0"
+    "https://github.com/kyaukyuai/linear-cli/releases/download/v3.1.0"
   ],
   "bin": {
     "linear": "run-linear.js"
@@ -85,7 +85,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "3.0.0",
+  "version": "3.1.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"