docs(v0.11-M54-G): post-IMPL refactor-audit — file R-v0.11-NEW-5/6 + refresh Live numbers + flip M54-G status row

Post-IMPL housekeeping pass over the v0.11-M54-G cycle (f08bfef..59dff5a,
4 commits). Filed 2 new R-class watch-items + swept 2 genuine drift
sites in CLAUDE.md and v0.11-plan.md (no code touched; gates re-verified
green).

R-class candidates filed:

- R-v0.11-NEW-5 — Sentinel-normalisation anti-pattern: `raw === null
  || raw === undefined` early-return for sentinel-producing helpers
  masks shape-drift (code-hygiene watch-item, LOW). The M54-G IMPL R1
  P2-1 fix tightened parseItemDescription from the two-clause shape
  to `raw === null` only. Cross-doc grep confirmed 9 throw-on-absent
  call sites are safe (both null and undefined correctly route to
  not_found); 0 other sentinel-returning sites found. Watch for 2nd
  sentinel-returning parse helper — at 2 sites consider folding the
  audit-point into the codex pre-flight template's W3 enumeration.

- R-v0.11-NEW-6 — Codex pre-flight W3 wire-shape audit could
  exhaustively enumerate failure surfaces (a)-(e) (process /
  template extension, LOW-MEDIUM). The M54-G cycle showed Codex
  pre-flight R1 caught (c) malformed-row case but missed (d)
  missing-key drift, which Codex IMPL R1 then caught (same priority,
  same audit point). Single-instance evidence is insufficient (Codex
  review quality has natural variance); watch for 2nd reproducible
  miss before folding the (a)-(e) enumeration into the template.

Doc-drift sites fixed:

- CLAUDE.md:53-77 Live numbers block — refreshed from the stale
  v0.10-M53 close baseline (4270 tests + 4 skipped, 95.89% branches,
  118 commands, 1354/1368 functions) to the M54-G IMPL close baseline
  (4295 tests + 5 skipped, 95.86% branches, 119 commands, 1359/1373
  functions). Earlier coverage contributors list extended with the
  v0.10-M53 NOUN_DESCRIPTIONS lift.

- docs/v0.11-plan.md:66 M54-G status column — flipped from
  "pre-flight CLOSED 2026-05-23 ... IMPL pending" to "✅ SHIPPED
  2026-05-23" with the IMPL close SHA + Codex R2 verdict + the
  R-v0.11-NEW-2 graduation note.

