@aemonge-dev/pi-stardeck 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aemonge-dev/pi-stardeck",
-  "version": "0.12.0",
+  "version": "0.13.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

@@ -237,15 +237,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 +757,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,27 @@ const TASK_ID_MAX = 32;
 const SPAN_ID_MAX = 64;
 const WAIVER_ID_MAX = 64;
 const NOTICE_MAX = 180;
+const ARTIFACTS_MAX = 16;
 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;
 };
 
 export type DeckTitleActivityState = {
@@ -121,46 +134,66 @@ 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;
+  }
+  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 counts =
-    typeof boundedDone === 'number' && typeof boundedTotalValue === 'number'
-      ? { done: boundedDone, total: boundedTotalValue }
-      : {};
   const extras = {
     ...(schemaName ? { schemaName } : {}),
-    ...(ladder ? { ladder } : {}),
+    ...(artifacts ? { artifacts } : {}),
+    ...(currentArtifact ? { currentArtifact } : {}),
+    ...(value.awaitingValidation === true ? { awaitingValidation: true } : {}),
+    ...(focusAt !== undefined ? { focusAt } : {}),
+    ...(value.focusStale === true ? { focusStale: true } : {}),
   };
-  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 +265,66 @@ 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:
+ * `execute 4/4 › 󰄱 12/15` — current artifact + artifact progress + the
+ * current artifact's file-truth item count. The change name lives on the
+ * subject side and never repeats here. 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' }];
+  }
+  const segments: DeckWorkSegment[] = [];
+  const stale = work.focusStale === true && work.focusAt !== undefined;
+  if (!compact) {
+    if (stale) {
+      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: `${current} ${done}/${artifacts.length}`,
+          color: complete ? 'success' : 'accent',
+        });
+      }
+    }
   }
-  if (work.done !== undefined && work.total !== undefined) {
-    segments.push({ text: ' › ', color: 'accent' });
+  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

@@ -171,6 +171,10 @@ 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;
   private subject: SessionSubject;
   private sessionName: string | undefined;
   private diagnosticsPath: string | undefined;
@@ -209,6 +213,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';
@@ -654,6 +659,7 @@ class GalacticaStatusRuntime {
       focus: facts.openSpec,
       openspec: snapshot.openspec,
       activity: this.titleActivity.current(),
+      focusAt: this.focusAt,
     });
   }
 
@@ -690,6 +696,7 @@ class GalacticaStatusRuntime {
   setFocus(focus: OpenSpecFocus): void {
     if (sameOpenSpecFocus(this.focus, focus)) return;
     this.focus = focus;
+    this.focusAt = Date.now();
     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

@@ -186,5 +186,8 @@ export function formatActiveWorkTitle(options: {
       'pi';
   }
 
-  return shorten(`π  ${normalizeTitlePart(detail)}`, MAX_TITLE_POINTS);
+  // Bare text — line 2 carries no chrome (frozen amendment): the session
+  // name, change, and task stand naked, and pi-title's naming is quoted,
+  // never re-decorated.
+  return shorten(normalizeTitlePart(detail), MAX_TITLE_POINTS);
 }

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,10 +492,28 @@ 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;
@@ -441,7 +579,9 @@ export async function collectOpenSpec(options: {
     ...(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/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,25 @@ const TASK_ID_MAX = 32;
 const SPAN_ID_MAX = 64;
 const WAIVER_ID_MAX = 64;
 const NOTICE_MAX = 180;
+const ARTIFACTS_MAX = 16;
+
+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;
 };
 
 export type TitleActivityState = {
@@ -115,46 +126,66 @@ 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;
+  }
+  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 counts =
-    typeof boundedDone === 'number' && typeof boundedTotalValue === 'number'
-      ? { done: boundedDone, total: boundedTotalValue }
-      : {};
   const extras = {
     ...(schemaName ? { schemaName } : {}),
-    ...(ladder ? { ladder } : {}),
+    ...(artifacts ? { artifacts } : {}),
+    ...(currentArtifact ? { currentArtifact } : {}),
+    ...(value.awaitingValidation === true ? { awaitingValidation: true } : {}),
+    ...(focusAt !== undefined ? { focusAt } : {}),
+    ...(value.focusStale === true ? { focusStale: true } : {}),
   };
-  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 +233,44 @@ 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 } = {},
 ): 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 } : {}),
     };
   }
   if (!openspec) return null;
-  const taskCounts = counts(openspec);
-  return { change: openspec.changeId, ...taskCounts, ...extras(openspec) };
+  return { change: openspec.changeId, ...extras(openspec) };
 }
 
 /**
@@ -254,11 +283,15 @@ export function buildTitleState(options: {
   focus: OpenSpecFocus;
   openspec?: OpenSpecState | null;
   activity?: TitleActivityState | null;
+  /** Publisher-owned timestamp of the current focus fact. */
+  focusAt?: number;
 }): 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,
+    }),
     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;
@@ -90,7 +99,12 @@ export interface OpenSpecState {
   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;
 }