@aemonge-dev/pi-stardeck 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aemonge-dev/pi-stardeck",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "A Vim- and tmux-inspired command deck for Pi",
   "type": "module",
   "keywords": [

package/packages/pi-stardeck/src/activity-age.ts

@@ -66,7 +66,7 @@ function standardActivityAge(ageMs: number): string {
   return `${Math.min(99, Math.floor(hours / 24))}d`;
 }
 
-function compactActivityAge(ageMs: number): string {
+export function compactActivityAge(ageMs: number): string {
   const age = boundedAge(ageMs);
   const seconds = Math.floor(age / 1_000);
   if (seconds < 100) return `${seconds}s`;

package/packages/pi-stardeck/src/deck.ts

@@ -163,10 +163,6 @@ function wrapFocus(text: string, width: number, maximumLines: number): string[]
   return lines.slice(0, maximumLines);
 }
 
-function mirrorKey(value: string): string {
-  return value.toLowerCase().replace(/[^a-z0-9]/gu, '');
-}
-
 function bandWrap(
   content: string,
   width: number,
@@ -191,12 +187,10 @@ function titleBandLines(state: HeaderDeckState, width: number, theme: Theme): st
       // moment` — never an empty band while the session talks.
       return bandWrap('— no subject', width, theme, 'dim');
     }
-    // When the subject mirrors the focused change (the gate law's
-    // "subject mirrors its title"), it renders success-green like the
-    // PWD — the mirror visible at a glance.
-    const work = title.work;
-    const mirrorsFocus = work !== null && mirrorKey(subject) === mirrorKey(work.change);
-    return bandWrap(subject, width, theme, mirrorsFocus ? 'success' : 'accent');
+    // Human layout law 2026-11-10: the left band is Human-owned title —
+    // it can never mirror openspec, so the mirror coloring is gone and
+    // the band renders accent unconditionally.
+    return bandWrap(subject, width, theme, 'accent');
   }
   // Pre-title publishers: the legacy selection keeps the band alive.
   const selection = state.header?.selection;
@@ -237,15 +231,18 @@ function alignedSingleRow(left: string, right: string, width: number): string {
   return `${fittedLeft}${' '.repeat(gap)}${right}`;
 }
 
-function workTile(state: HeaderDeckState, theme: Theme): string {
+function workTile(state: HeaderDeckState, theme: Theme, width: number): string {
   // Line 2 right: Work — derived from OpenSpec focus, never authored here.
-  // A fresh session keeps the slot with the accepted dim hint; pre-title
-  // publishers leave it silent (absent facts remove their slots).
+  // Width policy: the full tile from 56; 40–55 the attention/progress side
+  // yields first and the item count survives longest; below 40 the slot
+  // stays empty. A work slot without facts renders nothing — absent facts
+  // remove their slots, never sentinel dashes or narration.
+  if (width < 40) return '';
   const title = state.header?.title ?? null;
   if (!title) return '';
   const work = title.work;
-  if (!work) return color(theme, 'dim', '— no change owns the moment');
-  return deckWorkSegments(work)
+  if (!work) return '';
+  return deckWorkSegments(work, Date.now(), width < 56)
     .map((segment) => color(theme, segment.color, segment.text, segment.bold === true))
     .join('');
 }
@@ -754,7 +751,7 @@ export function renderHeaderDeck(
   // Line 2 (four-line deck): the Subject leads with Work on the right end
   // (Human amendment 2026-10-23 — no clock, no chrome). Narrow frames: the
   // Work slot yields before the Subject does.
-  const titleRight = boundedWidth >= 40 ? workTile(state, theme) : '';
+  const titleRight = workTile(state, theme, boundedWidth);
   const focusLines = titleBandLines(state, boundedWidth, theme);
   const titleRows = [
     alignedSingleRow(focusLines[0] ?? '', titleRight, boundedWidth),

package/packages/pi-stardeck/src/title-state.ts

@@ -12,7 +12,9 @@
  * the legacy selection/activity rendering.
  */
 
-export const DECK_TITLE_STATE_VERSION = 1 as const;
+import { compactActivityAge } from './activity-age.ts';
+
+export const DECK_TITLE_STATE_VERSION = 2 as const;
 
 export const DECK_TITLE_ACTIVITY_CLASSES = [
   'editing',
@@ -38,16 +40,30 @@ const TASK_ID_MAX = 32;
 const SPAN_ID_MAX = 64;
 const WAIVER_ID_MAX = 64;
 const NOTICE_MAX = 180;
+const ARTIFACTS_MAX = 16;
+const GATE_ACT_MAX = 180;
 const TURN_TOKENS_MAX = 999_999_999;
 const TURN_ELAPSED_MAX = (99 * 60 + 59) * 1_000 + 999;
 
+export type DeckTitleArtifactState = {
+  id: string;
+  done: boolean;
+  items?: { done: number; total: number };
+};
+
 export type DeckTitleWorkState = {
   change: string;
   task?: string;
-  done?: number;
-  total?: number;
   schemaName?: string;
-  ladder?: { done: number; total: number; rung?: string };
+  artifacts?: DeckTitleArtifactState[];
+  /** The artifact the work is in — first not done, else last done. */
+  currentArtifact?: string;
+  /** Attention facts, derived from publisher-owned truth only. */
+  awaitingValidation?: boolean;
+  focusAt?: number;
+  focusStale?: boolean;
+  /** The gate's relayed act line — dim commentary in the optional slot. */
+  gateAct?: string;
 };
 
 export type DeckTitleActivityState = {
@@ -121,46 +137,69 @@ function parseTitleWork(value: unknown): DeckTitleWorkState | null | undefined {
   if (!isRecord(value)) return undefined;
   const change = boundedText(value.change, IDENTIFIER_MAX);
   if (!change) return undefined;
-  // Counts are optional as a pair: absent means unknown (never fabricated
-  // zeros); present-but-invalid rejects the object.
-  const hasCounts = 'done' in value && 'total' in value;
-  if ('done' in value !== 'total' in value) return undefined;
-  const boundedDone = hasCounts ? boundedTotal(value.done) : undefined;
-  const boundedTotalValue = hasCounts ? boundedTotal(value.total) : undefined;
-  if (hasCounts && (boundedDone === null || boundedTotalValue === null)) {
-    return undefined;
-  }
   const task = boundedText(value.task, TASK_ID_MAX, { required: false });
   if (task === null) return undefined;
   const schemaName = boundedText(value.schemaName, IDENTIFIER_MAX, {
     required: false,
   });
   if (schemaName === null) return undefined;
-  let ladder: { done: number; total: number; rung?: string } | undefined;
-  if ('ladder' in value) {
-    if (!isRecord(value.ladder)) return undefined;
-    const ladderDone = boundedTotal(value.ladder.done);
-    const ladderTotal = boundedTotal(value.ladder.total);
-    if (ladderDone === null || ladderTotal === null) return undefined;
-    const ladderRung = boundedText(value.ladder.rung, 32, { required: false });
-    if (ladderRung === null) return undefined;
-    ladder = {
-      done: ladderDone,
-      total: ladderTotal,
-      ...(ladderRung ? { rung: ladderRung } : {}),
-    };
+  const currentArtifact = boundedText(value.currentArtifact, TASK_ID_MAX, {
+    required: false,
+  });
+  if (currentArtifact === null) return undefined;
+  let artifacts: DeckTitleArtifactState[] | undefined;
+  if ('artifacts' in value) {
+    if (!Array.isArray(value.artifacts) || value.artifacts.length > ARTIFACTS_MAX) {
+      return undefined;
+    }
+    const parsed: DeckTitleArtifactState[] = [];
+    for (const entry of value.artifacts) {
+      if (!isRecord(entry)) return undefined;
+      const id = boundedText(entry.id, TASK_ID_MAX);
+      if (!id) return undefined;
+      if (typeof entry.done !== 'boolean') return undefined;
+      const artifactDone = entry.done;
+      let items: { done: number; total: number } | undefined;
+      if ('items' in entry) {
+        if (!isRecord(entry.items)) return undefined;
+        const done = boundedTotal(entry.items.done);
+        const total = boundedTotal(entry.items.total);
+        if (done === null || total === null) return undefined;
+        items = { done, total };
+      }
+      parsed.push({ id, done: artifactDone, ...(items ? { items } : {}) });
+    }
+    artifacts = parsed;
+  }
+  if ('awaitingValidation' in value && typeof value.awaitingValidation !== 'boolean') {
+    return undefined;
   }
-  const counts =
-    typeof boundedDone === 'number' && typeof boundedTotalValue === 'number'
-      ? { done: boundedDone, total: boundedTotalValue }
-      : {};
+  let focusAt: number | undefined;
+  if ('focusAt' in value) {
+    if (
+      typeof value.focusAt !== 'number' ||
+      !Number.isSafeInteger(value.focusAt) ||
+      value.focusAt < 0
+    ) {
+      return undefined;
+    }
+    focusAt = value.focusAt;
+  }
+  if ('focusStale' in value && typeof value.focusStale !== 'boolean') {
+    return undefined;
+  }
+  const gateAct = boundedText(value.gateAct, GATE_ACT_MAX, { required: false });
+  if (gateAct === null) return undefined;
   const extras = {
     ...(schemaName ? { schemaName } : {}),
-    ...(ladder ? { ladder } : {}),
+    ...(artifacts ? { artifacts } : {}),
+    ...(currentArtifact ? { currentArtifact } : {}),
+    ...(value.awaitingValidation === true ? { awaitingValidation: true } : {}),
+    ...(focusAt !== undefined ? { focusAt } : {}),
+    ...(value.focusStale === true ? { focusStale: true } : {}),
+    ...(gateAct ? { gateAct } : {}),
   };
-  return task === undefined
-    ? { change, ...counts, ...extras }
-    : { change, task, ...counts, ...extras };
+  return task === undefined ? { change, ...extras } : { change, task, ...extras };
 }
 
 function parseTitleWaiver(value: unknown): DeckTitleWaiverState | null | undefined {
@@ -232,33 +271,85 @@ export function parseDeckTurnCost(value: unknown): DeckTurnCost | null {
 export type DeckWorkSegment = { text: string; color: string; bold?: boolean };
 
 /**
- * The Work label as colored segments — the human-chosen design: `change ⟩
- * done/total rung › 󰄱 done/total` in one hue per state (accent, success at
- * complete with a filled checkbox and bold counts). The rung name comes
- * straight from OpenSpec's status artifacts — never an invented phase
- * word. Separators are chrome with hard deck-wide colors — `⟩`
- * thinkingHigh-bold like every semantic separator, `›` accent like every
- * minor one. Unknown facts degrade honestly; the bare change is the floor.
+ * The Work label as colored segments — the truthful, de-duplicated tile
+ * under the layout law (truthful-rendered-state 2026-11-10):
+ * `<slug> › <artifact> <done/total> › gate: <act> › 󰄱 <items>` — the
+ * slug leads because openspec identity renders exclusively on the right
+ * (the left band is Human-owned title), then current artifact + artifact
+ * progress, the gate's relayed act dim in the optional slot, and the
+ * current artifact's file-truth item count. Attention is derived, never authored:
+ * `⏸ awaiting you` (warning) replaces the whole tile; a stale focus fact
+ * (`⚠ focus <age> old`, dim, humanized at render time) replaces the artifact
+ * group. Unknown facts drop their segments — absent items never render as
+ * zeros. Compact width: the attention/progress side yields first, the item
+ * count survives longest. Separators are chrome with hard deck-wide colors —
+ * `›` accent like every minor separator.
  */
-export function deckWorkSegments(work: DeckTitleWorkState): DeckWorkSegment[] {
-  const complete =
-    work.done !== undefined &&
-    work.total !== undefined &&
-    work.total > 0 &&
-    work.done >= work.total;
-  const base = complete ? 'success' : 'accent';
-  const segments: DeckWorkSegment[] = [{ text: work.change, color: base }];
-  const ladder = work.ladder;
-  if (ladder) {
-    segments.push({ text: ' ⟩ ', color: 'thinkingHigh', bold: true });
-    const group = `${ladder.done}/${ladder.total}${ladder.rung ? ` ${ladder.rung}` : ''}`;
-    segments.push({ text: group, color: base });
+export function deckWorkSegments(
+  work: DeckTitleWorkState,
+  now: number = Date.now(),
+  compact = false,
+): DeckWorkSegment[] {
+  if (work.awaitingValidation) {
+    return compact ? [] : [{ text: '⏸ awaiting you', color: 'warning' }];
   }
-  if (work.done !== undefined && work.total !== undefined) {
-    segments.push({ text: ' › ', color: 'accent' });
+  // The slug leads the right side — openspec identity renders exclusively
+  // here (Human layout law 2026-11-10); the left band is Human-owned.
+  const segments: DeckWorkSegment[] = [
+    { text: work.change, color: 'success', bold: true },
+  ];
+  const stale = work.focusStale === true && work.focusAt !== undefined;
+  if (!compact) {
+    if (stale) {
+      segments.push({ text: ' › ', color: 'accent' });
+      segments.push({
+        text: `⚠ focus ${compactActivityAge(Math.max(0, now - (work.focusAt ?? 0)))} old`,
+        color: 'dim',
+      });
+    } else {
+      const artifacts = work.artifacts;
+      const current = work.currentArtifact;
+      if (artifacts && artifacts.length > 0 && current) {
+        const done = artifacts.filter((artifact) => artifact.done).length;
+        const currentItems = artifacts.find(
+          (artifact) => artifact.id === current,
+        )?.items;
+        const itemsSettled =
+          currentItems === undefined ||
+          currentItems.total === 0 ||
+          currentItems.done >= currentItems.total;
+        // One hue per state: success only when the artifacts are done AND
+        // the current artifact's items are settled — otherwise work is open.
+        const complete = done === artifacts.length && itemsSettled;
+        segments.push(
+          { text: ' › ', color: 'accent' },
+          {
+            text: `${current} ${done}/${artifacts.length}`,
+            color: complete ? 'success' : 'accent',
+          },
+        );
+      }
+    }
+    // The {optional} slot: the gate's relayed act — dim commentary that
+    // yields first on narrow frames.
+    if (work.gateAct) {
+      segments.push(
+        { text: ' › ', color: 'accent' },
+        { text: `gate: ${work.gateAct}`, color: 'dim' },
+      );
+    }
+  }
+  const items = work.currentArtifact
+    ? work.artifacts?.find((artifact) => artifact.id === work.currentArtifact)?.items
+    : undefined;
+  if (items && items.total > 0) {
+    const complete = items.done >= items.total;
+    if (segments.length > 0) {
+      segments.push({ text: ' › ', color: 'accent' });
+    }
     segments.push({
-      text: `${complete ? '✔' : '󰄱'} ${work.done}/${work.total}`,
-      color: base,
+      text: `${complete ? '✔' : '󰄱'} ${items.done}/${items.total}`,
+      color: complete ? 'success' : 'accent',
       ...(complete ? { bold: true } : {}),
     });
   }

package/packages/status/index.ts

@@ -17,6 +17,7 @@ import {
 } 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 { collectOrchestration } from './src/orchestration.ts';
 import {
@@ -171,6 +172,14 @@ class GalacticaStatusRuntime {
   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;
@@ -209,6 +218,7 @@ class GalacticaStatusRuntime {
     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';
@@ -454,6 +464,19 @@ class GalacticaStatusRuntime {
     ) {
       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',
@@ -628,23 +651,15 @@ class GalacticaStatusRuntime {
 
   private currentTitleState(snapshot = this.store.get()): TitleState {
     const facts = this.cockpitFacts;
-    const focusedTaskId =
-      facts.openSpec.mode === 'task' ? facts.openSpec.taskId : undefined;
-    const taskTitle =
-      facts.openSpec.mode === 'task' &&
-      snapshot.openspec?.changeId === facts.openSpec.change &&
-      !snapshot.openspec.meta.stale
-        ? (snapshot.openspec.allTasks ?? snapshot.openspec.pendingTasks).find(
-            (task) => task.id === focusedTaskId,
-          )?.title
+    // 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;
-    // The band chip renders the fallback chain — task focus, native session
-    // name, legacy subject, directory. The terminal titlebar is pi-title's
-    // alone; this package never paints it (pure-renderer-split Slice 2).
     const subjectTitle = formatActiveWorkTitle({
-      focus: facts.openSpec,
       subject: facts.subject,
-      ...(taskTitle ? { taskTitle } : {}),
       ...(this.sessionName ? { sessionName: this.sessionName } : {}),
       projectRoot: snapshot.projectRoot,
       cwd: snapshot.cwd,
@@ -654,6 +669,8 @@ class GalacticaStatusRuntime {
       focus: facts.openSpec,
       openspec: snapshot.openspec,
       activity: this.titleActivity.current(),
+      focusAt: this.focusAt,
+      ...(gateAct ? { gateAct } : {}),
     });
   }
 
@@ -690,6 +707,10 @@ class GalacticaStatusRuntime {
   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) {

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

@@ -20,7 +20,6 @@ export const NO_SESSION_SUBJECT: SessionSubject = { state: 'clear' };
 
 const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/gu;
 const MAX_TITLE_POINTS = 180;
-const MAX_TASK_TITLE_POINTS = 72;
 const MAX_SUBJECT_POINTS = 120;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -160,31 +159,26 @@ export function sameSessionSubject(
   );
 }
 
+/**
+ * The Human-owned left title: session name, subject, then the directory
+ * fallbacks. Layout law 2026-11-10 (truthful-rendered-state): openspec
+ * identity renders exclusively on the right work tile — this chain never
+ * carries change, task, or gate text.
+ */
 export function formatActiveWorkTitle(options: {
-  focus: OpenSpecFocus;
   subject?: SessionSubject;
-  taskTitle?: string;
   sessionName?: string;
   projectRoot?: string;
   cwd: string;
 }): string {
-  let detail: string;
-  if (options.focus.mode === 'task') {
-    const taskTitle = options.taskTitle
-      ? shorten(normalizeTitlePart(options.taskTitle), MAX_TASK_TITLE_POINTS)
-      : '';
-    detail = `${options.focus.change} › ${options.focus.taskId}${taskTitle ? ` ${taskTitle}` : ''}`;
-  } else if (normalizeTitlePart(options.sessionName ?? '')) {
-    detail = normalizeTitlePart(options.sessionName ?? '');
-  } else if (options.subject && options.subject.state === 'set') {
-    detail = options.subject.title;
-  } else {
-    detail =
-      normalizeTitlePart(options.sessionName ?? '') ||
-      normalizeTitlePart(basename(options.projectRoot ?? '')) ||
-      normalizeTitlePart(basename(options.cwd)) ||
-      'pi';
-  }
-
-  return shorten(`π  ${normalizeTitlePart(detail)}`, MAX_TITLE_POINTS);
+  const detail =
+    normalizeTitlePart(options.sessionName ?? '') ||
+    (options.subject && options.subject.state === 'set' ? options.subject.title : '') ||
+    normalizeTitlePart(basename(options.projectRoot ?? '')) ||
+    normalizeTitlePart(basename(options.cwd)) ||
+    'pi';
+
+  // Bare text — line 2 carries no chrome (frozen amendment): the title
+  // stands naked, and pi-title's naming is quoted, never re-decorated.
+  return shorten(detail, MAX_TITLE_POINTS);
 }

package/packages/status/src/gate-act.ts

@@ -0,0 +1,85 @@
+import { promises as fs } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import type { CommandRunner } from './types.ts';
+
+/** Relay budget: the gate's act line is cockpit commentary — a slow or
+ *  absent gate must cost less than a refresh, never block one. */
+const GATE_PROBE_TIMEOUT_MS = 2_000;
+/** Re-probe cadence when the meta file cannot be statted at all — time
+ *  is the only cache key left, so it steps lightly. */
+const ABSENT_META_TTL_MS = 30_000;
+
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/gu;
+
+interface GateActCacheEntry {
+  mtimeMs?: number;
+  at: number;
+  line: string | undefined;
+}
+
+/** mtime-keyed relay cache: one probe per meta mtime, negatives cached
+ *  exactly like hits — a missing or refusing gate must never become a
+ *  per-render spawn storm. Keyed by contained change root, not slug. */
+const gateActCache = new Map<string, GateActCacheEntry>();
+
+function containedChangeRoot(projectRoot: string, change: string): string | undefined {
+  const changesRoot = resolve(projectRoot, 'openspec', 'changes');
+  const changeRoot = resolve(changesRoot, change);
+  if (changeRoot === changesRoot || !changeRoot.startsWith(`${changesRoot}${sep}`)) {
+    return undefined;
+  }
+  return changeRoot;
+}
+
+/**
+ * The gate's teaching line for one change, relayed verbatim:
+ * `pios-gate <slug>` — the aim — owns truth and words; this module owns
+ * only placement and cost. Any non-zero exit (unknown changes error),
+ * timeout kill, spawn failure, or empty output yields `undefined` —
+ * declared focus renders alone, quietly. The meta file is never parsed:
+ * its mtime only keys the cache.
+ */
+export async function resolveGateAct(options: {
+  change: string;
+  projectRoot: string;
+  runner: CommandRunner;
+  now?: number;
+}): Promise<string | undefined> {
+  const changeRoot = containedChangeRoot(options.projectRoot, options.change);
+  if (!changeRoot) return undefined;
+  const now = options.now ?? Date.now();
+
+  let mtimeMs: number | undefined;
+  try {
+    mtimeMs = (await fs.stat(resolve(changeRoot, '.openspec.yaml'))).mtimeMs;
+  } catch {
+    mtimeMs = undefined;
+  }
+
+  const cached = gateActCache.get(changeRoot);
+  if (
+    cached &&
+    (cached.mtimeMs !== undefined
+      ? cached.mtimeMs === mtimeMs
+      : mtimeMs === undefined && now - cached.at < ABSENT_META_TTL_MS)
+  ) {
+    return cached.line;
+  }
+
+  let line: string | undefined;
+  try {
+    const result = await options.runner('pios-gate', [options.change], {
+      cwd: options.projectRoot,
+      timeoutMs: GATE_PROBE_TIMEOUT_MS,
+    });
+    if (result.code === 0 && !result.killed) {
+      const firstLine = String(result.stdout).split('\n', 1)[0] ?? '';
+      const cleaned = firstLine.replace(CONTROL_CHARACTERS, ' ').trim();
+      if (cleaned) line = cleaned;
+    }
+  } catch {
+    // Missing binary, spawn refusal, whatever went wrong: no gate line.
+  }
+  gateActCache.set(changeRoot, { mtimeMs, at: now, line });
+  return line;
+}

package/packages/status/src/openspec.ts

@@ -2,6 +2,7 @@ import { promises as fs } from 'node:fs';
 import { resolve, sep } from 'node:path';
 import type {
   CommandRunner,
+  OpenSpecArtifact,
   OpenSpecHierarchyProgress,
   OpenSpecOverview,
   OpenSpecState,
@@ -27,6 +28,19 @@ interface ApplyInstructionsResult {
   tasksPath?: string;
 }
 
+/** Parsed `openspec status` artifacts plus their resolved files. Paths stay
+ *  internal: they feed the file-truth item counter, never the contract. */
+interface ParsedArtifact extends OpenSpecArtifact {
+  resolvedPath?: string;
+}
+
+interface ParsedOpenSpecStatus {
+  schemaName?: string;
+  artifacts?: ParsedArtifact[];
+  currentArtifact?: string;
+  changeRoot?: string;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -117,6 +131,51 @@ export function parseTaskMarkdown(content: string): OpenSpecTask[] {
   return tasks;
 }
 
+/** File-truth checkbox counting: `{ done, total }` over `- [x]` / `- [ ]`
+ *  items. Zero checkboxes is absence, not zero — `undefined` emits only
+ *  when a readable source file actually carries countable items. */
+export function parseCheckboxCounts(
+  content: string,
+): { done: number; total: number } | undefined {
+  const pattern = /^\s*-\s*\[([ xX])\]/gmu;
+  let total = 0;
+  let done = 0;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(content)) !== null) {
+    total += 1;
+    if ((match[1] ?? '').toLowerCase() === 'x') done += 1;
+  }
+  return total > 0 ? { done, total } : undefined;
+}
+
+/** mtime-keyed parse cache: a file is re-read only after its mtime moves.
+ *  Unreadable files stay uncached so the next refresh retries honestly. */
+const artifactItemsCache = new Map<
+  string,
+  { mtimeMs: number; counts: { done: number; total: number } | undefined }
+>();
+
+export async function readArtifactItems(
+  path: string,
+): Promise<{ done: number; total: number } | undefined> {
+  let mtimeMs: number;
+  try {
+    mtimeMs = (await fs.stat(path)).mtimeMs;
+  } catch {
+    return undefined;
+  }
+  const cached = artifactItemsCache.get(path);
+  if (cached && cached.mtimeMs === mtimeMs) return cached.counts;
+  let counts: { done: number; total: number } | undefined;
+  try {
+    counts = parseCheckboxCounts(await fs.readFile(path, 'utf8'));
+  } catch {
+    return undefined;
+  }
+  artifactItemsCache.set(path, { mtimeMs, counts });
+  return counts;
+}
+
 export function parseTaskHierarchy(
   content: string,
 ): OpenSpecHierarchyProgress | undefined {
@@ -234,31 +293,60 @@ function chooseChange(
   return selected;
 }
 
-function parseOpenSpecStatus(value: unknown): {
-  schemaName?: string;
-  ladder?: { done: number; total: number; rung?: string };
-} {
+function parseOpenSpecStatus(value: unknown): ParsedOpenSpecStatus {
   if (!isRecord(value)) return {};
   const schemaName =
     typeof value.schemaName === 'string' && value.schemaName.trim()
       ? value.schemaName.trim()
       : undefined;
-  let ladder: { done: number; total: number; rung?: string } | undefined;
+  const changeRoot =
+    typeof value.changeRoot === 'string' && value.changeRoot.trim()
+      ? value.changeRoot.trim()
+      : undefined;
+  let artifacts: ParsedArtifact[] | undefined;
+  let currentArtifact: string | undefined;
   if (Array.isArray(value.artifacts) && value.artifacts.length > 0) {
-    let done = 0;
-    let rung: string | undefined;
+    const parsed: ParsedArtifact[] = [];
+    let lastDone: string | undefined;
     for (const artifact of value.artifacts) {
       if (!isRecord(artifact)) continue;
-      const id = typeof artifact.id === 'string' ? artifact.id : undefined;
-      if (rung === undefined && id) rung = id;
-      if (artifact.status === 'done') {
-        done += 1;
-        if (id) rung = id;
+      const id =
+        typeof artifact.id === 'string' && artifact.id.trim()
+          ? artifact.id.trim()
+          : undefined;
+      if (!id) continue;
+      const done = artifact.status === 'done';
+      if (done) lastDone = id;
+      // The artifacts array carries a relative outputPath; the item counter
+      // resolves it against the change root — contained paths only.
+      let resolvedPath: string | undefined;
+      const outputPath =
+        typeof artifact.outputPath === 'string' && artifact.outputPath.trim()
+          ? artifact.outputPath.trim()
+          : undefined;
+      if (changeRoot && outputPath) {
+        const root = resolve(changeRoot);
+        const candidate = resolve(root, outputPath);
+        if (candidate === root || candidate.startsWith(`${root}${sep}`)) {
+          resolvedPath = candidate;
+        }
       }
+      parsed.push({ id, done, ...(resolvedPath ? { resolvedPath } : {}) });
+    }
+    if (parsed.length > 0) {
+      // The current artifact is the one the work is in: the first not yet
+      // done; once everything is complete, the last done artifact.
+      const inProgress = parsed.find((artifact) => !artifact.done);
+      currentArtifact = inProgress ? inProgress.id : lastDone;
+      artifacts = parsed;
     }
-    ladder = { done, total: value.artifacts.length, ...(rung ? { rung } : {}) };
   }
-  return { ...(schemaName ? { schemaName } : {}), ...(ladder ? { ladder } : {}) };
+  return {
+    ...(schemaName ? { schemaName } : {}),
+    ...(artifacts ? { artifacts } : {}),
+    ...(currentArtifact ? { currentArtifact } : {}),
+    ...(changeRoot ? { changeRoot } : {}),
+  };
 }
 
 async function runJson(
@@ -295,6 +383,37 @@ async function isIdeaChange(projectRoot: string, changeName: string): Promise<bo
   }
 }
 
+/** Newest mtime over the change directory's direct files — the file-truth
+ *  "the change moved on" timestamp attention staleness compares against.
+ *  Change directories are flat; absent or unreadable dirs stay undefined. */
+async function changeDirectoryMtime(
+  projectRoot: string,
+  changeName: string,
+): Promise<number | undefined> {
+  const changesRoot = resolve(projectRoot, 'openspec', 'changes');
+  const changeRoot = resolve(changesRoot, changeName);
+  if (changeRoot !== changesRoot && !changeRoot.startsWith(`${changesRoot}${sep}`)) {
+    return undefined;
+  }
+  let entries;
+  try {
+    entries = await fs.readdir(changeRoot, { withFileTypes: true });
+  } catch {
+    return undefined;
+  }
+  let newest: number | undefined;
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    try {
+      const mtimeMs = (await fs.stat(resolve(changeRoot, entry.name))).mtimeMs;
+      newest = newest === undefined ? mtimeMs : Math.max(newest, mtimeMs);
+    } catch {
+      // A file vanishing between readdir and stat is honest absence.
+    }
+  }
+  return newest;
+}
+
 export async function collectOpenSpecOverview(options: {
   cwd: string;
   runner: CommandRunner;
@@ -361,7 +480,8 @@ export async function collectOpenSpec(options: {
   }
 
   let schemaName: string | undefined;
-  let ladder: OpenSpecState['ladder'];
+  let artifacts: OpenSpecArtifact[] | undefined;
+  let currentArtifact: string | undefined;
   try {
     const status = parseOpenSpecStatus(
       await runJson(
@@ -372,14 +492,31 @@ export async function collectOpenSpec(options: {
       ),
     );
     schemaName = status.schemaName;
-    ladder = status.ladder;
+    currentArtifact = status.currentArtifact;
+    if (status.artifacts) {
+      // Item counts come from the artifact FILES, not CLI opinion: the CLI
+      // cannot count custom-schema items (taskTrackingConfigured: false),
+      // and only readable files emit counts — absence never becomes zero.
+      artifacts = await Promise.all(
+        status.artifacts.map(async (artifact) => {
+          const items = artifact.resolvedPath
+            ? await readArtifactItems(artifact.resolvedPath)
+            : undefined;
+          return {
+            id: artifact.id,
+            done: artifact.done,
+            ...(items ? { items } : {}),
+          };
+        }),
+      );
+    }
   } catch {
-    // Ladder facts are optional; the list counts remain valid without them.
+    // Artifact facts are optional; the list counts remain valid without them.
   }
+  const changeModifiedAt = await changeDirectoryMtime(projectRoot, change.name);
 
   let tasks: OpenSpecTask[] = [];
   let tasksPath: string | undefined;
-  let instructionProgress: ApplyInstructionsResult['progress'];
   let hierarchy: OpenSpecHierarchyProgress | undefined;
   try {
     const instructions = parseApplyInstructions(
@@ -392,7 +529,6 @@ export async function collectOpenSpec(options: {
     );
     tasks = instructions.tasks;
     tasksPath = instructions.tasksPath;
-    instructionProgress = instructions.progress;
 
     if (tasksPath) {
       try {
@@ -414,34 +550,46 @@ 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 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.
+  const artifactCounts = artifacts
+    ? {
+        done: artifacts.filter((artifact) => artifact.done).length,
+        total: artifacts.length,
+      }
+    : undefined;
   const completedTasks =
-    tasks.length > 0
-      ? tasks.filter((task) => task.done).length
-      : Math.max(0, Math.trunc(instructionProgress?.complete ?? change.completedTasks));
-  const totalTasks =
-    tasks.length > 0
-      ? tasks.length
-      : Math.max(0, Math.trunc(instructionProgress?.total ?? change.totalTasks));
+    tasks.length > 0 ? tasks.filter((task) => task.done).length : artifactCounts?.done;
+  const totalTasks = tasks.length > 0 ? tasks.length : artifactCounts?.total;
   const complete =
-    change.status === 'complete' || (totalTasks > 0 && completedTasks >= totalTasks);
+    change.status === 'complete' ||
+    (totalTasks !== undefined && totalTasks > 0 && (completedTasks ?? 0) >= totalTasks);
 
   return {
     projectRoot,
     changeId: change.name,
     title,
     phase: complete ? 'complete' : change.status,
-    completedTasks,
-    totalTasks,
-    progressPercent:
-      totalTasks > 0
-        ? Math.max(0, Math.min(100, Math.round((completedTasks / totalTasks) * 100)))
-        : 0,
+    ...(completedTasks !== undefined ? { completedTasks } : {}),
+    ...(totalTasks !== undefined ? { totalTasks } : {}),
+    ...(totalTasks !== undefined && totalTasks > 0
+      ? {
+          progressPercent: Math.max(
+            0,
+            Math.min(100, Math.round(((completedTasks ?? 0) / totalTasks) * 100)),
+          ),
+        }
+      : {}),
     pendingTasks: tasks.filter((task) => !task.done),
     allTasks: tasks,
     ...(tasksPath ? { tasksPath } : {}),
     ...(hierarchy ? { hierarchy } : {}),
     ...(schemaName ? { schemaName } : {}),
-    ...(ladder ? { ladder } : {}),
+    ...(artifacts ? { artifacts } : {}),
+    ...(currentArtifact ? { currentArtifact } : {}),
+    ...(changeModifiedAt !== undefined ? { changeModifiedAt } : {}),
     meta: {
       source: 'openspec-cli',
       refreshedAt: now,

package/packages/status/src/publisher.ts

@@ -99,7 +99,13 @@ export function formatOpenSpec(
   focusedTaskId: string | null,
   compact = false,
 ): string {
-  const progress = `${state.completedTasks}/${state.totalTasks}`;
+  // File-truth counts only — absent counts render no progress prefix at
+  // all (absence never becomes zero, truthful-rendered-state).
+  const progress =
+    state.totalTasks !== undefined
+      ? `${state.completedTasks ?? 0}/${state.totalTasks}`
+      : '';
+  const lead = progress ? `${progress}  ` : '';
   const title = compact
     ? compactChangeTitle(state.title, 26)
     : normalizeChangeTitle(state.title);
@@ -107,16 +113,16 @@ export function formatOpenSpec(
     ? `  stale ${ageText(state.meta.updatedAt, Date.now()) ?? ''}`.trimEnd()
     : '';
 
-  if (state.phase === 'complete') return `${progress}  ${title}${stale}`;
+  if (state.phase === 'complete') return `${lead}${title}${stale}`;
 
   const activeTask = focusedTaskId
     ? (state.allTasks ?? state.pendingTasks).find((task) => task.id === focusedTaskId)
     : undefined;
   if (activeTask) {
-    return `${progress}  ▶ ${focusedTaskText(activeTask, compact)}${stale}`;
+    return `${lead}▶ ${focusedTaskText(activeTask, compact)}${stale}`;
   }
 
-  return `${progress}  ${title}${stale}`;
+  return `${lead}${title}${stale}`;
 }
 
 function diagnosticsColor(state: DiagnosticsState, now: number): WidgetColor {
@@ -917,16 +923,19 @@ export function buildHeaderStatusEvent(
       ...projectedActivity,
     };
   }
-  const progress = options.openSpec?.totalTasks
-    ? [
-        {
-          icon: '󰘬',
-          completed: options.openSpec.completedTasks,
-          total: options.openSpec.totalTasks,
-          color: openSpecColor(options.openSpec),
-        },
-      ]
-    : [];
+  const openSpec = options.openSpec;
+  const progress =
+    typeof openSpec?.totalTasks === 'number' &&
+    typeof openSpec.completedTasks === 'number'
+      ? [
+          {
+            icon: '󰘬',
+            completed: openSpec.completedTasks,
+            total: openSpec.totalTasks,
+            color: openSpecColor(openSpec),
+          },
+        ]
+      : [];
 
   return {
     protocol: 1,

package/packages/status/src/title-state.ts

@@ -10,7 +10,7 @@ import type { OpenSpecState } from './types.ts';
  * code may never write any slot; it only parses defensively.
  */
 
-export const TITLE_STATE_VERSION = 1 as const;
+export const TITLE_STATE_VERSION = 2 as const;
 
 export const TITLE_ACTIVITY_CLASSES = [
   'editing',
@@ -37,14 +37,28 @@ const TASK_ID_MAX = 32;
 const SPAN_ID_MAX = 64;
 const WAIVER_ID_MAX = 64;
 const NOTICE_MAX = 180;
+const ARTIFACTS_MAX = 16;
+const GATE_ACT_MAX = 180;
+
+export type TitleArtifactState = {
+  id: string;
+  done: boolean;
+  items?: { done: number; total: number };
+};
 
 export type TitleWorkState = {
   change: string;
   task?: string;
-  done?: number;
-  total?: number;
   schemaName?: string;
-  ladder?: { done: number; total: number; rung?: string };
+  artifacts?: TitleArtifactState[];
+  /** The artifact the work is in — first not done, else last done. */
+  currentArtifact?: string;
+  /** Attention facts, derived from publisher-owned truth only. */
+  awaitingValidation?: boolean;
+  focusAt?: number;
+  focusStale?: boolean;
+  /** The gate's relayed act line — dim commentary in the optional slot. */
+  gateAct?: string;
 };
 
 export type TitleActivityState = {
@@ -115,46 +129,69 @@ function parseTitleWork(value: unknown): TitleWorkState | null | undefined {
   if (!isRecord(value)) return undefined;
   const change = boundedText(value.change, IDENTIFIER_MAX);
   if (!change) return undefined;
-  // Counts are optional as a pair: absent means unknown (never fabricated
-  // zeros); present-but-invalid rejects the object.
-  const hasCounts = 'done' in value && 'total' in value;
-  if ('done' in value !== 'total' in value) return undefined;
-  const boundedDone = hasCounts ? boundedTotal(value.done) : undefined;
-  const boundedTotalValue = hasCounts ? boundedTotal(value.total) : undefined;
-  if (hasCounts && (boundedDone === null || boundedTotalValue === null)) {
-    return undefined;
-  }
   const task = boundedText(value.task, TASK_ID_MAX, { required: false });
   if (task === null) return undefined;
   const schemaName = boundedText(value.schemaName, IDENTIFIER_MAX, {
     required: false,
   });
   if (schemaName === null) return undefined;
-  let ladder: { done: number; total: number; rung?: string } | undefined;
-  if ('ladder' in value) {
-    if (!isRecord(value.ladder)) return undefined;
-    const ladderDone = boundedTotal(value.ladder.done);
-    const ladderTotal = boundedTotal(value.ladder.total);
-    if (ladderDone === null || ladderTotal === null) return undefined;
-    const ladderRung = boundedText(value.ladder.rung, 32, { required: false });
-    if (ladderRung === null) return undefined;
-    ladder = {
-      done: ladderDone,
-      total: ladderTotal,
-      ...(ladderRung ? { rung: ladderRung } : {}),
-    };
+  const currentArtifact = boundedText(value.currentArtifact, TASK_ID_MAX, {
+    required: false,
+  });
+  if (currentArtifact === null) return undefined;
+  let artifacts: TitleArtifactState[] | undefined;
+  if ('artifacts' in value) {
+    if (!Array.isArray(value.artifacts) || value.artifacts.length > ARTIFACTS_MAX) {
+      return undefined;
+    }
+    const parsed: TitleArtifactState[] = [];
+    for (const entry of value.artifacts) {
+      if (!isRecord(entry)) return undefined;
+      const id = boundedText(entry.id, TASK_ID_MAX);
+      if (!id) return undefined;
+      if (typeof entry.done !== 'boolean') return undefined;
+      const artifactDone = entry.done;
+      let items: { done: number; total: number } | undefined;
+      if ('items' in entry) {
+        if (!isRecord(entry.items)) return undefined;
+        const done = boundedTotal(entry.items.done);
+        const total = boundedTotal(entry.items.total);
+        if (done === null || total === null) return undefined;
+        items = { done, total };
+      }
+      parsed.push({ id, done: artifactDone, ...(items ? { items } : {}) });
+    }
+    artifacts = parsed;
+  }
+  if ('awaitingValidation' in value && typeof value.awaitingValidation !== 'boolean') {
+    return undefined;
   }
-  const counts =
-    typeof boundedDone === 'number' && typeof boundedTotalValue === 'number'
-      ? { done: boundedDone, total: boundedTotalValue }
-      : {};
+  let focusAt: number | undefined;
+  if ('focusAt' in value) {
+    if (
+      typeof value.focusAt !== 'number' ||
+      !Number.isSafeInteger(value.focusAt) ||
+      value.focusAt < 0
+    ) {
+      return undefined;
+    }
+    focusAt = value.focusAt;
+  }
+  if ('focusStale' in value && typeof value.focusStale !== 'boolean') {
+    return undefined;
+  }
+  const gateAct = boundedText(value.gateAct, GATE_ACT_MAX, { required: false });
+  if (gateAct === null) return undefined;
   const extras = {
     ...(schemaName ? { schemaName } : {}),
-    ...(ladder ? { ladder } : {}),
+    ...(artifacts ? { artifacts } : {}),
+    ...(currentArtifact ? { currentArtifact } : {}),
+    ...(value.awaitingValidation === true ? { awaitingValidation: true } : {}),
+    ...(focusAt !== undefined ? { focusAt } : {}),
+    ...(value.focusStale === true ? { focusStale: true } : {}),
+    ...(gateAct ? { gateAct } : {}),
   };
-  return task === undefined
-    ? { change, ...counts, ...extras }
-    : { change, task, ...counts, ...extras };
+  return task === undefined ? { change, ...extras } : { change, task, ...extras };
 }
 
 function parseTitleWaiver(value: unknown): TitleWaiverState | null | undefined {
@@ -202,46 +239,49 @@ export function shortenTitleTarget(value: string): string {
   return `${points.slice(0, Math.max(1, TITLE_TARGET_MAX - 1)).join('')}…`;
 }
 
-function boundedCount(value: number | undefined, fallback = 0): number {
-  const candidate = value === undefined || !Number.isFinite(value) ? fallback : value;
-  return Math.max(0, Math.min(TITLE_TOTAL_MAX, Math.round(candidate)));
-}
-
 /**
  * Derive the `work` slot from the OpenSpec focus and the focused snapshot.
  * A task focus owns its change; without a focus a passively collected change
- * still reports progress, just without a task id.
+ * still reports artifact facts, just without a task id. Counts live only on
+ * artifact `items` — file truth; absent counts are absent, never zeros.
  */
 export function deriveTitleWork(
   focus: OpenSpecFocus,
   openspec: OpenSpecState | null | undefined,
+  options: { focusAt?: number; gateAct?: string } = {},
 ): TitleWorkState | null {
-  const counts = (state: OpenSpecState): { done: number; total: number } => ({
-    done: boundedCount(state.hierarchy?.tasks?.completed, state.completedTasks),
-    total: boundedCount(state.hierarchy?.tasks?.total, state.totalTasks),
-  });
-  // Human steering 2026-10-23: no invented phase words — the ladder's
-  // rung name comes straight from OpenSpec.
+  // Artifact facts come straight from the collector; nothing is invented
+  // here — absent facts simply drop out of the contract.
   const extras = (state: OpenSpecState | undefined) => {
     if (!state) return {};
     return {
       ...(state.schemaName ? { schemaName: state.schemaName } : {}),
-      ...(state.ladder ? { ladder: state.ladder } : {}),
+      ...(state.artifacts ? { artifacts: state.artifacts } : {}),
+      ...(state.currentArtifact ? { currentArtifact: state.currentArtifact } : {}),
     };
   };
   if (focus.mode === 'task') {
     const state = openspec && openspec.changeId === focus.change ? openspec : undefined;
-    const taskCounts = state ? counts(state) : undefined;
+    const stale =
+      options.focusAt !== undefined &&
+      state?.changeModifiedAt !== undefined &&
+      state.changeModifiedAt > options.focusAt;
     return {
       change: focus.change,
       task: focus.taskId,
-      ...(taskCounts ?? {}),
       ...extras(state),
+      ...(focus.awaitingValidation ? { awaitingValidation: true } : {}),
+      ...(options.focusAt !== undefined ? { focusAt: options.focusAt } : {}),
+      ...(stale ? { focusStale: true } : {}),
+      ...(options.gateAct ? { gateAct: options.gateAct } : {}),
     };
   }
   if (!openspec) return null;
-  const taskCounts = counts(openspec);
-  return { change: openspec.changeId, ...taskCounts, ...extras(openspec) };
+  return {
+    change: openspec.changeId,
+    ...extras(openspec),
+    ...(options.gateAct ? { gateAct: options.gateAct } : {}),
+  };
 }
 
 /**
@@ -254,11 +294,18 @@ export function buildTitleState(options: {
   focus: OpenSpecFocus;
   openspec?: OpenSpecState | null;
   activity?: TitleActivityState | null;
+  /** Publisher-owned timestamp of the current focus fact. */
+  focusAt?: number;
+  /** The gate's relayed act line for the focused change, if resolved. */
+  gateAct?: string;
 }): TitleState {
   return {
     v: TITLE_STATE_VERSION,
     subject: options.subject.state === 'set' ? options.subject.title : null,
-    work: deriveTitleWork(options.focus, options.openspec),
+    work: deriveTitleWork(options.focus, options.openspec, {
+      focusAt: options.focusAt,
+      ...(options.gateAct ? { gateAct: options.gateAct } : {}),
+    }),
     activity: options.activity ?? null,
     waiver: null,
   };

package/packages/status/src/types.ts

@@ -60,6 +60,15 @@ export interface OpenSpecTask {
   done: boolean;
 }
 
+/** One OpenSpec artifact: lifecycle from `openspec status`, item counts
+ *  from the artifact's own file. Absent items mean unreadable or empty —
+ *  never zeros. */
+export interface OpenSpecArtifact {
+  id: string;
+  done: boolean;
+  items?: { done: number; total: number };
+}
+
 export interface OpenSpecOverview {
   projectRoot: string;
   actionableChanges: number;
@@ -82,15 +91,23 @@ export interface OpenSpecState {
   changeId: string;
   title: string;
   phase: string;
-  completedTasks: number;
-  totalTasks: number;
-  progressPercent: number;
+  /** File-truth counts — checkbox tasks first, then done/total
+   *  artifacts. Absent when neither is readable: absence never becomes
+   *  zero (truthful-rendered-state). */
+  completedTasks?: number;
+  totalTasks?: number;
+  progressPercent?: number;
   pendingTasks: OpenSpecTask[];
   allTasks?: OpenSpecTask[];
   tasksPath?: string;
   hierarchy?: OpenSpecHierarchyProgress;
   schemaName?: string;
-  ladder?: { done: number; total: number; rung?: string };
+  artifacts?: OpenSpecArtifact[];
+  /** The artifact the work is currently in: first not yet done, falling
+   *  back to the last done artifact once everything is complete. */
+  currentArtifact?: string;
+  /** Newest file mtime inside the change directory, when statable. */
+  changeModifiedAt?: number;
   meta: SourceMeta;
 }