SDK atomic structured mutations, lean output, and agent-first envelopes

.agents/pm/extensions/.managed-extensions.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "updated_at": "2026-07-19T17:39:34.219Z",
+  "updated_at": "2026-07-20T11:57:03.909Z",
   "entries": [
     {
       "name": "pm-changelog",

.agents/pm/features/pm-cfed.toon

@@ -2,19 +2,46 @@ id: pm-cfed
 title: "GH-435: lean JSON output mode omitting null/empty fields (~50% token cut for --json)"
 description: "Dogfood GH-435: --json is ~50% larger than TOON because it serializes all-null filters echoes and empty containers; add a lean JSON mode. Duplicate check: searched lean json/omit null/compact output — only MCP compact defaults (closed 2026-05-20) and mutation compactness (GH-437 item) matched; no open overlap."
 type: Feature
-status: open
+status: closed
 priority: 2
 tags[4]: agent-ux,"area:cli",gh-issue,token-efficiency
 created_at: "2026-07-06T08:03:03.161Z"
-updated_at: "2026-07-18T15:09:38.214Z"
+updated_at: "2026-07-20T10:27:08.701Z"
+closed_at: "2026-07-20T10:26:25.482Z"
 author: maintainer-agent
 estimated_minutes: 180
 acceptance_criteria: Lean JSON mode ships on list/get/context/search; null/empty omission rules pinned by spec; >=40% measured size cut on list+context in this workspace; docs+contracts updated
 parent: pm-mpbb
 risk: low
 confidence: high
-dependencies[1]{id,kind,created_at,author,source_kind}:
+resolution: Lean JSON recursively removes null and empty containers while preserving meaningful root semantics and stable pagination fields.
+expected_result: Lean list and context JSON reduce combined bytes by at least 40% without erasing actionable information.
+actual_result: "Packed list plus context output dropped 41.06%, list dropped 52.57%, context dropped 35.42%, and fully empty lean roots emit null."
+dependencies[4]{id,kind,created_at,author,source_kind}:
   pm-nilh,related,"2026-07-06T08:03:45.495Z",null,null
-comments[1]{created_at,author,text}:
+  pm-ds3b,related,"2026-07-20T08:49:47.189Z",null,null
+  pm-g9xk,related,"2026-07-20T08:49:47.189Z",null,null
+  pm-xm7c,related,"2026-07-20T08:49:47.189Z",null,null
+comments[4]{created_at,author,text}:
   "2026-07-18T15:09:38.214Z",codex-root,"GitHub intake 2026-07-18: GH-595 (https://github.com/unbraind/pm-cli/issues/595) independently confirms the canonical lean-JSON scope: pm list --json spends about 44% of its envelope on null filter echoes. The report also adds a related pagination-envelope stability requirement (always-present total/has_more and removal of redundant has_more/truncated semantics). All-status duplicate search maps the null-bloat portion here; retain one canonical implementation lineage and account for the pagination addition when this item is claimed."
+  "2026-07-20T09:59:53.909Z",codex-20260720,"Evidence: --lean recursively omits null and empty containers in structured output while preserving actionable fields. Isolated packed list JSON shrank from 1069 to 507 bytes (52.57% reduction); lean known and Commander error contracts are covered."
+  "2026-07-20T10:01:00.123Z",codex-20260720,"Acceptance measurement detail: isolated packed list+context combined output shrank from 3254 to 1918 bytes (41.06%); list alone shrank 52.57% and context alone 35.42%. This satisfies the combined >=40% list+context target."
+  "2026-07-20T10:26:23.435Z",codex-20260720,"Greptile finding disposition: fixed the fully-compacted lean JSON root to emit null rather than an ambiguous success object; focused output/structured suites pass and full coverage is 6013/6013 at 100/100/100/100."
+files[7]{path,scope,note}:
+  src/cli/error-guidance.ts,project,Lean error envelope projection
+  src/cli/registration-helpers.ts,project,lean option propagation
+  src/core/output/output.ts,project,recursive lean JSON projection
+  src/core/shared/command-types.ts,project,lean global output contract
+  src/sdk/cli-bootstrap.ts,project,bootstrap lean parsing
+  src/sdk/cli-program.ts,project,public global lean flag
+  tests/integration/structured-mutation-io.integration.spec.ts,project,Lean JSON byte and omission acceptance
+tests[3]{command,scope,timeout_seconds}:
+  node scripts/run-tests.mjs coverage,project,600
+  node scripts/run-tests.mjs test -- tests/integration/structured-mutation-io.integration.spec.ts tests/unit/cli/structured-mutation-registration.spec.ts,project,180
+  node scripts/run-tests.mjs test -- tests/integration/structured-mutation-io.integration.spec.ts tests/unit/core/output/output.spec.ts,project,240
+test_runs[1]{run_id,kind,status,started_at,finished_at,recorded_at,passed,failed,skipped}:
+  test-local-mrt1w8es-6vdqzi,test,passed,"2026-07-20T09:57:04.555Z","2026-07-20T09:57:15.796Z","2026-07-20T09:57:15.796Z",1,0,0
+docs[1]{path,scope,note}:
+  docs/COMMANDS.md,project,lean JSON omission semantics
+close_reason: "Implemented lean structured output with measured 41.06% combined reduction, preserved null root semantics, contracts, docs, packed proof, Greptile follow-up, and exact 100% coverage."
 body: "GitHub: https://github.com/unbraind/pm-cli/issues/435\n\n## Problem\n`--json` output serializes every field including nulls and empty containers: `pm list --json` always emits a 23-key all-null `filters` echo (+ empty `runtime_filters`); `pm context --json` echoes `order/deadline/assignee/parent: null` per item. Measured: list 2552 B (TOON) vs 3773 B JSON (+48%); context 4582 vs 7034 (+53%). AGENTS.md already warns agents off `--json` for loops — the structured format is too expensive for the agents that need it.\n\n## Proposed fix\nLean JSON mode (`--json --lean`, `PM_JSON_LEAN=1`, or config key) that omits null values, empty arrays/objects, and collapses `filters` to only keys actually set (TOON parity). Verbose form stays as explicit opt-in.\n\n## Definition of done\nLean mode on list/get/context/search JSON paths; measured >=40% size cut on list+context in a tag-heavy tracker; contracts + docs updated; spec pins the null-omission rules."

.agents/pm/features/pm-g9xk.toon

@@ -2,19 +2,43 @@ id: pm-g9xk
 title: "GH-443: lean error mode — drop constant required/why boilerplate from structured errors"
 description: "Dogfood GH-443: every structured error carries two constant prose fields (required/why) that never vary by error; keep only actionable fields in lean mode. Duplicate check: pm-gdi7 covers unknown-option suggestions, not envelope size; no other overlap."
 type: Feature
-status: open
+status: closed
 priority: 2
 tags[4]: agent-ux,"area:cli",gh-issue,token-efficiency
 created_at: "2026-07-06T08:03:05.997Z"
-updated_at: "2026-07-15T19:27:27.234Z"
+updated_at: "2026-07-20T10:27:09.494Z"
+closed_at: "2026-07-20T10:01:05.447Z"
 author: maintainer-agent
 estimated_minutes: 90
 acceptance_criteria: JSON errors omit generic constant prose while keeping code/detail/examples/next_steps/recovery; error-envelope spec updated; mode documented for agents
 parent: pm-mpbb
 risk: low
 confidence: high
-dependencies[1]{id,kind,created_at,author,source_kind}:
+resolution: Structured errors expose a compact actionable envelope through shared public SDK normalization primitives.
+expected_result: "Lean errors remove repeated boilerplate while preserving code, detail, exit status, and next action semantics across CLI surfaces."
+actual_result: "Commander and known runtime errors share compact lean projection, public error helpers, strict docstrings, tests, and zero SDK-boundary growth."
+dependencies[4]{id,kind,created_at,author,source_kind}:
   pm-gdi7,related,"2026-07-06T08:03:05.997Z",null,null
+  pm-cfed,related,"2026-07-20T08:49:48.290Z",null,null
+  pm-ds3b,related,"2026-07-20T08:49:48.290Z",null,null
+  pm-xm7c,related,"2026-07-20T08:49:48.290Z",null,null
+comments[1]{created_at,author,text}:
+  "2026-07-20T09:59:54.464Z",codex-20260720,"Evidence: lean errors retain code/detail/exit_code/recovery while omitting constant boilerplate; shared normalization moved behind public SDK runtime primitives so CLI/MCP added zero private-core boundary edges. Static gate reports 100% source/export/member docstrings and SDK boundary 405/405 with no violations."
 notes[1]{created_at,author,text}:
   "2026-07-15T19:27:27.232Z",maintainer-agent,"Fresh evidence 2026-07-15 (review pass #89): a one-token command typo (pm lst) returns ~20 lines / ~150 tokens of constant scaffolding (What happened / What is required / Why / Examples / Next steps / Recovery bundle) around the only two load-bearing lines: the error name and \"Did you mean: list?\". Worse, for unknown-OPTION errors the Error: headline and the \"What happened:\" paragraph are the IDENTICAL sentence twice (observed on --statuss). Lean mode should collapse to headline + suggestion + one recovery hint; the full bundle stays behind --verbose or a config key. Duplicate-sentence dedup is worth doing even before lean mode ships."
+files[5]{path,scope,note}:
+  src/cli/commander-usage.ts,project,lean Commander JSON errors
+  src/cli/error-guidance.ts,project,actionable lean error projection
+  src/cli/main.ts,project,lean known error routing
+  src/sdk/error-runtime.ts,project,Shared SDK error normalization primitives
+  tests/unit/cli/error-handler-projection.spec.ts,project,In-process lean error and primitive normalization coverage
+tests[3]{command,scope,timeout_seconds}:
+  node scripts/run-tests.mjs coverage,project,600
+  node scripts/run-tests.mjs test -- tests/unit/cli/error-handler-projection.spec.ts tests/integration/structured-mutation-io.integration.spec.ts,project,240
+  node scripts/run-tests.mjs test -- tests/unit/cli/structured-mutation-registration.spec.ts tests/integration/structured-mutation-io.integration.spec.ts,project,180
+test_runs[1]{run_id,kind,status,started_at,finished_at,recorded_at,passed,failed,skipped}:
+  test-local-mrt1wgl8-rd6y01,test,passed,"2026-07-20T09:57:16.304Z","2026-07-20T09:57:26.396Z","2026-07-20T09:57:26.396Z",1,0,0
+docs[1]{path,scope,note}:
+  docs/COMMANDS.md,project,agent lean error mode
+close_reason: "Implemented actionable lean JSON errors and public SDK error normalization primitives with zero SDK-boundary growth, docs, and full tests."
 body: "GitHub: https://github.com/unbraind/pm-cli/issues/443\n\n## Problem\nThe structured error envelope carries two constant-prose fields on every error (`required`: \"Use values that match documented command constraints.\"; `why`: \"Validation protects data consistency...\"). They never vary by error and carry no actionable signal — pure token overhead in retry loops.\n\n## Proposed fix\nLean error mode (or simply omit constant `why`/`required` under --json unless error-specific): keep `code`, `detail`, `examples`, `next_steps`, `recovery.suggested_retry`. Verbose prose stays for human/TTY.\n\n## Definition of done\nJSON errors drop generic boilerplate (or --lean-errors/PM_LEAN_ERRORS added); error-envelope spec updated; agent docs note the mode. Related: pm-gdi7 covers unknown-option did-you-mean in the same envelope."

.agents/pm/features/pm-kipd.toon

@@ -2,18 +2,46 @@ id: pm-kipd
 title: "GH-438: accept a full item JSON document on stdin for pm create / pm update"
 description: "Dogfood GH-438: no single-document create/update; agents translate items into 10-20 flags. Duplicate check: searched stdin json/document create — only per-field stdin support (--dep -, --note -) exists; no open overlap."
 type: Feature
-status: open
+status: closed
 priority: 2
 tags[3]: agent-ux,"area:cli",gh-issue
 created_at: "2026-07-06T08:03:04.192Z"
-updated_at: "2026-07-14T17:05:05.785Z"
+updated_at: "2026-07-20T10:27:07.952Z"
+closed_at: "2026-07-20T10:26:28.799Z"
 author: maintainer-agent
 estimated_minutes: 240
 acceptance_criteria: create/update accept --stdin-json full-item documents incl. facets; get->modify->update round-trip spec green; unknown keys rejected with did-you-mean; docs+contracts updated
 parent: pm-mpbb
 risk: medium
 confidence: high
-dependencies[2]{id,kind,created_at,author,source_kind}:
+resolution: Create and update accept full item JSON documents on stdin with deterministic precedence and safe round trips.
+expected_result: "Agents can pipe complete item documents into create/update, preserve facets, reject likely typos, and override document values with explicit flags."
+actual_result: "Direct and get-envelope documents normalize into typed mutation options; explicit flags win, persisted annotations are deduplicated, custom fields remain extensible, and packed round trips are no-ops unless changed."
+dependencies[6]{id,kind,created_at,author,source_kind}:
   pm-srns,related,"2026-07-14T17:05:05.070Z",null,null
   pm-xwah,related,"2026-07-14T17:05:05.766Z",null,null
+  pm-cfed,related,"2026-07-20T08:49:46.009Z",null,null
+  pm-ds3b,related,"2026-07-20T08:49:46.009Z",null,null
+  pm-g9xk,related,"2026-07-20T08:49:46.009Z",null,null
+  pm-xm7c,related,"2026-07-20T08:49:46.009Z",null,null
+comments[2]{created_at,author,text}:
+  "2026-07-20T09:59:53.386Z",codex-20260720,"Evidence: create/update now accept complete get --full JSON envelopes through --stdin-json, explicit flags win, persisted annotations are not duplicated, and empty persisted facet arrays do not clear data. Temp packed get-to-update round trip returned changed_field_count=0; linked focused suites passed in the pm sandbox."
+  "2026-07-20T10:26:24.646Z",codex-20260720,"Greptile finding disposition: flat update documents now filter persisted comments/notes/learnings exactly like get envelopes while retaining new annotations. Arbitrary non-near-match keys remain intentional custom fields for universal schemas; near-match typos still fail with hints. Full coverage is 100/100/100/100."
+files[5]{path,scope,note}:
+  src/cli/register-mutation.ts,project,create and update stdin adapters
+  src/sdk/cli-contracts/flag-contracts.ts,project,stdin JSON flag contracts
+  src/sdk/structured-mutations.ts,project,full item normalization
+  tests/integration/structured-mutation-io.integration.spec.ts,project,Full get update round-trip acceptance
+  tests/unit/cli/structured-mutation-registration.spec.ts,project,Whole-item stdin precedence and empty input coverage
+tests[3]{command,scope,timeout_seconds}:
+  node scripts/run-tests.mjs coverage,project,600
+  node scripts/run-tests.mjs test -- tests/unit/cli/structured-mutation-registration.spec.ts tests/integration/structured-mutation-io.integration.spec.ts,project,240
+  node scripts/run-tests.mjs test -- tests/unit/sdk/structured-mutations.spec.ts tests/integration/structured-mutation-io.integration.spec.ts,project,180
+test_runs[2]{run_id,kind,status,started_at,finished_at,recorded_at,passed,failed,skipped}:
+  test-local-mrt1vzav-c9t8nc,test,failed,"2026-07-20T09:56:44.415Z","2026-07-20T09:57:03.991Z","2026-07-20T09:57:03.991Z",1,1,0
+  test-local-mrt1yie2-rcpq2x,test,passed,"2026-07-20T09:58:42.756Z","2026-07-20T09:59:02.042Z","2026-07-20T09:59:02.042Z",2,0,0
+docs[2]{path,scope,note}:
+  docs/COMMANDS.md,project,get modify update round-trip guide
+  docs/SDK.md,project,structured item adapter reference
+close_reason: "Implemented full-item JSON stdin create/update with flag precedence, persisted annotation deduplication for envelope and flat documents, facet-safe round trips, contracts, docs, Greptile follow-up, linked tests, and packed proof."
 body: "GitHub: https://github.com/unbraind/pm-cli/issues/438\n\n## Problem\nNo way to create/update an item from one JSON document: `pm create -` treats `-` as the title; `--stdin` is unknown. Structured agents must translate an item into 10-20 flags; strict-mode errors suggest a 19-flag retry.\n\n## Proposed fix\n`pm create --stdin-json` and `pm update <id> --stdin-json` accepting the same item shape `pm get --json` emits (round-trip: get | modify | update). Flags win over document keys when both given. Reject unknown keys with did-you-mean.\n\n## Definition of done\nCreate+update accept full item documents on stdin incl. deps/comments/files facets; round-trip spec (get -> update) green; SDK/MCP parity noted (MCP already takes structured params); docs + contracts updated."

.agents/pm/features/pm-nilh.toon

@@ -2,15 +2,40 @@ id: pm-nilh
 title: "GH-437: make lean mutation output the CLI default (parity with MCP compact envelope)"
 description: "Dogfood GH-437: CLI mutations echo the full item (12.7x vs --id-only) while MCP is compact by default; align CLI default with MCP. Duplicate check: compact mutation output PR (2026-05-26) shipped suppressor flags only; no open item flips the default."
 type: Feature
-status: open
+status: closed
 priority: 2
 tags[4]: agent-ux,"area:cli",gh-issue,token-efficiency
 created_at: "2026-07-06T08:03:03.701Z"
-updated_at: "2026-07-06T08:03:03.701Z"
+updated_at: "2026-07-20T10:27:10.448Z"
+closed_at: "2026-07-20T10:01:06.896Z"
 author: maintainer-agent
 estimated_minutes: 120
 acceptance_criteria: CLI mutations default (or config-default) to id/status/changed_field_count; --full opt-ins restore old echo; MCP-parity spec green; measured reduction recorded
 parent: pm-mpbb
 risk: low
 confidence: high
+resolution: Single-item mutations default to compact id/status/change-count envelopes with explicit full and id-only compatibility controls.
+expected_result: Agent mutation responses are token-efficient by default while callers can request legacy full deltas or id-only output.
+actual_result: "Compact defaults ship across CLI and MCP with 87.82% packed output reduction, full/id-only precedence, updated token budgets, contracts, docs, and tests."
+dependencies[3]{id,kind,created_at,author,source_kind}:
+  pm-cfed,related,"2026-07-20T08:49:49.562Z",null,null
+  pm-g9xk,related,"2026-07-20T08:49:49.562Z",null,null
+  pm-xm7c,related,"2026-07-20T08:49:49.562Z",null,null
+comments[1]{created_at,author,text}:
+  "2026-07-20T09:59:55.002Z",codex-20260720,"Evidence: mutation commands now default to id/status/changed_field_count, --no-changed-fields preserves the compact legacy item envelope, --full-changed-fields restores the full delta, and --id-only retains precedence. Isolated packed creates measured 71-byte compact vs 583-byte full output (87.82% reduction). Token-budget consumer and manifest were updated intentionally."
+files[6]{path,scope,note}:
+  scripts/release/token-budget-gate.mjs,project,Compact mutation consumer compatibility
+  scripts/release/token-budgets.json,project,Intentional agent output budget update
+  src/core/output/mutation-projection.ts,project,Compact default mutation envelope
+  src/sdk/cli-contracts/flag-contracts.ts,project,full changed fields contract
+  src/sdk/cli-program.ts,project,explicit full changed fields opt-in
+  tests/unit/core/output/mutation-projection.spec.ts,project,Compact envelope projection coverage
+tests[2]{command,scope,timeout_seconds}:
+  node scripts/run-tests.mjs test -- tests/integration/structured-mutation-io.integration.spec.ts,project,180
+  node scripts/run-tests.mjs test -- tests/unit/core/output/mutation-projection.spec.ts tests/unit/core/output/output.spec.ts tests/integration/structured-mutation-io.integration.spec.ts,project,240
+test_runs[1]{run_id,kind,status,started_at,finished_at,recorded_at,passed,failed,skipped}:
+  test-local-mrt1wq5g-6g4ut7,test,passed,"2026-07-20T09:57:26.862Z","2026-07-20T09:57:38.788Z","2026-07-20T09:57:38.788Z",1,0,0
+docs[1]{path,scope,note}:
+  docs/COMMANDS.md,project,explicit compact and full mutation controls
+close_reason: "Implemented compact mutation output by default with explicit full/id-only compatibility controls, 87.82% packed output reduction, MCP parity, token budgets, docs, and tests."
 body: "GitHub: https://github.com/unbraind/pm-cli/issues/437\n\n## Problem\nEvery CLI mutation echoes the full updated item + full `changed_fields` by default (368 B for a trivial create vs 29 B `--id-only` — 12.7x). MCP is already compact by default (`changed_field_count`, `idOnly`/`fullChangedFields` opt-ins), so the CLI is the more verbose surface and inconsistent with MCP.\n\n## Proposed fix\nMake CLI mutation default lean: `{ id, status, changed_field_count }` (+ `close_reason` on close). Full echo behind `--full` / `--full-changed-fields`; existing `--id-only`/`--quiet` stay. Config knob (e.g. `output_lean_mutations`) so the default is project-tunable; respect back-compat for scripts via config.\n\n## Definition of done\nLean default (or config-flipped default) with parity spec vs MCP compact output; docs/AGENTS.md updated; contracts:update run; measured token reduction recorded on this item."