@aemonge-dev/pi-stardeck 0.10.0 → 0.12.0

package/packages/status/src/openspec.ts

@@ -408,14 +408,20 @@ export async function collectOpenSpec(options: {
     // Progress from `list` remains valid even if apply instructions are unavailable.
   }
 
-  const completedTasks = Math.max(
-    0,
-    Math.trunc(instructionProgress?.complete ?? change.completedTasks),
-  );
-  const totalTasks = Math.max(
-    0,
-    Math.trunc(instructionProgress?.total ?? change.totalTasks),
-  );
+  // File truth first: when the artifact (or apply) task list parsed, its
+  // done flags are what the Human actually ticks — the CLI's done-counting
+  // does not track custom-schema execution artifacts and pinned the Work
+  // 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.
+  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));
   const complete =
     change.status === 'complete' || (totalTasks > 0 && completedTasks >= totalTasks);
 

package/packages/status/src/publisher.ts

@@ -1,4 +1,4 @@
-import type { SessionSubject, SessionWorkFocus } from './active-work.ts';
+import type { SessionSubject } from './active-work.ts';
 import type { ActiveRunSpanView, ActiveRuntimeRuns } from './runtime-runs.ts';
 import type { TitleState } from './title-state.ts';
 import type { TurnCostSnapshot } from './turn-cost.ts';
@@ -24,7 +24,6 @@ export const GALACTICA_HEADER_CHANNEL = 'galactica-status:header';
 const OPEN_SPEC_WIDGET_ID = 'galactica.openspec';
 const OPEN_SPEC_SCOPE_SEPARATOR_WIDGET_ID = 'galactica.openspec-scope-separator';
 const OPEN_SPEC_PROGRESS_WIDGET_ID = 'galactica.openspec-progress';
-const SESSION_WORK_WIDGET_ID = 'galactica.work';
 const DIAGNOSTICS_WIDGET_ID = 'galactica.diagnostics';
 const ORCHESTRATION_WIDGET_ID = 'galactica.orchestration';
 
@@ -88,13 +87,6 @@ function openSpecColor(state: OpenSpecState): WidgetColor {
   return 'accent';
 }
 
