@aemonge-dev/pi-stardeck 0.11.0 → 0.13.0

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;
 }
 
@@ -193,7 +207,6 @@ export type StageValue =
 
 export type SelectionState =
   | { kind: 'openspec-task'; change: string; task: string }
-  | { kind: 'session-work'; intent: string; phase: 'active' | 'validation' }
   | { kind: 'subject'; title: string }
   | { kind: 'none' };
 

package/packages/work-state/README.md

@@ -0,0 +1,33 @@
+# work-state
+
+Owns the branch-local OpenSpec Task focus for the pi-stardeck cockpit: the
+`openspec_focus` tool, the `galactica-status.openspec-focus.v1` session entry
+write path, and the taskflow conflict guard.
+
+## Entry contract
+
+The session entry name `galactica-status.openspec-focus.v1` is an
+**interface, not an ownership mark**: it predates this package and must stay
+byte-identical for existing sessions and external readers. A contract test
+(`test/contract.test.ts`) asserts byte-identity against the renderer's copy —
+runtime code never imports across packages; the suites enforce the name.
+
+External readers:
+
+- **`pi-openspec-gate`** (separate repository) — parses latest-wins
+  `galactica-status.openspec-focus.v1` entries, with explicit clears. Do not
+  change the entry shape or name.
+
+## Focus changes
+
+After each successful focus write this package emits the `pi.events` event
+`focus-changed` carrying the new focus data. The status renderer subscribes
+and repaints; no other consumer is required, and the package fails soft when
+nothing listens.
+
+## No slash command
+
+Focus is set only through the `openspec_focus` tool, on explicit Human
+direction or an exact declared OpenSpec Task handoff — never inferred. There
+is deliberately **no slash command**; clears and replacements happen through
+the tool's `clear` / `replace` actions under the same policy.

package/packages/work-state/index.ts

