@aemonge-dev/pi-stardeck 0.14.0 → 0.15.0

package/packages/status/README.md

@@ -57,49 +57,36 @@ The provider uses the installed OpenSpec CLI and reads only each listed change's
 5. The task artifact is read once per refresh to recover labels such as `3.8` and kinds
    such as Story, Spike, Lab, or Hack.
 
-The session focus takes precedence over configured `openspec.change`, which takes
-precedence over `PI_OPENSPEC_CHANGE`. Configuration and environment values can select a
-change for collection/debugging, but they do not create session task focus or expose an
-active OpenSpec footer by themselves.
+The focused change no longer lives in session state: the cockpit reads the
+room aim (`openspec/.focus`) directly and prints its fields verbatim.
 
-## Session focus and terminal title
+active OpenSpec footer by themselves.
 
-A Pi session has zero or one explicit OpenSpec task focus and an independent
-ephemeral Session Work state. Display priority is OpenSpec
-Task → Session Work → safe direct fallback. OpenSpec focus clears active Session
-Work when acquired, preventing hidden or stale work from resurfacing later.
+## Room aim and terminal title
 
-Session Work is a legacy surface: its writer tool and `/work` command are retired, and
-only old sessions' versioned custom entries remain, restored fail-soft on the active
-Pi session branch (never a repository status file). OpenSpec focus is stored the same
-way and supports this lifecycle:
+The focused change is the Human's room aim — `pios-gate <slug>` writes
+`openspec/.focus`, the cockpit reads it on every refresh and renders its five
+fields verbatim on the right work tile:
 
 ```text
-/openspec-focus set <change> <task>
-/openspec-focus validate
-/openspec-focus replace <change> <task>
-/openspec-focus clear
+{change} ⟩ {artifact_name} {artifact-idx} › {task} ⟩ {next-step}
 ```
 
-When no OpenSpec portfolio is available, the matching row-one footer fallback is the
-compact `▶ Focus` or `◇ Validate`; an entirely empty
-project uses ` no OpenSpec`. The detailed Session Work intent remains in the header
-instead of being duplicated in the footer. Active and validation states also replace the
-fallback terminal title. Reload, resume, and tree navigation restore the newest valid
-branch entry. The agent-callable `openspec_focus` tool shares the command's `status`,
-safeguarded `set`, deliberate `replace`, validating `validate`, and persistent `clear`
-transitions; the `awaitingValidation` flag marks a focused task as awaiting Human
-validation and auto-clears on the next `set`, `replace`, or `clear`. The
-retired `work_focus`, `stage`, and `title` instruments are gone: stages
-derive from events and Taskflow phases, the focus row falls back to the
-native session name (named by `pi-title`) and then to legacy `session-subject`
-entries from old sessions, read defensively and fail-soft.
+Read as-is, printed as-is: no prefixes, no relabeling. A missing field drops
+its segment; absence never becomes zero; an aim without a change slug is no
+aim at all. The agent never writes the file — it is the Human's word, written
+by their terminal verbs.
+
+Session Work and the `openspec_focus` tool are retired instruments: old
+sessions' versioned custom entries restore fail-soft and carry no writers.
+The focus row falls back to the native session name (named by `pi-title`)
+and then to legacy `session-subject` entries from old sessions, read
+defensively and fail-soft.
 
 Global routing belongs to native Ramona policy rather than this status package. This
 package does not inject parent routing prompts, block parent tools, create Session Work
 for a global route, or promote a raw request into OpenSpec focus. It continues to own
-branch-local OpenSpec and Session Work state, commands, restoration, titles, and footer
-publication.
+branch-local Session Work restoration, commands, titles, and footer publication.
 
 The header projection uses the rich lifecycle `understanding`, `working`, `waiting`,
 `assuring`, `learning`, `answering`, `blocked`, `listening`, or `aborted`. It separately