Considered but NOT changed (historical narrative — leaving alone so
the next audit doesn't re-flag):

- docs/v0.11-plan.md:428,432,693,699 + .claude/rules/workflow.md:97 —
  references to "rejection-lift OR pure-refactor" old framing are all
  legitimate historical narratives describing the widening, not stale
  current prose.
- docs/v0.9-plan.md:1045 R-v0.9-NEW-2 original filing — entries in
  plan-doc §22 stay frozen at their filing-state per project
  convention; graduations/widenings recorded in subsequent plan-docs
  (v0.10-plan.md §3 M53 IMPL close + v0.11-plan.md §3 M54-G IMPL
  close).
- CLAUDE.md:344-348 — describes M53 close historically with "2nd
  instance: M50 deletion + M53 lift" — accurate AS OF v0.10-M53 close;
  the M54-G widening to 3 instances is recorded in v0.11 content
  (lines 191+ + plan-doc).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Nick Webster

CLAUDE.md

@@ -50,31 +50,38 @@ humans are second-class. Built incrementally via Claude Code on top of
   `monday-cli@0.8.0` (tag `v0.8.0` at `090fb76`, 2026-05-21T23:45:48Z);
   `monday-cli@0.7.0` (tag `3e46f59`, 2026-05-20T15:48:07Z).
 - **package.json version:** `0.10.0`.
-- **Live numbers:** **4270 tests pass + 4 skipped** (the **v0.10-M53
-  IMPL** net +10 over the M52 baseline of 4260 — 12 new
-  `tests/unit/commands/types.test.ts` cases pinning the
-  `NOUN_DESCRIPTIONS` map contract + `ensureSubcommand` 2-arg/3-arg
-  overload + `lookupNounDescription`'s `unknown_noun` strict-mode
-  invariant, less two replaced tests subsumed by the new contract.
-  The 4 skips are unchanged: the 2 pre-existing + the multipart-upload
-  smoke test + the board-projection schema-drift smoke test). **✅ CI
-  `test:coverage` PASSES:** global **branch coverage 95.89% vs the
-  95.45% floor** (HOLDS across M53 — the pure-refactor lift removed
-  87 single-line + 35 multi-line literal 3rd-args + added one
-  `lookupNounDescription` strict-mode branch, all covered by the new
-  contract tests). **29 ERROR_CODES** (unchanged across M53 — the
-  `lookupNounDescription` `unknown_noun` discriminator routes through
-  the existing `internal_error` code); **118 commands** (unchanged
-  across M53 — pure-refactor lift, no command delta);
-  **functions 98.97% (1354/1368)** — net +1 generated overload-witness
-  function the migration exercises, no coverage regression;
-  `npm audit` **0 vulnerabilities**. Earlier coverage contributors
-  still hold: the **v0.8 refactor cluster** (`item/update.ts` 79.42% →
-  87.27%), **R-v0.8-NEW-11** transport-helper lift, the M46 dispatch-
-  arm tests (`item/create.ts` 82.31% → 86.58%). **Release-prep held
-  all numbers** — every release-prep edit is docs-only (README, CHANGELOG,
-  plan-doc, CLAUDE.md) plus `package.json`/`package-lock.json` version
-  bumps; re-verified green at the close-docs gate.
+- **Live numbers:** **4295 tests pass + 5 skipped** (the **v0.11-M54-G
+  IMPL** net +25 over the v0.10.0 baseline of 4270 + 4 — 13 unit
+  `tests/unit/api/item-description.test.ts` cases pinning the
+  `ITEM_DESCRIPTION_QUERY` selection, the `documentBlockSchema` /
+  `itemDescriptionSchema` shapes, and `parseItemDescription` parse-
+  boundary surfaces; 8 integration
+  `tests/integration/commands/item-get-description.test.ts` cases
+  (happy + wire-null + emptied-blocks + not-found + usage-error +
+  401 + malformed-row guard + missing-description-key guard); 1 new
+  `RUN_LIVE_TESTS`-gated skip in `live-schema-drift.test.ts` for the
+  `ITEM_DESCRIPTION_QUERY` smoke; 1 envelope-snapshot test + the
+  pre-existing snapshot count delta; less 1 flipped unit test for
+  `parseItemDescription(undefined)`. The 5 skips: the 2 pre-existing +
+  the multipart-upload smoke + the board-projection schema-drift smoke
+  + the new item-description schema-drift smoke). **✅ CI
+  `test:coverage` PASSES:** global **branch coverage 95.86% vs the
+  95.45% floor** (HOLDS across M54-G — the absent-key guard + tightened
+  `parseItemDescription` early-return added new branches all covered
+  by the new tests; net 95.89% → 95.86% reflects the M54-G IMPL
+  adding `client.raw` + new schema branches the test surface didn't
+  exhaust at every defensive arm). **29 ERROR_CODES** (unchanged
+  across M54-G — the `missing_description_key` discriminator routes
+  through the existing `internal_error` code); **119 commands** (+1
+  for `monday item get-description`); **functions 98.98% (1359/1373)**
+  — net +5 functions from the new schema + helper + projector + verb
+  body, no coverage regression; `npm audit` **0 vulnerabilities**.
+  Earlier coverage contributors still hold: the **v0.8 refactor
+  cluster** (`item/update.ts` 79.42% → 87.27%), **R-v0.8-NEW-11**
+  transport-helper lift, the M46 dispatch-arm tests (`item/create.ts`
+  82.31% → 86.58%), the **v0.10-M53** `NOUN_DESCRIPTIONS` single-
+  source-of-truth lift (collapsed 122 duplicate `ensureSubcommand`
+  literals, no coverage regression).
 - **CI status:** **fully green.** The v0.7.0 table-colour test flake
   (root cause: cli-table3's `@colors/colors` caches its enabled-state
   from ambient TTY detection, so `color: true` emitted no ANSI in a
@@ -239,8 +246,14 @@ humans are second-class. Built incrementally via Claude Code on top of
   (jsonScalarOrNull pattern re-used in `item-description.ts`;
   lift at 3rd consumer per R-NEW-58). 4 R-class watch-items
   filed at pre-flight (R-v0.11-NEW-1/2/3/4); R-v0.11-NEW-2
-  GRADUATED at IMPL close; R-v0.11-NEW-1/3/4 stay WATCH. Net
-  stats: **4295 tests pass + 5 skipped** (+25 vs v0.10.0 baseline
+  GRADUATED at IMPL close; R-v0.11-NEW-1/3/4 stay WATCH;
+  **2 more watch-items filed at post-IMPL refactor-audit**
+  (R-v0.11-NEW-5 sentinel-normalisation anti-pattern, 1 known
+  instance fixed at M54-G IMPL R1 P2-1, watch for 2nd; R-v0.11-NEW-6
+  Codex pre-flight W3 wire-shape audit could exhaustively
+  enumerate (a)-(e) failure surfaces, watch for 2nd reproducible
+  miss before folding into template). Net stats: **4295 tests pass
+  + 5 skipped** (+25 vs v0.10.0 baseline
   of 4270 + 4); branches **95.86%** (≥ 95.45 floor); functions
   1359/1373; **29 ERROR_CODES** unchanged; **119 commands** (+1
   vs v0.10.0); `npm audit` 0 vulns. v0.10.0 stays PUBLISHED +

docs/v0.11-plan.md

@@ -63,7 +63,7 @@
 
 | M | Surface | Wire op | Status |
 |---|---------|---------|--------|
-| **M54-G** | **`monday item get-description <iid>` — narrow companion read.** New verb that surfaces Monday's `Item.description { id, blocks: [DocumentBlock] }` via raw GraphQL — 4 projected `DocumentBlock` fields (`id`, `type`, `content`, `position`) out of the 9 wire fields. Wire-null description (item never had one) normalises to the sentinel `{id: null, blocks: []}` so the single-resource envelope's `data` slot stays an iterable object (agents distinguish absent via `data.id === null`). Mirrors v0.9-M52's `board views <bid>` carve-out from `board describe` — heavy/nested content lives behind an opt-in verb rather than bloating `ITEM_FIELDS_FRAGMENT`'s ~16 universal consumers. SDK 14.0.0-untyped (same drift class as `hierarchy_type` / `views`); two-layer wire selection-pin guard applies (cassette `match_query: /description \{/` + RUN_LIVE_TESTS `toHaveProperty('description')`). | `query ItemGetDescription($ids: [ID!]!) { items(ids: $ids) { id description { id blocks { id type content position } } } }` | **pre-flight CLOSED 2026-05-23** (`f08bfef` — verb registers + tests + cassette pin + live-smoke; per R-v0.9-NEW-2 the new narrow verb's wire leg IS the runtime payload at pre-flight, no stub literal); IMPL pending (close-docs sweep + Codex IMPL review; very thin per the pure-additive shape) |
+| **M54-G** | **`monday item get-description <iid>` — narrow companion read.** New verb that surfaces Monday's `Item.description { id, blocks: [DocumentBlock] }` via raw GraphQL — 4 projected `DocumentBlock` fields (`id`, `type`, `content`, `position`) out of the 9 wire fields. Wire-null description (item never had one) normalises to the sentinel `{id: null, blocks: []}` so the single-resource envelope's `data` slot stays an iterable object (agents distinguish absent via `data.id === null`). Mirrors v0.9-M52's `board views <bid>` carve-out from `board describe` — heavy/nested content lives behind an opt-in verb rather than bloating `ITEM_FIELDS_FRAGMENT`'s ~16 universal consumers. SDK 14.0.0-untyped (same drift class as `hierarchy_type` / `views`); two-layer wire selection-pin guard applies (cassette `match_query: /description \{/` + RUN_LIVE_TESTS `toHaveProperty('description')`). | `query ItemGetDescription($ids: [ID!]!) { items(ids: $ids) { id description { id blocks { id type content position } } } }` | **✅ SHIPPED 2026-05-23** (pre-flight `f08bfef` Codex R1 CONVERGED 0 P1; IMPL close-docs `5738b64` Codex R2 CONVERGED 0 P1/P2/P3 — R1 P2-1 absent-key shape-drift gap folded inline + new `missing_description_key` discriminator + `parseItemDescription` early-return tightened to literal `null` only; R-v0.11-NEW-2 GRADUATED widening R-v0.9-NEW-2 rule to 3 instances in workflow.md) |
 | ~~M39 / M40 / M41~~ | API `2026-04` pin + `item set-description` + `doc block-create-bulk` | — | DEFERRED — SDK 15.x not published (**5th-consecutive stall**) |
 | ~~M44 / M45~~ | user-entity migration + `user activity` | — | DEFERRED — SDK 16.x not published |
 | **release-prep** | Version bump 0.10.0 → 0.11.0; CHANGELOG `[0.11.0]` headlining the new verb (one user-impact line per `feedback_public_docs_clean`); ToC audit; deferral-slot slip cross-doc grep (R-NEW-82); README refresh per R-v0.9-NEW-15 across the three surfaces (quickstart, per-version Scope block, `**v<next> (next):**` block — likely absent post-`317ae04` collapse); help-text hygiene grep (R-v0.8-NEW-21); envelope-snapshot refresh probe; close-docs sweep. Codex skipped per R-NEW-84 if zero production `src/**/*.ts` semantic changes outside the M54-G IMPL close. | (n/a) | pending |
@@ -740,3 +740,64 @@ pending the user):
   Cheap fold; do at next `_lib.ts` edit OR proactively at v0.11
   release-prep. **Status: OPEN (DX-only, defer until next probe
   authoring).**
+
+### New at M54-G IMPL close (2026-05-23 — post-IMPL refactor-audit)
+
+- **R-v0.11-NEW-5 — Sentinel-normalisation anti-pattern: `raw ===
+  null || raw === undefined` early-return for sentinel-producing
+  helpers masks shape-drift** (code-hygiene watch-item, LOW). The
+  M54-G IMPL R1 P2-1 fix (`5738b64`) tightened `parseItemDescription`
+  from `raw === null || raw === undefined` to **`raw === null`
+  only**. The two-clause early-return was correct for THROW-on-
+  absent helpers (which constitute the majority of the codebase's
+  similar shape — `assertUpdateMutationPresent`,
+  `assertResponseFieldPresent`, `projectMutationUpdate`,
+  `workspace/create.ts`'s post-mutation parse, etc., 9+ sites all
+  routing both `null` and `undefined` to `not_found` correctly).
+  But for **SENTINEL-returning** parse helpers (rare —
+  `parseItemDescription` is currently the only known instance in
+  `src/`), the same shape silently collapses JS-undefined-from-
+  shape-drift into the wire-null sentinel, making absent-key
+  shape regressions indistinguishable from genuine "no description
+  set" responses. **Cross-doc grep at this audit:** 9 throw-on-
+  absent sites confirmed safe; 0 other sentinel-returning sites
+  found. **Trigger:** if a 2nd sentinel-returning parse helper
+  ships, audit it for the same masking + either tighten to `raw
+  === null` only OR add an explicit upstream `hasOwnProperty.call`
+  guard at the verb body (the M54-G two-layer pattern). At 2 sites,
+  consider folding the audit-point into the codex pre-flight
+  template's W3 enumeration. **Status: WATCH (1 KNOWN INSTANCE,
+  ALREADY FIXED).** Cross-refs M54-G IMPL R1 P2-1.
+
+- **R-v0.11-NEW-6 — Codex pre-flight W3 wire-shape audit could
+  exhaustively enumerate failure surfaces** (process / template
+  extension, LOW-MEDIUM). The M54-G cycle showed Codex pre-flight
+  R1 caught `(c) malformed-row` (non-object scalar
+  `items: [42]` → P2-1) but missed `(d) missing-key` (object
+  without the selected field `items: [{id: '12345'}]`), which
+  Codex IMPL R1 then caught (P2-1 — same priority, same audit
+  point W3, same fix-class). Both fall under "wire-shape drift
+  hidden by the projection boundary's sentinel-normalisation"
+  but the pre-flight Codex reviewer enumerated only the malformed-
+  row case + missed the missing-key sibling. **Candidate:** add a
+  sub-bullet to the codex-pre-flight-review.md template's W3
+  pattern (or to milestone-specific W3 enumeration prose for any
+  read verb with a wire-null sentinel normaliser) asking the
+  reviewer to walk the FULL failure-surface set:
+    (a) populated wire shape — happy path
+    (b) wire-null sentinel — `field: null` literal
+    (c) malformed row — non-object scalar / wrong-type at items[0]
+    (d) missing-key drift — object without the selected field
+    (e) malformed nested shape — schema parse-boundary
+  **Trigger:** at the 2nd "Codex IMPL caught a wire-shape failure
+  surface Codex pre-flight missed" instance, fold the
+  enumeration into the template's W3 framing OR into
+  `.claude/rules/testing.md` as a per-milestone audit-point
+  checklist for wire-null sentinel normalisers. The single-
+  instance evidence is insufficient (Codex review quality has
+  natural variance per round); a 2nd reproducible miss confirms
+  the gap is template-shape rather than reviewer-variance.
+  **Status: WATCH (1 INSTANCE, NEED 2ND BEFORE FOLDING).**
+  Cross-refs R-v0.7-NEW-4 (parent process-discipline framing —
+  "pre-IMPL checklist replaces round-N-specific term discovery";
+  R-v0.11-NEW-6 is the wire-shape-surface analog).