fix(#4294): reserve a full progress bar for 100% and give the render half one owner (#4473)

* fix(#4294): reserve a full progress bar for 100% and give the render half one owner

Six call sites each carried `Math.round((percent / 100) * width)` inline, and
every copy rounded to a full bar before the percent reached 100: from 95 up at
width 10, from 98 up at width 20. A project at 19/20 plans drew the same bar as
a shipped one beside a number that said otherwise, and an out-of-range percent
threw `RangeError` from the unguarded `'░'.repeat`.

ADR-3180 Decision 7 gave the completion-RATIO derivation one owner
(`clampPercentFromFraction`). This gives the RENDER half the same:
`progressBarFilledCells` / `renderProgressBar` in phase-lifecycle.cts, with the
`progress` table and bar renderers, the stats renderer, the gsd2 import writer,
and #4231's `formatProgressMachineSegment` (which now serves both STATE.md
writers) all drawing through it.

Contract: below 100 the fill is held one cell short of the width, so only the
saturating percents move (95-99 at width 10, 98-99 at width 20) and every other
value in 0-100 renders as before — pinned by an exhaustive comparison against
the legacy formula at both widths. Null / non-finite renders an empty bar;
out-of-range is clamped, never thrown.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012hbFn24VWaxJBw8DUWjAmU

* chore(#4294): set changeset fragment pr to 4473

* docs(#4294): correct the pre-fix inline call-site count to five

The kernel's doc comment said SIX call sites carried their own
`Math.round((percent / 100) * width)`. The base tree has five: three in
`commands.cts` plus one each in `gsd2-import.cts` and
`formatProgressMachineSegment`, the latter two using `/ 10` with the width
already substituted (`pct` and `clamped` respectively).

The six is #4294's count of consumers -- it counts `cmdStateUpdateProgress`
and `syncCore` separately, but #4231 had already routed both through
`formatProgressMachineSegment` (as it does `applyPostSyncPreservation`), so by
this branch's base they share one copy. The comment now states the tree's count
and records where the six comes from, so neither number reads as an error
later.

Comment-only; no behaviour change, and no change to compiled output.

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Tom Boucher <trekkie@nomorestars.com>

src/commands.cts

@@ -58,7 +58,7 @@ import modelProfiles = require('./model-profiles.cjs');
 const { MODEL_PROFILES, VALID_PHASE_TYPES } = modelProfiles;
 import { formatGsdSlash, resolveRuntime } from './runtime-slash.cjs';
 import { realClock } from './clock.cjs';
-import { clampPercent } from './phase-lifecycle.cjs';
+import { clampPercent, renderProgressBar } from './phase-lifecycle.cjs';
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import planScanMod = require('./plan-scan.cjs');
 const { scanPhasePlans } = planScanMod;
@@ -2772,9 +2772,7 @@ function cmdProgressRender(cwd: string, format: string | undefined, raw: boolean
 
   if (format === 'table') {
     // Render markdown table
-    const barWidth = 10;
-    const filled = percent === null ? 0 : Math.round((percent / 100) * barWidth);
-    const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
+    const bar = renderProgressBar(percent, 10);
     const percentSuffix = percent === null ? '' : ` (${percent}%)`;
     let out = `# ${milestone?.version ?? ''} ${milestone?.name ?? ''}\n\n`;
     out += `**Progress:** [${bar}] ${totalSummaries}/${totalPlans} plans${percentSuffix}\n\n`;
@@ -2785,9 +2783,7 @@ function cmdProgressRender(cwd: string, format: string | undefined, raw: boolean
     }
     output({ rendered: out }, raw, out);
   } else if (format === 'bar') {
-    const barWidth = 20;
-    const filled = percent === null ? 0 : Math.round((percent / 100) * barWidth);
-    const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
+    const bar = renderProgressBar(percent, 20);
     const percentSuffix = percent === null ? '' : ` (${percent}%)`;
     const text = `[${bar}] ${totalSummaries}/${totalPlans} plans${percentSuffix}`;
     output({ bar: text, percent, completed: totalSummaries, total: totalPlans }, raw, text);
@@ -3256,9 +3252,7 @@ function cmdStats(cwd: string, format: string | undefined, raw: boolean): void {
   };
 
   if (format === 'table') {
-    const barWidth = 10;
-    const filled = percent === null ? 0 : Math.round((percent / 100) * barWidth);
-    const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
+    const bar = renderProgressBar(percent, 10);
     let out = `# ${milestone?.version ?? ''} ${milestone?.name ?? ''} — Statistics\n\n`;
     const percentSuffix = percent === null ? '' : ` (${percent}%)`;
     out += `**Progress:** [${bar}] ${completedPhases}/${phases.length} phases${percentSuffix}\n`;

src/gsd2-import.cts

@@ -24,7 +24,7 @@ import path from 'node:path';
 import { platformWriteSync } from './shell-command-projection.cjs';
 import { formatGsdSlash, resolveRuntime } from './runtime-slash.cjs';
 import { realClock } from './clock.cjs';
-import { clampPercent } from './phase-lifecycle.cjs';
+import { clampPercent, renderProgressBar } from './phase-lifecycle.cjs';
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- core-utils.cjs is an export= CommonJS module
 import coreUtilsMod = require('./core-utils.cjs');
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -382,8 +382,7 @@ function buildStateMd(phaseMap: PhaseMapEntry[]): string {
   const currentSlug = currentEntry ? slugify(currentEntry.slice.title) : 'complete';
   const status = currentEntry ? 'Ready to plan' : 'All phases complete';
 
-  const filled = Math.round(pct / 10);
-  const bar = `[${'█'.repeat(filled)}${'░'.repeat(10 - filled)}]`;
+  const bar = `[${renderProgressBar(pct, 10)}]`;
   const today = realClock.localToday();
 
   return [

src/phase-lifecycle.cts

@@ -151,3 +151,61 @@ export function clampPercent(completed: number, total: number): number {
   if (!total || total <= 0) return 0;
   return clampPercentFromFraction(completed / total);
 }
+
+/**
+ * How many cells of a `width`-cell progress bar are filled for `percent`.
+ *
+ * #4294: the RENDER half's kernel — the counterpart of `clampPercentFromFraction`
+ * one layer down. That function owns `fraction -> integer percent`; this one
+ * owns `integer percent -> filled cells`, and is the single place that rounding
+ * is expressed. Five inline copies of the rounding carried it before this
+ * change — three in `commands.cts`, and one each in `gsd2-import.cts` and
+ * `formatProgressMachineSegment` here; the latter two used `/ 10` with the
+ * width already substituted (`pct` in `gsd2-import.cts`, `clamped` in the
+ * formatter). (#4294 counts SIX call sites because it counts
+ * `cmdStateUpdateProgress` and `syncCore` separately; #4231 had already routed
+ * both through `formatProgressMachineSegment` — as it does
+ * `applyPostSyncPreservation` — so by this branch's base they share one copy.)
+ * Every copy saturated: at width 10 that rounds to a full bar from 95 up, at
+ * width 20 from 98 up, so a project at 19/20 plans drew the same bar as a
+ * shipped one beside a number that said otherwise.
+ *
+ * Contract:
+ *   - A FULL bar is reserved for an actual 100. Below 100 the fill is held one
+ *     cell short of the width. This is the only departure from the old formula:
+ *     at width 10 exactly 95-99 move (10 -> 9), at width 20 exactly 98-99
+ *     (20 -> 19); every other percent in 0-100 rounds as before.
+ *   - `null` / `undefined` / non-finite renders an empty bar, matching the
+ *     `percent === null ? 0 : ...` guard the `progress` renderers already carried.
+ *   - Out-of-range input is clamped to 0-100 before rounding, so the count is
+ *     always within `[0, width]` and a `'░'.repeat(width - filled)` can never
+ *     be handed a negative count (the old inline form threw `RangeError` at
+ *     120%). A non-positive width yields 0.
+ *
+ * Callers wanting the glyph run call `renderProgressBar`; this is exported so
+ * the rounding rule can be pinned directly against the legacy curve.
+ */
+export function progressBarFilledCells(percent: number | null | undefined, width: number): number {
+  const cells = Number.isFinite(width) && width > 0 ? Math.floor(width) : 0;
+  if (cells === 0) return 0;
+  if (typeof percent !== 'number' || !Number.isFinite(percent)) return 0;
+  const clamped = Math.max(0, Math.min(100, percent));
+  if (clamped >= 100) return cells;
+  // Scale by the WIDTH, not by 100 — this is cells-from-percent, not the
+  // completion-ratio derivation lint-completion-ratio-drift.cjs guards.
+  const rounded = Math.round((clamped / 100) * cells);
+  return Math.min(rounded, cells - 1);
+}
+
+/**
+ * Render the glyph run of a `width`-cell progress bar for `percent` —
+ * `'█'` for each filled cell, `'░'` for the rest, always exactly `width`
+ * glyphs (an empty string for a non-positive width). Brackets, the printed
+ * percent and any suffix stay with the caller; the fill rule is
+ * `progressBarFilledCells` (#4294).
+ */
+export function renderProgressBar(percent: number | null | undefined, width: number): string {
+  const filled = progressBarFilledCells(percent, width);
+  const cells = Number.isFinite(width) && width > 0 ? Math.floor(width) : 0;
+  return '█'.repeat(filled) + '░'.repeat(cells - filled);
+}

src/state-transition.cts

@@ -20,7 +20,7 @@ import { stateReplaceField, stateExtractField, stateReplaceFieldIfTemplate, stat
 import { KNOWN_TEMPLATE_DEFAULTS, toFiniteNumber, computeProgressPercent } from './state-document.cjs';
 import { tokenizeHeadings } from './markdown-sectionizer.cjs';
 import type { HeadingToken } from './markdown-sectionizer.cjs';
-import { deriveProgressFromRoadmap, clampPercent, clampPercentFromFraction } from './phase-lifecycle.cjs';
+import { deriveProgressFromRoadmap, clampPercent, clampPercentFromFraction, renderProgressBar } from './phase-lifecycle.cjs';
 import { escapeRegex } from './pattern.cjs';
 // #4129: the completion-ratio kernel for the resync-arm ratchet's percent
 // (planning-scope's SCOPE — state-document's own dependency, no cycle here:
@@ -38,12 +38,13 @@ export function formatProgressMachineSegment(percent: number): string {
   // ADR-3180 Decision 7: rounding and the 100 ceiling belong to the
   // completion-ratio kernel. The floor is added here because this helper is
   // also fed persisted frontmatter values (hand-editable, unlike the
-  // count-shaped entries into that kernel), and `'░'.repeat` throws on a
-  // negative count. Bar and printed percent use the clamped value so the two
-  // halves of the segment can never disagree.
+  // count-shaped entries into that kernel). Bar and printed percent use the
+  // clamped value so the two halves of the segment can never disagree.
+  // #4294: the CELL count is the render kernel's — `renderProgressBar` holds a
+  // sub-100 percent one cell short of full, so `[██████████]` beside `95%`
+  // cannot recur here as a seventh inline copy of the rounding.
   const clamped = Math.max(0, clampPercentFromFraction(percent / 100));
-  const filled = Math.round(clamped / 10);
-  return `[${'█'.repeat(filled)}${'░'.repeat(10 - filled)}] ${clamped}%`;
+  return `[${renderProgressBar(clamped, 10)}] ${clamped}%`;
 }
 
 // Consumers (a future STATE.md writer that bypasses all three reintroduces the