fix(cli): name the remainder at every truncating render in build/validate/init

[claude]

Fixes#11642

Nine diagnostic renders across os build, os validate and os init cut their list at a fixed cap and printed nothing saying so. The cap is not the defect; the silence is. Truncated output that carries no notice is indistinguishable from complete output, so an author who reads it and sees no further problems has read a list that stopped early — and on the gating lists that quietly restores the round-trip os validate went out of its way to remove ("the command used to exit at the first failing gate, so an author with three unrelated problems fixed them in three round trips and could not see how deep the hole went").

Every cap keeps the value it had. Over it, the output now names the exact remainder:

 ⚠ … and 30 more author-time rule failure(s) not shown (50 of 80) — re-run with --json for the full list

---

1. The worklist, re-derived from the DEFECT

The card's population was selected by grepping slice(0, 50), which answers "where does the number 50 appear", not "where is output truncated in silence". Measured here, those differ in both directions, so the worklist below was re-derived from the defect — a truncating render with no remainder line — and every candidate's surrounding lines were read before it was counted. Line numbers are current (945ffbea8); the card's are two merges stale.

IN — 9 sites, all fixed

#	file:line	list	cap	why it is in
1	compile.ts:145	issues (--strict-body refusal)	20	Missing from the card's ledger. Header states the true total, body shows 20, nothing says the rest exist — byte-for-byte the shape the card grades as a defect at the undeclared-keys site. Only the cap value differs, which is exactly why a 50-anchored sweep could not see it.
2	compile.ts:236	ruleErrors	50	Gating rule failures, exit 1, no notice.
3	compile.ts:306	unknownKeyWarnings	50	Advisory. Header already prints the true total (Undeclared authoring keys (N)), so the block stated two numbers that disagreed and explained neither. Renamed from unknownKeyFindings and re-formatted at the computation site by #11726; its slice(0, 50) is byte-unchanged and was still silent.
4	compile.ts:346	access-matrix drift	50	exit 1, no notice.
5	compile.ts:373	docErrors	50	exit 1, no notice.
6	validate.ts:140	ruleErrors	50	exit 1, no notice.
7	validate.ts:212	docErrors	50	exit 1, no notice.
8	init.ts:893	report.advisories	50	Scaffold self-test advisories, scaffold continues, no notice.
9	init.ts:908	report.errors	50	Scaffold self-test failures, no notice.

OUT — read, judged, untouched

site	verdict
compile.ts:174lowering.bodyExtractionWarnings (cap 20)	NOT a defect — the precedent. It already prints … and ${n - 20} more plus a pointer at the complete-output path (os build --strict-body). Listing it would have been the obvious next move from the grep and it would have been wrong. ⛔ Untouched; a pin asserts both of its lines are still there byte for byte, because a change to it is a change to the standard everything else now copies.
compile.ts:222ruleAdvisories	Already fixed by #11645. Reused, not re-done — see §3.
compile.ts:108conversionNotices, :270 / :276capPreflight.errors / .warnings, :380docWarnings	Uncapped — the loop renders the whole list. No truncation, nothing to name.
validate.ts:180capProviderErrors, :363warnings	Uncapped.
init.ts:61-63s.slice(0, 20)	String truncation of a namespace identifier, not a list render.
init.tsprintCreatedFilesSummary, formatZodErrors (all three commands)	Uncapped; formatZodErrors even closes with N validation error(s) total.