@@ -0,0 +1,160 @@
+import { StringEnum } from '@earendil-works/pi-ai';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import {
+  NO_OPEN_SPEC_FOCUS,
+  OPEN_SPEC_FOCUS_ENTRY_TYPE,
+  type OpenSpecFocus,
+  restoreOpenSpecFocus,
+  sameOpenSpecFocus,
+  sameTaskFocus,
+  taskflowRunFocus,
+  taskFocus,
+} from './src/focus.ts';
+
+const FOCUS_CHANGED_EVENT = 'focus-changed';
+
+type OpenSpecFocusAction = 'status' | 'set' | 'replace' | 'validate' | 'clear';
+
+export default function workState(pi: ExtensionAPI): void {
+  let currentFocus: OpenSpecFocus = NO_OPEN_SPEC_FOCUS;
+
+  pi.on('session_start', (_event, ctx) => {
+    currentFocus = restoreOpenSpecFocus(ctx.sessionManager.getBranch());
+  });
+
+  pi.on('session_tree', (_event, ctx) => {
+    currentFocus = restoreOpenSpecFocus(ctx.sessionManager.getBranch());
+  });
+
+  function persistAndApplyFocus(focus: OpenSpecFocus): void {
+    pi.appendEntry(OPEN_SPEC_FOCUS_ENTRY_TYPE, focus);
+    currentFocus = focus;
+    pi.events.emit(FOCUS_CHANGED_EVENT, focus);
+  }
+
+  function applyOpenSpecFocusAction(
+    action: OpenSpecFocusAction,
+    change?: string,
+    taskId?: string,
+  ): { ok: boolean; message: string; focus: OpenSpecFocus } {
+    const current = currentFocus;
+    const statusMessage = (focus: OpenSpecFocus): string =>
+      focus.mode === 'task'
+        ? `OpenSpec focus: ${focus.change} › ${focus.taskId}` +
+          (focus.awaitingValidation ? ' — awaiting Human validation' : '')
+        : 'OpenSpec focus: none';
+
+    if (action === 'status') {
+      return { ok: true, message: statusMessage(current), focus: current };
+    }
+    if (action === 'clear') {
+      persistAndApplyFocus(NO_OPEN_SPEC_FOCUS);
+      return {
+        ok: true,
+        message: 'OpenSpec focus cleared',
+        focus: NO_OPEN_SPEC_FOCUS,
+      };
+    }
+    if (action === 'validate') {
+      if (current.mode !== 'task') {
+        return {
+          ok: false,
+          message: 'OpenSpec focus has no task to validate',
+          focus: current,
+        };
+      }
+      const validated = { ...current, awaitingValidation: true };
+      if (!sameOpenSpecFocus(current, validated)) persistAndApplyFocus(validated);
+      return { ok: true, message: statusMessage(validated), focus: validated };
+    }
+
+    const requested = taskFocus(change, taskId);
+    if (!requested) {
+      return {
+        ok: false,
+        message: 'OpenSpec focus requires non-empty change and task identifiers',
+        focus: current,
+      };
+    }
+    if (
+      action === 'set' &&
+      current.mode === 'task' &&
+      !sameTaskFocus(current, requested)
+    ) {
+      return {
+        ok: false,
+        message:
+          `OpenSpec focus is ${current.change} › ${current.taskId}; ` +
+          'use replace to change it deliberately',
+        focus: current,
+      };
+    }
+    if (!sameOpenSpecFocus(current, requested)) persistAndApplyFocus(requested);
+    return {
+      ok: true,
+      message: statusMessage(requested),
+      focus: requested,
+    };
+  }
+
+  pi.on('tool_call', (event) => {
+    if (event.toolName !== 'taskflow') return;
+    const requested = taskflowRunFocus(event.input);
+
+    if (requested) {
+      if (currentFocus.mode === 'task' && !sameOpenSpecFocus(currentFocus, requested)) {
+        return {
+          block: true,
+          reason:
+            `OpenSpec focus is ${currentFocus.change} › ${currentFocus.taskId}; ` +
+            'clear or replace the OpenSpec focus (explicit Human direction) before starting a conflicting run',
+        };
+      }
+      if (!sameOpenSpecFocus(currentFocus, requested)) {
+        persistAndApplyFocus(requested);
+      }
+    }
+  });
+
+  pi.registerTool({
+    name: 'openspec_focus',
+    label: 'OpenSpec Focus',
+    description:
+      'Show, safely set, deliberately replace, validate, or clear branch-local OpenSpec Task focus. Use only for explicit Human direction or an exact declared OpenSpec Task handoff; never infer material Plan selection or Human validation',
+    promptSnippet:
+      'Manage exact branch-local OpenSpec Task focus with replacement safeguards',
+    parameters: Type.Object({
+      action: StringEnum(['status', 'set', 'replace', 'validate', 'clear'] as const),
+      change: Type.Optional(
+        Type.String({
+          description: 'Required for set and replace: the exact OpenSpec change ID',
+        }),
+      ),
+      task: Type.Optional(
+        Type.String({
+          description: 'Required for set and replace: the exact OpenSpec Task ID',
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const result = applyOpenSpecFocusAction(
+        params.action,
+        params.change,
+        params.task,
+      );
+      return {
+        content: [
+          {
+            type: 'text',
+            text: result.ok ? result.message : `Error: ${result.message}`,
+          },
+        ],
+        details: {
+          ok: result.ok,
+          focus: result.focus,
+        },
+      };
+    },
+  });
+}

package/packages/work-state/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "work-state",
+  "version": "1.0.0",
+  "private": true,
+  "description": "OpenSpec focus entry owner for the pi-stardeck cockpit",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "work-state",
+    "openspec"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}\" --ignore-path .prettierignore",
+    "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}\" --ignore-path .prettierignore",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --experimental-strip-types test/*.test.ts",
+    "check": "npm run format:check && npm run typecheck && npm test"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}

package/packages/work-state/src/focus.ts

@@ -0,0 +1,100 @@
+export const OPEN_SPEC_FOCUS_ENTRY_TYPE = 'galactica-status.openspec-focus.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' };
+
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/gu;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function normalizeTitlePart(value: string): string {
+  return value.replace(CONTROL_CHARACTERS, ' ').replace(/\s+/gu, ' ').trim();
+}
+
+function explicitId(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const normalized = normalizeTitlePart(value);
+  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 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 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)
+  );
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 
 import galacticaContextHeader from '../packages/pi-stardeck/index.js';
+import workState from '../packages/work-state/index.js';
 import galacticaStatus from '../packages/status/index.js';
 import footerTelemetry from '../packages/footer/index.js';
 import { registerStardeckHealth } from './health.js';
@@ -19,6 +20,7 @@ export const COCKPIT_COMPOSITION = [
 export default function piStardeck(pi: ExtensionAPI): void {
   registerPiStatus(pi);
   footerTelemetry(pi);
+  workState(pi);
   galacticaStatus(pi);
   galacticaContextHeader(pi, {
     surface: COCKPIT_SURFACES.contextHeader,