-export function formatSessionWork(focus: SessionWorkFocus): string {
-  if (focus.state === 'clear') return 'Work · clear';
-  return focus.state === 'validation'
-    ? `Validate · ${focus.intent}`
-    : `Work · ${focus.intent}`;
-}
-
 export function formatOpenSpecOverview(overview: OpenSpecOverview): string {
   return (
     `${overview.completedPlans}/${overview.totalPlans}` +
@@ -209,21 +201,13 @@ export function buildWidgetSnapshots(
     openSpecFeedback?: OpenSpecFeedback;
     openSpecOverview?: OpenSpecOverview;
     openSpecProjectDetected?: boolean;
-    workFocus?: SessionWorkFocus;
   } = {},
 ): FancyFooterWidget[] {
   const compact = options.compact ?? false;
   const now = options.now ?? Date.now();
   const widgets: FancyFooterWidget[] = [];
 
-  const hasActiveFallback =
-    !options.openSpecOverview &&
-    Boolean(options.workFocus && options.workFocus.state !== 'clear');
-
-  if (
-    options.openSpecOverview ||
-    (options.openSpecProjectDetected === false && !hasActiveFallback)
-  ) {
+  if (options.openSpecOverview || options.openSpecProjectDetected === false) {
     widgets.push({
       id: OPEN_SPEC_SCOPE_SEPARATOR_WIDGET_ID,
       label: 'OpenSpec scope separator',
@@ -265,41 +249,7 @@ export function buildWidgetSnapshots(
   // Frozen contract: without an OpenSpec focus there is no progress surface —
   // no aggregate overview, no 'no OpenSpec' narration.
 
-  if (
-    !snapshot.openspec &&
-    !options.openSpecOverview &&
-    options.workFocus &&
-    options.workFocus.state !== 'clear'
-  ) {
-    const color: WidgetColor =
-      options.workFocus.state === 'validation' ? 'warning' : 'accent';
-    const glyph =
-      options.workFocus.state === 'validation'
-        ? { nerd: '◇⠀', emoji: '◇⠀', unicode: '◇⠀', ascii: '? ' }
-        : { nerd: '▶⠀', emoji: '▶⠀', unicode: '▶⠀', ascii: '> ' };
-    widgets.push({
-      id: SESSION_WORK_WIDGET_ID,
-      label: options.workFocus.state === 'validation' ? 'Validate' : 'Focus',
-      description:
-        options.workFocus.state === 'validation'
-          ? 'Session focus awaiting Human validation; its title remains in the header'
-          : 'Active Session Work focus; its title remains in the header',
-      content: {
-        type: 'text',
-        text: options.workFocus.state === 'validation' ? 'Validate' : 'Focus',
-      },
-      icon: { glyphs: glyph, color },
-      style: { textColor: color },
-      layout: {
-        row: 0,
-        position: 0,
-        align: 'right',
-        fill: 'none',
-      },
-    });
-  }
-
-  if (!snapshot.openspec && !options.workFocus && options.openSpecFeedback) {
+  if (!snapshot.openspec && options.openSpecFeedback) {
     const unavailable = options.openSpecFeedback === 'unavailable';
     const color: WidgetColor = unavailable ? 'warning' : 'dim';
     const stateText =
@@ -466,11 +416,7 @@ export const HEADER_LIFECYCLES = [
 
 export type HeaderLifecycle = (typeof HEADER_LIFECYCLES)[number];
 
-export const HEADER_SELECTION_SOURCES = [
-  'openspec',
-  'session-work',
-  'subject',
-] as const;
+export const HEADER_SELECTION_SOURCES = ['openspec', 'subject'] as const;
 
 export type HeaderSelection = {
   source: (typeof HEADER_SELECTION_SOURCES)[number];
@@ -547,7 +493,6 @@ function selectedOpenSpecTitles(
 export function headerSelection(options: {
   openSpec?: OpenSpecState | null;
   focusedTaskId?: string;
-  workFocus?: SessionWorkFocus;
   subject?: SessionSubject;
 }): HeaderSelection | null {
   if (options.openSpec) {
@@ -557,13 +502,6 @@ export function headerSelection(options: {
       color: openSpecColor(options.openSpec),
     };
   }
-  if (options.workFocus && options.workFocus.state !== 'clear') {
-    return {
-      source: 'session-work',
-      titles: [normalizeInline(options.workFocus.intent)],
-      color: options.workFocus.state === 'validation' ? 'warning' : 'accent',
-    };
-  }
   if (options.subject && options.subject.state === 'set') {
     return {
       source: 'subject',
@@ -884,7 +822,6 @@ export function buildHeaderStatusEvent(
   options: {
     openSpec?: OpenSpecState | null;
     focusedTaskId?: string;
-    workFocus?: SessionWorkFocus;
     subject?: SessionSubject;
     orchestration?: OrchestrationState | null;
     lifecycle?: HeaderLifecycle;
@@ -932,7 +869,7 @@ export function buildHeaderStatusEvent(
     orchestrationLifecycle ??
     options.lifecycle ??
     headerLifecycleForActivity(activity) ??
-    (options.workFocus?.state === 'validation' ? 'waiting' : 'listening');
+    'listening';
   const lifecycle: HeaderLifecycle = blocked
     ? 'blocked'
     : options.lifecycle === 'aborted'
@@ -942,7 +879,7 @@ export function buildHeaderStatusEvent(
   const projectedActivity =
     activityPath !== undefined ? { activityPath } : activity ? { activity } : {};
   const selection = headerSelection(options);
-  const approvalRequired = options.workFocus?.state === 'validation';
+  const approvalRequired = false;
   const suggestion = headerSuggestion({
     lifecycle,
     activity,
@@ -960,13 +897,6 @@ export function buildHeaderStatusEvent(
       color: openSpecColor(state),
       ...projectedActivity,
     };
-  } else if (options.workFocus && options.workFocus.state !== 'clear') {
-    work = {
-      lifecycle,
-      titles: [normalizeInline(options.workFocus.intent)],
-      color: options.workFocus.state === 'validation' ? 'warning' : 'accent',
-      ...projectedActivity,
-    };
   } else if (options.orchestration) {
     work = {
       lifecycle,

package/packages/status/src/reducer.ts

@@ -1,5 +1,5 @@
 import type { LedgerEvent } from './ledger.ts';
-import type { OpenSpecFocus, SessionSubject, SessionWorkFocus } from './active-work.ts';
+import type { OpenSpecFocus, SessionSubject } from './active-work.ts';
 import type {
   CockpitSnapshot,
   ProgressFact,
@@ -19,7 +19,6 @@ import type {
 
 export type ReducerFacts = {
   openSpec: OpenSpecFocus;
-  work: SessionWorkFocus;
   subject: SessionSubject;
   runs: ReadonlyMap<string, RunSpan>;
   progress: ProgressFact | null;
@@ -30,7 +29,6 @@ export const NO_SELECTION: SelectionState = { kind: 'none' };
 export function emptyFacts(): ReducerFacts {
   return {
     openSpec: { mode: 'none' },
-    work: { state: 'clear' },
     subject: { state: 'clear' },
     runs: new Map(),
     progress: null,
@@ -40,7 +38,6 @@ export function emptyFacts(): ReducerFacts {
 /** The single selection resolver. Priority order is contract-frozen. */
 export function resolveSelection(facts: {
   openSpec: OpenSpecFocus;
-  work: SessionWorkFocus;
   subject: SessionSubject;
 }): SelectionState {
   if (facts.openSpec.mode === 'task') {
@@ -50,13 +47,6 @@ export function resolveSelection(facts: {
       task: facts.openSpec.taskId,
     };
   }
-  if (facts.work.state !== 'clear') {
-    return {
-      kind: 'session-work',
-      intent: facts.work.intent,
-      phase: facts.work.state === 'validation' ? 'validation' : 'active',
-    };
-  }
   if (facts.subject.state === 'set') {
     return { kind: 'subject', title: facts.subject.title };
   }
@@ -73,8 +63,6 @@ export function applyEvent(facts: ReducerFacts, event: LedgerEvent): ReducerFact
   switch (event.type) {
     case 'focus/openspec':
       return { ...facts, openSpec: event.focus };
-    case 'focus/work':
-      return { ...facts, work: event.work };
     case 'focus/subject':
       return { ...facts, subject: event.subject };
     case 'run/start': {
@@ -153,12 +141,6 @@ export function deriveTitle(snapshot: CockpitSnapshot): string {
     case 'openspec-task':
       detail = `${selection.change} › ${selection.task}`;
       break;
-    case 'session-work':
-      detail =
-        selection.phase === 'validation'
-          ? `Validate › ${selection.intent}`
-          : selection.intent;
-      break;
     case 'subject':
       detail = selection.title;
       break;

package/packages/status/src/types.ts

@@ -193,7 +193,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,