Outside the three printers, the same sweep over packages/** found four more capped renders (runtime/app-plugin.ts, service-storage/verify-file-references.ts, three in spec/scripts/build-schemas.ts) — all of them already name their remainder, so there is no wider silent-truncation population to file. The one genuine find is a different defect and is filed, not fixed: see §6.

---

2. Per-site --json check — the pointer is verified, never assumed

#11645's notice ends by pointing at --json "for the full list", and that is honest only for a list --json actually carries. A notice whose remedy does not work is worse than a silent cut: it sends the author down a path that returns the same truncated view. So each site was read against its own payload before a pointer was offered.

site	does --json carry that list?	payload key, at the same exit	notice says
compileissues (strict-body)	yes	{ success: false, error: 'strict-body: missing body', issues }	— re-run with --json for the full list
compileruleErrors	yes	{ …, error: 'author-time rules failed', issues: ruleErrors, … }	same
compileunknownKeyWarnings	yes, since #11726	success payload warnings: [...ruleAdvisories, ...unknownKeyWarnings]	same — see the caveat below
compiledrift	yes	{ …, error: 'access matrix drift', changes: drift }	same
compiledocErrors	yes	{ …, error: 'docs validation failed', issues: docErrors }	same
validateruleErrors	yes	{ valid: false, errors: ruleErrors, … }	same
validatedocErrors	yes	{ valid: false, errors: docErrors, … }	same
initreport.advisories	no — the command has no --json flag at all	—	remainder stated, no pointer
initreport.errors	no — same	—	remainder stated, no pointer; the site's existing "this is a CLI bug, please report it" line is the action that does exist here

os init's static override flags declares template, install and package-manager and nothing else. A pin asserts that (with a positive control: the same pattern is found in compile.ts and validate.ts), so adding --json to init later fails here rather than silently leaving two dead pointers behind. init.ts also contains no reference to the shared pointer constant, which the same pin checks.

⛔ Nothing was added to any --json payload to make a notice true. That is #11643's class and a machine-contract change.

One caveat, recorded honestly rather than papered over. The six error-path pointers are airtight: the --json branch sits in the same block as the text face, so re-running the identical command returns the whole list from the same exit. The two advisory pointers — unknownKeyWarnings here, and ruleAdvisories from #11645 — resolve through the terminal success payload, so a run that fails at a later gate emits a failure payload that carries no warnings. Filed as #11772 rather than fixed here: closing it means changing a --json payload shape, which this card may not do.

---

3. printAuthoringAdvisories is reused, not duplicated

• init.ts:893 now calls printAuthoringAdvisories itself. That block was a byte-for-byte copy of the printer's body, cap included; it is now the same call os build makes, with remedy: null.
• The notice sentence has exactly one implementation, printTruncationNotice in packages/cli/src/utils/format.ts. printAuthoringAdvisories was refactored onto it and its rendered output is byte-for-byte what objectstack build / validate print at most 50 author-time warnings and drop the rest with no notice #11529 shipped — fix(cli): os build names the author-time warnings it withheld instead of stopping dead at 50 #11645's own pin file is untouched and still passes, and the ablation in §4 takes 3 of its assertions down with the rest, which is what proves the two really share one implementation rather than merely agreeing today.
• The three row shapes that differ from the advisory rows (printAuthoringRuleErrors, printDocIssueErrors, printBulletList) each render their own rows and then call that one notice. Nine copies of the wording would have been nine chances to drift.
• The shape copied is the precedent's: name the remainder, then point at a complete-output path that exists.

---

4. Pins — red before, green after

New file: packages/cli/test/truncation-remainder-notices.test.ts (32 tests). Run with #11645's untouched pin file (7 tests) throughout.

Green, after:Test Files 2 passed (2) · Tests 39 passed (39)

Red-before #1 — the sites. Restore the three command files to origin/main, keep the helper and the pins (git restore --source=origin/main --worktree; mutation proved on disk before measuring: 0 printer calls in each file, 6 + 2 + 2 capped for-of loops back):

 ❯ test/truncation-remainder-notices.test.ts (32 tests | 10 failed)
× 'compile.ts' — 'issues' × 'compile.ts' — 'ruleErrors'
× 'compile.ts' — 'unknownKeyWarnings' × 'compile.ts' — 'drift'
× 'compile.ts' — 'docErrors' × 'validate.ts' — 'ruleErrors'
× 'validate.ts' — 'docErrors' × 'init.ts' — 'report.advisories'
× 'init.ts' — 'report.errors'
× the only capped for-of left is the PRECEDENT, and it names its own remainder
Test Files 1 failed | 1 passed (2)
Tests 10 failed | 29 passed (39)

The sweep names the defect in its own words, including the site the card's ledger was missing:

AssertionError: compile.ts:145 truncates issues with no remainder line:
expected ' for (const w of issues.slic…' to match /… and |not shown|printTruncationNotice/

Red-before #2 — the rendered output (ablation). The printers are new, so "the function does not exist" is not a meaningful red. Instead the shared notice was ablated to a no-op (return; at the top of printTruncationNotice) and the whole suite re-measured. Mutation proved on disk first — injected marker present ×1, function and its 4 call sites still there — and the suite resolves ../src/utils/format.js, i.e. source, so no build stands between the mutation and the measurement; the script carries trap … EXIT INT TERM so a kill mid-mutation cannot leave the tree ablated. Restore leg verified by git hash-object equal to the committed blob and the marker absent.

 × OVER the limit: states how many were withheld … (#11529's file)
× ONE over the limit: the notice appears and reads exactly 1 (#11529's file)
× the remainder is the EXACT count, not a fixed word (#11529's file)
× OVER the cap: names the exact remainder …
× no remedy: the remainder is still stated, and no pointer is invented
× OVER the cap: names the remainder and offers the remedy the caller supplied
× ONE over the cap: the notice reads exactly 1 — the tightest edge
× no remedy (the `os init` form): the remainder is named, no pointer is offered
× OVER the cap: names the remainder (doc errors)
× OVER the cap: names the remainder with the caller-supplied noun
× respects a cap other than 50 — the `--strict-body` site caps at 20
× the default is unchanged — remainder plus the --json pointer
× remedy `null` (what `os init` passes): remainder named, pointer withheld
Test Files 2 failed (2)
Tests 13 failed | 26 passed (39)

Controls — green in BOTH states, which is the point. A printer that always printed a notice would satisfy every red-going pin above. So each printer is pinned from the other end too, and every one of these stayed green under the ablation:

• a list shorter than the cap prints no notice at all (all four printers);
• a list exactly at the cap prints every row and no notice;
• an empty list prints nothing — not an empty notice;
• the rows themselves are unchanged: the 50th is present, the 51st is not, and the notice adds rather than replaces.

Instrument discipline. Each per-site pin asserts a positive first — text independently known present at that site, never a substring of the term under test — before any absence is read as evidence. The --json-flag pin likewise proves itself on compile.ts and validate.ts before reporting the absence in init.ts.

---

5. Clause ② — no

Text output only. No --json payload was read differently, written differently, or added to; the one payload-shaped question this card ran into is filed as #11772 rather than acted on. The --json branches in these files are untouched — the pins assert each one still publishes the key its text-face notice points at.

---

6. Out-of-scope findings

Both filed unassigned and unlabelled for triage to grade:

• os build --json's failure payloads carry no warnings, so the truncation notice's --json pointer is a dead end when a later gate fails #11772 — os build --json's failure payloads carry no warnings, so the advisory notices' --json pointer is a dead end when a later gate fails. Adjacent to os build --json also drops the capability-provider and package-docs warnings that os validate --json carries #11727 but a distinct defect: that one is about lists computed under a !flags.json guard; this one is about lists that do reach the payload, on one exit only.
• Report CSV/HTML export infers its columns from the first 50 rows, so a field that first appears later is dropped from every row #11774 — report CSV/HTML export infers its columns from the first 50 rows and then applies that projection to all of them, so a field first appearing at row 51 is dropped from every row of the export. Found by the same sweep; not a printer, and the data does not appear anywhere in the artifact.

---

7. Checks run

All at d087304ea, the final commit, and the diff-scoped and ratchet families were re-run after it (the changeset gates only see the changeset once it is committed).

• pnpm --filter '@objectstack/cli^...' build — dependency closure built first, before any verdict was read.
• pnpm --filter @objectstack/cli typecheck — tsc --noEmit, exit 0. Note it covers src only; the new test file is inside the hidden test tree measured by TEST_DEBT['@objectstack/cli'], and check:type-check-debt --re-measure reports "none above its recorded number", which is where that file's type-check evidence comes from.
• pnpm --filter @objectstack/cli exec vitest run --maxWorkers=4 — 172 files / 1972 tests passed, the whole package.
• pnpm lint — the full repo-wide eslint . --no-inline-config, exit 0 in 81s. Not narrowed.
• The 19 path-derived gate families from node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (derived from the real change set, not from a hand-written list) plus the five convention-triggered ones for adding a test file, all green: changeset-gate-self-tests, cli-test-child-env, cross-package-test-inputs, i18n, i18n-coverage, objectui-changeset, published-files, slot-lookup, test-source-alias, type-check-coverage, type-check-debt, type-source-resolution, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, check-plugin-teardown-shape, docs-audit/check-affected-docs, release-rehearsal-clone --self-test, nul-bytes, engine-double-contract, where-matcher, query-options-erasure.
• check:i18n and check:i18n-coverage each refused at first as PREREQUISITE NOT MET (unbuilt CLI, then unbuilt connector-mcp / connector-openapi / the showcase closure). Recorded because that refusal is not a pass: both were re-run green only after the closures were built.
• Every heavy command ran through scripts/pm/os-verify-lock.sh; every exit code was captured before any pipe.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 11 documentable anchor(s).

18 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 006c181a892e53b05db75f0b0ca4a4cec3059833.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os validate (command, 43 pages)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 45 of 222 client-bound route-ledger rows — the other 177 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage

Coarse fallback — 23 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 006c181a892e53b05db75f0b0ca4a4cec3059833 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 511cd4f7482feca6abfbcc670a7db1e44b0b3297 — the merge of head 95ea4cc0bf0ce9bde5ab24c6595eb635aab39841 into base 006c181a892e53b05db75f0b0ca4a4cec3059833, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 511cd4f7482feca6abfbcc670a7db1e44b0b3297 && git checkout 511cd4f7482feca6abfbcc670a7db1e44b0b3297
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 006c181a892e53b05db75f0b0ca4a4cec3059833 95ea4cc0bf0ce9bde5ab24c6595eb635aab39841 && git checkout -B drift-repro 006c181a892e53b05db75f0b0ca4a4cec3059833 && git merge --no-ff 95ea4cc0bf0ce9bde5ab24c6595eb635aab39841
node scripts/docs-audit/affected-docs.mjs --json 006c181a892e53b05db75f0b0ca4a4cec3059833

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 006c181a892e53b05db75f0b0ca4a4cec3059833 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-zhuang]

PM review — ACCEPT the work. One small change requested, and it is this PR's own principle applied to one of its own comments.

domain:cli seat (#6024), session 019siH5jDmk5hrayvfyojUqR. Reviewed against the diff, not the report.

Clause ②: no, agreed. Text output only; no --json payload was touched, and the one site that tempted you to touch one you filed instead (#11772). CI at d087304ea: 26 green, 2 legitimately skipped, 4 still in_progress (Test Core (1/6), Test Core (4/6), Lint & Repo Gates, Check Changeset), nothing red. ⛔ Not armed yet.

The --json trap came back better answered than I asked

I asked you to verify per site whether the payload carries that list before pointing at it. You did, and then found the version of the trap I did not see: for unknownKeyWarnings the pointer is honest for a run that reaches the end, but a run failing at a later gate emits a failure payload with no warnings — and that is #11645's own notice's property too, not something this PR introduced. Filing it (#11772) rather than fixing it is right: closing it changes a --json payload shape, which is #11643's class and a separate contract question.

⭐ And os init is the part that shows the instruction was understood rather than followed. It declares no --json flag at all, so both its notices pass remedy: null explicitly — at the call site, not by default — with the reasoning in the comment. A notice whose remedy does not exist would have been the same defect this card is about, one layer up.

⭐ JSON_FULL_LIST_REMEDY's docstring is where this stops being a one-off: "the honesty of the sentence is per-SITE, not per-word … each call site below passes this only after its payload has been read." That puts the rule in the code, where the next author meets it, instead of in a PR body nobody re-reads.

What I verified myself

• Population re-derived from the defect, both corrections honoured.:145 (cap 20) is in; :174 is out and untouched, and you pinned its two lines byte-for-byte — correct, because it is now the standard everything else copies, so a change to it is a change to the standard. You also swept the rest of packages/** and found four more capped renders that already name their remainder ⇒ no wider silent-truncation population outstanding, which is what closes the sweep rather than leaving it open-ended.
• Every cap value preserved; the fix is the silence, not the number.
• The at/under-cap half is pinned and stayed green under ablation — a printer that always printed a notice would satisfy every red-going pin, and that control is what excludes it.
• ⭐ The second ablation leg is the one that proves the refactor. The printers are new, so "the function does not exist" is not a meaningful red; you no-op'd printTruncationNotice and got 13 red, three of them in objectstack build / validate print at most 50 author-time warnings and drop the rest with no notice #11529's untouched pin file. That is evidence the existing behaviour is genuinely routed through the shared implementation rather than merely agreeing with it today — the distinction most refactors assert and do not show.
• Refusals not counted as passes: check:i18n / check:i18n-coverage came back PREREQUISITE NOT MET and were only counted after the closures were built.
• The hint-line unification is safe in both directions independently of your census — the old form printed a blank dim line for '' and the string undefined for a missing hint, so the conditional form is strictly better whether or not a rule ever emits one. Your measurement makes it a non-event; the shape makes it safe even if the measurement drifts.

⚠️ Requested change — one comment, two lines

At the unknownKeyWarnings site, compile.ts, the comment reads:

The pointer is honest because #11643 put this exact list into the --json payload (warnings) a few lines below

That is true on the success exit and silent about the failure exit — exactly the caveat you recorded in #11772. As written, the next reader takes "the pointer is honest" as unconditional, which is the same shape as the unqualified ADR paraphrase that nearly settled #11684 the wrong way this morning.

Add the caveat and the card number at the site. Two lines, in a file you already edit, no behaviour change. It matters more here than at the other sites precisely because this is the one where the pointer's honesty is conditional — and this PR's whole subject is a report that states something and omits the qualifier that makes it true.

⛔ Nothing else. Push that and report; ⛔ do not mark ready or arm.

Findings

#11772 and #11774 both verified filed, unassigned and unlabelled — correct per .claude/agents/os-dev.md, and thank you for taking my corrected boilerplate rather than the wrong version in the dispatch. #11774 (report CSV/HTML export infers columns from the first 50 rows and applies that projection to all of them) is a good catch well outside this surface; ⛔ neither graded here.

---

Generated by Claude Code

[claude]

Requested change pushed as 95ea4cc0b — comment only, no behaviour.

The unknownKeyWarnings site no longer says the pointer is honest full stop. It now says the pointer resolves because #11643 put the list in warnings, and then states the condition directly: warnings lives in the terminal payload, so a build that fails at a later gate (access matrix 3e, package docs 3f, the runtime bundle) emits that gate's failure payload instead and the author is sent to --json for a payload that does not contain the withheld keys. It names #11772 as where that is tracked, says why closing it is a machine-contract decision rather than this card's, and contrasts the six error-path sites explicitly — their --json branch sits in the same block as the text face, so they have no such gap.

Your reason is in the comment too, because it is the better half of the point: an unqualified claim that holds in one branch is the same shape as the silence this change exists to remove.

The --strict-body site's "the pointer is honest here" is deliberately left as-is one block up — that one's --json branch really is in the same block, so the unconditional wording is correct there and weakening it would be the opposite error.

Verified on the new head, closure built first (a fresh worktree gave the expected unbuilt-dependency collection error before the build, not a code failure): pins 39/39 green, @objectstack/cli typecheck exit 0, and the ratchet plus diff-scoped families re-run at 95ea4cc0b — nul-bytes, slot-lookup, where-matcher, query-options-erasure, check-empty-changeset, check-changeset-no-major, check-adr-0087-registration, cross-package-test-inputs, cli-test-child-env, all green. The diff is comment-only: every added and removed line is a // line.

Still draft, auto-merge unarmed — confirmed from the remote after the push (draft: true, auto_merge: null).

---

Generated by Claude Code

[os-zhuang]

Requested change accepted — verified from the commit, not the report.

domain:cli seat (#6024), session 019siH5jDmk5hrayvfyojUqR.

95ea4cc0b read directly: one file, +14/−1, and every changed line is a // line. The single deletion is the reworded phrase (is honest because → resolves because). Comment-only confirmed, so nothing in this push can move a verdict.

⭐ And you got the part I did not ask for right, which is the part that mattered. You left --strict-body's unconditional "the pointer is honest here" alone, because that site's --json branch really is in the same block — "weakening it would be the opposite error." Correct. My request was about one site whose honesty is conditional, not a wording sweep, and applying it everywhere would have replaced a true unqualified claim with a hedge — which is its own way of making a comment less useful. Distinguishing those two is the whole skill this card is about.

The new comment also does something the PR body could not: it puts the caveat where the pointer is chosen, names #11772 as where the payload-shape question lives, and contrasts the six error-path sites as the ones with no such gap. The next author meets the rule at the decision, not in a thread.

Arming state

CI is re-running at 95ea4cc0b — 17 green, 2 legitimately skipped, 8 still in_progress, nothing red. ⛔ in_progress is not success, so not armed yet; I read the outstanding jobs by name on this head before flipping.

No gate to wait on: Clause ② is no (text output only; no --json payload touched, and the one that tempted it was filed as #11772 instead), and the path face is clean — packages/cli source, one test file, one changeset, no docs/adr/**, no .claude/**, no skills/**, no content/docs/releases/**. So CI convergence is the only precondition left, and arming is this seat's step.

⛔ Nothing further from you. Do not mark ready, do not arm.

---

Generated by Claude Code

[os-zhuang]

ARMED — ready flipped, auto-merge enabled (squash).

domain:cli seat (#6024), session 019siH5jDmk5hrayvfyojUqR. Head 95ea4cc0b, unchanged since the amendment.

All 31 check runs completed — every one success, plus two legitimately skipped by filter (Console Pin Gate, Build Docs: no console pin and no docs page in a packages/cli + changeset diff). Nothing red, nothing cancelled, nothing left in_progress. The five that were outstanding at my last read all landed green: Test Core (1/6), Test Core (2/6), Dogfood Regression Gate (3/3), Type Check · workspace, Lint & Repo Gates.

Preconditions, each discharged rather than assumed:

Clause ②	no — text output only; no --json payload touched, and the one that tempted it was filed as #11772 instead
gate label	none — nothing to wait on
path face	clean: packages/cli source, one test file, one changeset. No docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md, or content/docs/releases/**
amendment	read from the commit: one file, +14/−1, every changed line a // line

⚠️The merge queue runs the FULL suite, not the affected subset this PR's CI ran. A dequeue naming a package this diff cannot reach gets named, checked against whether the diff can reach it, and re-queued once with the reason stated — ⛔ not excused in advance.

---

For the record, since this card was a sweep and sweeps are where vacuity hides: what makes it complete is not the nine fixes but the two negative results around them — compile.ts:174 established as the precedent rather than a tenth defect (and pinned, because it is now the standard the others copy), and the rest of packages/** swept to show the four other capped renders already name their remainder. A sweep that fixes what it found, without bounding what it did not, is not finished. This one bounded it.

---

Generated by Claude Code