@@ -318,8 +305,7 @@ configuration directory in this installation). This repository keeps the source
 ```
 
 Unknown or invalid fields are ignored and reported by the debug command; they do not
-prevent Pi from starting. `openspec.change` is an explicit collection target, not a
-session-scoped task focus.
+prevent Pi from starting.
 
 ## Commands
 

package/packages/status/index.ts

@@ -7,18 +7,14 @@ import { promises as fs, watch } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import {
   formatActiveWorkTitle,
-  type OpenSpecFocus,
-  parseOpenSpecFocus,
-  restoreOpenSpecFocus,
   restoreSessionSubject,
-  sameOpenSpecFocus,
   sameSessionSubject,
   type SessionSubject,
 } from './src/active-work.ts';
 import { collectDiagnostics } from './src/diagnostics.ts';
 import { loadConfig } from './src/config.ts';
-import { resolveGateAct } from './src/gate-act.ts';
-import { collectOpenSpec, collectOpenSpecOverview } from './src/openspec.ts';
+import { readRoomAim } from './src/room-aim.ts';
+import { collectOpenSpecOverview } from './src/openspec.ts';
 import { collectOrchestration } from './src/orchestration.ts';
 import {
   buildHeaderStatusEvent,
@@ -171,15 +167,6 @@ class GalacticaStatusRuntime {
   private openSpecFeedback: OpenSpecFeedback | undefined;
   private openSpecOverview: OpenSpecOverview | undefined;
   private openSpecProjectDetected: boolean | undefined;
-  private focus: OpenSpecFocus;
-  /** Publisher-owned timestamp of the current focus fact — seeded at
-   *  construction, refreshed on every accepted focus change; staleness
-   *  compares it against the change directory's file truth. */
-  private focusAt: number | undefined;
-  /** The gate's relayed act line for the focused change — commentary
-   *  beside the declared focus, never a replacement; cleared whenever
-   *  the focus moves so stale gate truth never survives a switch. */
-  private gateAct: { change: string; line?: string } | undefined;
   private subject: SessionSubject;
   private sessionName: string | undefined;
   private diagnosticsPath: string | undefined;
@@ -208,30 +195,21 @@ class GalacticaStatusRuntime {
     pi: ExtensionAPI,
     ctx: SessionContext,
     publisher: FancyFooterPublisher,
-    focus: OpenSpecFocus,
     subject: SessionSubject,
     sessionName: string | undefined,
   ) {
     this.pi = pi;
     this.ctx = ctx;
     this.publisher = publisher;
-    this.focus = focus;
     this.subject = subject;
     this.sessionName = sessionName;
-    this.focusAt = Date.now();
-    const restoredAwaitingValidation =
-      focus.mode === 'task' && focus.awaitingValidation;
-    this.liveLifecycle = restoredAwaitingValidation ? 'waiting' : 'listening';
-    this.liveActivity = restoredAwaitingValidation
-      ? { kind: 'awaiting-validation' }
-      : undefined;
+    this.liveLifecycle = 'listening';
     this.store = new AtomicStatusStore({
       cwd: ctx.cwd,
       projectRoot: ctx.cwd,
       configPath: '',
     });
     const seededAt = Date.now();
-    this.recordEvent({ type: 'focus/openspec', at: seededAt, focus });
     this.recordEvent({ type: 'focus/subject', at: seededAt, subject });
   }
 
@@ -384,7 +362,6 @@ class GalacticaStatusRuntime {
     const generation = ++this.generation;
     if (!this.loadedConfig || this.stopped) return;
     const config = this.loadedConfig.config;
-    const focus = this.focus;
     const at = Date.now();
     let projectRoot = await detectProjectRoot(this.ctx.cwd, this.runner);
 
@@ -393,6 +370,9 @@ class GalacticaStatusRuntime {
       openSpecEnabled && (await pathIsDirectory(join(projectRoot, 'openspec')));
     let openSpecOverview: RefreshOutcome<OpenSpecOverview> = { kind: 'absent' };
     let openspec: RefreshOutcome<OpenSpecState> = { kind: 'absent' };
+    // The per-change collector retired with the focus store: the room aim
+    // carries the tile fields verbatim; the overview feeds the rest.
+    void openspec;
 
     if (hasOpenSpecProject) {
       openSpecOverview = await this.outcome('openspec', () =>
@@ -403,31 +383,6 @@ class GalacticaStatusRuntime {
       }
     }
 
-    if (focus.mode === 'none') {
-      const passiveChange = config.openspec.change ?? process.env.PI_OPENSPEC_CHANGE;
-      if (passiveChange) {
-        openspec = await this.outcome('openspec', () =>
-          collectOpenSpec({
-            cwd: projectRoot,
-            runner: this.runner,
-            configuredChange: passiveChange,
-            now: at,
-          }),
-        );
-        if (openspec.kind === 'success') projectRoot = openspec.value.projectRoot;
-      }
-    } else {
-      openspec = await this.outcome('openspec', () =>
-        collectOpenSpec({
-          cwd: projectRoot,
-          runner: this.runner,
-          configuredChange: focus.change,
-          now: at,
-        }),
-      );
-      if (openspec.kind === 'success') projectRoot = openspec.value.projectRoot;
-    }
-
     const [diagnostics, orchestration] = await Promise.all([
       !config.enabled || !config.diagnostics.enabled
         ? Promise.resolve<RefreshOutcome<DiagnosticsState>>({ kind: 'absent' })
@@ -457,26 +412,9 @@ class GalacticaStatusRuntime {
           }),
     ]);
 
-    if (
-      this.stopped ||
-      generation !== this.generation ||
-      !sameOpenSpecFocus(focus, this.focus)
-    ) {
+    if (this.stopped || generation !== this.generation) {
       return;
     }
-    // The gate act is focus-owned commentary: resolved only for a task
-    // focus inside an OpenSpec project, after the commit guard, so a
-    // superseded refresh never spends a probe on stale truth.
-    if (focus.mode === 'task' && hasOpenSpecProject) {
-      this.gateAct = {
-        change: focus.change,
-        line: await resolveGateAct({
-          change: focus.change,
-          projectRoot,
-          runner: this.runner,
-        }),
-      };
-    }
     const previous = this.store.get();
     this.updateRefreshHealth(
       'openspec',
@@ -499,19 +437,18 @@ class GalacticaStatusRuntime {
     } else if (openSpecOverview.kind === 'absent') {
       this.openSpecOverview = undefined;
     }
-    this.openSpecFeedback =
-      !hasOpenSpecProject || focus.mode === 'task'
-        ? undefined
-        : openSpecOverview.kind === 'error'
-          ? 'unavailable'
-          : openSpecOverview.kind === 'success' &&
-              openSpecOverview.value.actionableChanges > 0
-            ? 'no-focus'
-            : 'clear';
+    this.openSpecFeedback = !hasOpenSpecProject
+      ? undefined
+      : openSpecOverview.kind === 'error'
+        ? 'unavailable'
+        : openSpecOverview.kind === 'success' &&
+            openSpecOverview.value.actionableChanges > 0
+          ? 'no-focus'
+          : 'clear';
     this.store.applyRefresh({
       projectRoot,
       at,
-      openspec,
+      openspec: { kind: 'absent' },
       diagnostics,
       orchestration,
     });
@@ -605,21 +542,12 @@ class GalacticaStatusRuntime {
   private publish(): void {
     if (this.stopped) return;
     const snapshot = this.store.get();
-    // Builders read focus facts through the snapshot layer (recordEvent stores
-    // the same object references), so output stays byte-identical while the
-    // ledger becomes the feeding seam.
-    const focus = this.cockpitFacts.openSpec;
     const subject = this.cockpitFacts.subject;
     const title = this.currentTitleState(snapshot);
-    const focusedOpenSpec =
-      focus.mode === 'task' && snapshot.openspec?.changeId === focus.change
-        ? snapshot.openspec
-        : null;
     const widgets = buildWidgetSnapshots(
-      { ...snapshot, openspec: focusedOpenSpec },
+      { ...snapshot, openspec: null },
       {
-        focusedTaskId: focus.mode === 'task' ? focus.taskId : undefined,
-        openSpecFeedback: focus.mode === 'none' ? this.openSpecFeedback : undefined,
+        openSpecFeedback: this.openSpecFeedback,
         openSpecOverview: this.openSpecOverview,
         openSpecProjectDetected: this.openSpecProjectDetected,
       },
@@ -628,8 +556,7 @@ class GalacticaStatusRuntime {
     this.pi.events.emit(
       GALACTICA_HEADER_CHANNEL,
       buildHeaderStatusEvent(widgets, {
-        openSpec: focusedOpenSpec,
-        focusedTaskId: focus.mode === 'task' ? focus.taskId : undefined,
+        openSpec: null,
         subject,
         orchestration: snapshot.orchestration,
         lifecycle: this.liveLifecycle,
@@ -653,11 +580,8 @@ class GalacticaStatusRuntime {
     const facts = this.cockpitFacts;
     // The left title is Human-owned — session name, subject, directory —
     // never openspec text (truthful-rendered-state law 2026-11-10); the
-    // gate act rides the work slot for the right-side tile.
-    const gateAct =
-      facts.openSpec.mode === 'task' && this.gateAct?.change === facts.openSpec.change
-        ? this.gateAct.line
-        : undefined;
+    // right tile prints the room aim verbatim (observe-room-aim law).
+    const aim = readRoomAim(snapshot.projectRoot);
     const subjectTitle = formatActiveWorkTitle({
       subject: facts.subject,
       ...(this.sessionName ? { sessionName: this.sessionName } : {}),
@@ -666,11 +590,8 @@ class GalacticaStatusRuntime {
     });
     return buildTitleState({
       subject: { state: 'set', title: subjectTitle },
-      focus: facts.openSpec,
-      openspec: snapshot.openspec,
+      aim,
       activity: this.titleActivity.current(),
-      focusAt: this.focusAt,
-      ...(gateAct ? { gateAct } : {}),
     });
   }
 
@@ -684,10 +605,6 @@ class GalacticaStatusRuntime {
     return snapshotFromFacts(this.cockpitFacts, this.cockpitVersion);
   }
 
-  currentFocus(): OpenSpecFocus {
-    return this.focus;
-  }
-
   currentSubject(): SessionSubject {
     return this.subject;
   }
@@ -704,24 +621,6 @@ class GalacticaStatusRuntime {
     this.setLiveProjection('understanding', { kind: 'understanding' });
   }
 
-  setFocus(focus: OpenSpecFocus): void {
-    if (sameOpenSpecFocus(this.focus, focus)) return;
-    this.focus = focus;
-    this.focusAt = Date.now();
-    if (focus.mode !== 'task' || this.gateAct?.change !== focus.change) {
-      this.gateAct = undefined;
-    }
-    this.recordEvent({ type: 'focus/openspec', at: Date.now(), focus });
-    this.store.clearOpenSpec();
-    if (focus.mode === 'task' && focus.awaitingValidation) {
-      this.setLiveProjection('waiting', { kind: 'awaiting-validation' });
-    } else if (focus.mode === 'none') {
-      this.setLiveProjection('listening');
-    }
-    this.publish();
-    this.launch(this.refresh(false), 'openspec');
-  }
-
   setSubject(subject: SessionSubject): void {
     if (sameSessionSubject(this.subject, subject)) return;
     this.subject = subject;
@@ -904,10 +803,6 @@ class GalacticaStatusRuntime {
       this.publish();
       return;
     }
-    if (this.focus.mode === 'task') {
-      this.setLiveProjection('waiting', { kind: 'awaiting-validation' });
-      return;
-    }
     this.setLiveProjection('listening');
   }
 
@@ -932,13 +827,10 @@ class GalacticaStatusRuntime {
     );
     lines.push(
       snapshot.openspec
-        ? `OpenSpec focus: ${formatOpenSpec(
-            snapshot.openspec,
-            this.focus.mode === 'task' ? this.focus.taskId : null,
-          )}`
+        ? `OpenSpec: ${formatOpenSpec(snapshot.openspec)}`
         : this.openSpecFeedback
-          ? `OpenSpec focus: ${this.openSpecFeedback}`
-          : 'OpenSpec focus: none',
+          ? `OpenSpec: ${this.openSpecFeedback}`
+          : 'OpenSpec: no aim',
     );
     lines.push(
       snapshot.diagnostics
@@ -960,7 +852,6 @@ class GalacticaStatusRuntime {
         projectRoot: snapshot.projectRoot,
         configPath: snapshot.configPath,
         configWarnings: snapshot.configWarnings,
-        focus: this.focus,
         openSpecFeedback: this.openSpecFeedback ?? null,
         openSpecOverview: this.openSpecOverview ?? null,
         detected: {
@@ -1011,30 +902,12 @@ export default function galacticaStatus(pi: ExtensionAPI): void {
     }
   });
 
-  // work-state owns focus writes and emits `focus-changed` after each
-  // successful one (pi.events); the renderer subscribes for immediate
-  // repaint (pure-renderer-split Slice 2).
-  const stopFocusRepaint = pi.events.on('focus-changed', (data: unknown) => {
-    const focus = parseOpenSpecFocus(data);
-    if (!focus) return;
-    runtime?.setFocus(focus);
-    runtime?.settle();
-  });
-
   pi.on('session_start', (_event, ctx) => {
     runtime?.stop();
     const branch = ctx.sessionManager.getBranch();
-    const focus = restoreOpenSpecFocus(branch);
     const subject = restoreSessionSubject(branch);
     const sessionName = pi.getSessionName() ?? ctx.sessionManager.getSessionName();
-    runtime = new GalacticaStatusRuntime(
-      pi,
-      ctx,
-      publisher,
-      focus,
-      subject,
-      sessionName,
-    );
+    runtime = new GalacticaStatusRuntime(pi, ctx, publisher, subject, sessionName);
     runtime.start();
   });
 
@@ -1044,7 +917,6 @@ export default function galacticaStatus(pi: ExtensionAPI): void {
 
   pi.on('session_tree', (_event, ctx) => {
     const branch = ctx.sessionManager.getBranch();
-    runtime?.setFocus(restoreOpenSpecFocus(branch));
     runtime?.setSubject(restoreSessionSubject(branch));
     runtime?.settle();
   });
@@ -1131,7 +1003,6 @@ export default function galacticaStatus(pi: ExtensionAPI): void {
     runtime = undefined;
     publisher.removeAll();
     stopReady();
-    stopFocusRepaint();
   });
 
   pi.registerCommand('galactica-status', {

package/packages/status/src/active-work.ts

@@ -1,19 +1,7 @@
 import { basename } from 'node:path';
 
-export const OPEN_SPEC_FOCUS_ENTRY_TYPE = 'galactica-status.openspec-focus.v1';
 export const SESSION_SUBJECT_ENTRY_TYPE = 'galactica-status.session-subject.v1';
 
-export type TaskOpenSpecFocus = {
-  mode: 'task';
-  change: string;
-  taskId: string;
-  awaitingValidation: boolean;
-};
-
-export type OpenSpecFocus = { mode: 'none' } | TaskOpenSpecFocus;
-
-export const NO_OPEN_SPEC_FOCUS: OpenSpecFocus = { mode: 'none' };
-
 export type SessionSubject = { state: 'clear' } | { state: 'set'; title: string };
 
 export const NO_SESSION_SUBJECT: SessionSubject = { state: 'clear' };
@@ -42,29 +30,6 @@ function explicitId(value: unknown): string | undefined {
   return normalized || undefined;
 }
 
-export function taskFocus(
-  change: unknown,
-  taskId: unknown,
-  awaitingValidation?: unknown,
-): TaskOpenSpecFocus | undefined {
-  const normalizedChange = explicitId(change);
-  const normalizedTaskId = explicitId(taskId);
-  if (!normalizedChange || !normalizedTaskId) return undefined;
-  return {
-    mode: 'task',
-    change: normalizedChange,
-    taskId: normalizedTaskId,
-    awaitingValidation: awaitingValidation === true,
-  };
-}
-
-export function parseOpenSpecFocus(value: unknown): OpenSpecFocus | undefined {
-  if (!isRecord(value)) return undefined;
-  if (value.mode === 'none') return NO_OPEN_SPEC_FOCUS;
-  if (value.mode !== 'task') return undefined;
-  return taskFocus(value.change, value.taskId, value.awaitingValidation);
-}
-
 export function sessionSubject(
   state: unknown,
   title?: unknown,
@@ -84,22 +49,6 @@ export function parseSessionSubject(value: unknown): SessionSubject | undefined
   return sessionSubject(value.state, value.title);
 }
 
-export function restoreOpenSpecFocus(entries: readonly unknown[]): OpenSpecFocus {
-  for (let index = entries.length - 1; index >= 0; index -= 1) {
-    const entry = entries[index];
-    if (
-      !isRecord(entry) ||
-      entry.type !== 'custom' ||
-      entry.customType !== OPEN_SPEC_FOCUS_ENTRY_TYPE
-    ) {
-      continue;
-    }
-    const focus = parseOpenSpecFocus(entry.data);
-    if (focus) return focus;
-  }
-  return NO_OPEN_SPEC_FOCUS;
-}
-
 export function restoreSessionSubject(entries: readonly unknown[]): SessionSubject {
   for (let index = entries.length - 1; index >= 0; index -= 1) {
     const entry = entries[index];
@@ -116,39 +65,6 @@ export function restoreSessionSubject(entries: readonly unknown[]): SessionSubje
   return NO_SESSION_SUBJECT;
 }
 
-export function taskflowRunFocus(input: unknown): TaskOpenSpecFocus | undefined {
-  if (!isRecord(input) || input.action !== 'run' || !isRecord(input.args)) {
-    return undefined;
-  }
-  const focus = taskFocus(input.args.change, input.args.task);
-  return focus && focus.change !== 'none' && focus.taskId !== 'none'
-    ? focus
-    : undefined;
-}
-
-/** Task identity (mode · change · taskId) — the replace-safeguard's
- *  question; the validation flag is state, not identity. */
-export function sameTaskFocus(left: OpenSpecFocus, right: OpenSpecFocus): boolean {
-  if (left.mode !== right.mode) return false;
-  return (
-    left.mode === 'none' ||
-    (right.mode === 'task' &&
-      left.change === right.change &&
-      left.taskId === right.taskId)
-  );
-}
-
-export function sameOpenSpecFocus(left: OpenSpecFocus, right: OpenSpecFocus): boolean {
-  if (left.mode !== right.mode) return false;
-  return (
-    left.mode === 'none' ||
-    (right.mode === 'task' &&
-      left.change === right.change &&
-      left.taskId === right.taskId &&
-      left.awaitingValidation === right.awaitingValidation)
-  );
-}
-
 export function sameSessionSubject(
   left: SessionSubject,
   right: SessionSubject,

package/packages/status/src/config.ts

@@ -13,7 +13,6 @@ export const DEFAULT_CONFIG: GalacticaStatusConfig = {
   enabled: true,
   openspec: {
     enabled: true,
-    change: null,
   },
   diagnostics: {
     enabled: true,
@@ -126,7 +125,7 @@ export function parseConfig(value: unknown): {
   const diagnostics = isRecord(value.diagnostics) ? value.diagnostics : {};
   const orchestration = isRecord(value.orchestration) ? value.orchestration : {};
 
-  unknownKeys(openspec, ['enabled', 'change'], 'openspec', warnings);
+  unknownKeys(openspec, ['enabled'], 'openspec', warnings);
   unknownKeys(
     diagnostics,
     [
@@ -148,7 +147,6 @@ export function parseConfig(value: unknown): {
       enabled: booleanValue(value.enabled, DEFAULT_CONFIG.enabled),
       openspec: {
         enabled: booleanValue(openspec.enabled, DEFAULT_CONFIG.openspec.enabled),
-        change: nullableString(openspec.change, DEFAULT_CONFIG.openspec.change),
       },
       diagnostics: {
         enabled: booleanValue(diagnostics.enabled, DEFAULT_CONFIG.diagnostics.enabled),

package/packages/status/src/ledger.ts

@@ -5,7 +5,7 @@ import type {
   RunSpan,
   StageValue,
 } from './types.ts';
-import type { OpenSpecFocus, SessionSubject } from './active-work.ts';
+import type { SessionSubject } from './active-work.ts';
 
 /**
  * Append-only event ledger for the cockpit status core.
@@ -17,7 +17,6 @@ import type { OpenSpecFocus, SessionSubject } from './active-work.ts';
  */
 
 export const LEDGER_EVENT_TYPES = [
-  'focus/openspec',
   'focus/subject',
   'run/start',
   'run/stage',
@@ -31,11 +30,6 @@ export const LEDGER_EVENT_TYPES = [
 export type LedgerEventType = (typeof LEDGER_EVENT_TYPES)[number];
 
 export type LedgerEvent =
-  | {
-      type: 'focus/openspec';
-      at: number;
-      focus: OpenSpecFocus;
-    }
   | { type: 'focus/subject'; at: number; subject: SessionSubject }
   | { type: 'run/start'; at: number; span: RunSpan }
   | { type: 'run/stage'; at: number; id: string; stage: StageValue; declared: boolean }

package/packages/status/src/openspec.ts

@@ -270,7 +270,7 @@ export function parseApplyInstructions(value: unknown): ApplyInstructionsResult
         complete: finiteNumber(value.progress.complete),
       }
     : undefined;
-  // A blocked apply (mid-ladder, artifacts missing) reports zero progress;
+  // A blocked apply (part-way through, artifacts missing) reports zero progress;
   // those zeros must never shadow the honest `openspec list` counts.
   const progress =
     state !== 'blocked' && (reportedProgress?.total ?? 0) > 0
@@ -550,7 +550,7 @@ export async function collectOpenSpec(options: {
   // tile at 0/N (simplify-deck-defaults). CLI progress and list counts
   // remain fallbacks; the blocked-apply zero-guard stays for the
   // no-tasks case.
-  // File-truth ladder: checkbox tasks first, then done/total artifacts
+  // File-truth precedence: checkbox tasks first, then done/total artifacts
   // (file presence via `openspec status`) — CLI task opinion cannot count
   // custom schemas and pins 0/N (truthful-rendered-state). With neither
   // readable, counts stay absent — absence never becomes zero.