@dreki-gg/pi-plan-mode 0.26.0 → 0.26.1

package/extensions/plan-mode/effects/filesystem.ts

@@ -1,65 +0,0 @@
-/**
- * FileSystem service — the single seam for plan-mode disk I/O.
- *
- * Storage programs depend on this `Context.Tag` rather than touching
- * `node:fs/promises` directly, which makes them trivially testable and keeps
- * all failure modes typed (`PlanReadError` / `PlanWriteError`).
- */
-
-import { Context, Effect } from 'effect';
-import { mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
-import { PlanReadError, PlanWriteError } from '../errors.js';
-import { writeFileAtomic } from '../storage/atomic-write.js';
-
-export interface FileSystemService {
-  readonly readFileString: (path: string) => Effect.Effect<string, PlanReadError>;
-  readonly writeFileString: (path: string, data: string) => Effect.Effect<void, PlanWriteError>;
-  readonly writeFileAtomic: (path: string, data: string) => Effect.Effect<void, PlanWriteError>;
-  readonly makeDir: (path: string) => Effect.Effect<void, PlanWriteError>;
-  readonly listDirectories: (path: string) => Effect.Effect<string[], PlanReadError>;
-  readonly removeFile: (path: string) => Effect.Effect<void, PlanWriteError>;
-}
-
-export class FileSystem extends Context.Tag('PlanMode/FileSystem')<
-  FileSystem,
-  FileSystemService
->() {}
-
-export const nodeFileSystemService: FileSystemService = {
-  readFileString: (path) =>
-    Effect.tryPromise({
-      try: () => readFile(path, 'utf-8'),
-      catch: (cause) => new PlanReadError({ path, cause }),
-    }),
-
-  writeFileString: (path, data) =>
-    Effect.tryPromise({
-      try: () => writeFile(path, data, 'utf-8'),
-      catch: (cause) => new PlanWriteError({ path, cause }),
-    }),
-
-  writeFileAtomic: (path, data) => writeFileAtomic(path, data),
-
-  makeDir: (path) =>
-    Effect.tryPromise({
-      try: async () => {
-        await mkdir(path, { recursive: true });
-      },
-      catch: (cause) => new PlanWriteError({ path, cause }),
-    }),
-
-  listDirectories: (path) =>
-    Effect.tryPromise({
-      try: async () => {
-        const entries = await readdir(path, { withFileTypes: true });
-        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-      },
-      catch: (cause) => new PlanReadError({ path, cause }),
-    }),
-
-  removeFile: (path) =>
-    Effect.tryPromise({
-      try: () => unlink(path),
-      catch: (cause) => new PlanWriteError({ path, cause }),
-    }),
-};

package/extensions/plan-mode/effects/runtime.ts

@@ -1,24 +0,0 @@
-/**
- * Live Effect runtime for the plan-mode extension.
- *
- * Build the layer once inside the extension entry and run storage programs
- * through the `runPlanIO` bridge so the imperative pi event handlers keep their
- * `await fn(...)` shape.
- */
-
-import { Effect, Layer } from 'effect';
-import { FileSystem, nodeFileSystemService } from './filesystem.js';
-
-export function makeRuntimeLayer(): Layer.Layer<FileSystem> {
-  return Layer.succeed(FileSystem, nodeFileSystemService);
-}
-
-/** Build a bridge that runs storage programs against the live filesystem layer. */
-export function makePlanRuntime() {
-  const layer = makeRuntimeLayer();
-  return function runPlanIO<A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> {
-    return Effect.runPromise(program.pipe(Effect.provide(layer)));
-  };
-}
-
-export type RunPlanIO = ReturnType<typeof makePlanRuntime>;

package/extensions/plan-mode/errors.ts

@@ -1,105 +0,0 @@
-/**
- * Tagged errors for plan-mode disk I/O and JSONL validation.
- *
- * These replace ad-hoc `throw new Error(...)` so storage programs surface
- * typed, inspectable failures. They are mapped back to user-facing strings at
- * the tool boundary via `errorMessage`.
- */
-
-import { Data } from 'effect';
-
-export class PlanReadError extends Data.TaggedError('PlanReadError')<{
-  readonly path: string;
-  readonly cause: unknown;
-}> {
-  get message(): string {
-    return `Failed to read ${this.path}: ${causeMessage(this.cause)}`;
-  }
-}
-
-export class PlanWriteError extends Data.TaggedError('PlanWriteError')<{
-  readonly path: string;
-  readonly cause: unknown;
-}> {
-  get message(): string {
-    return `Failed to write ${this.path}: ${causeMessage(this.cause)}`;
-  }
-}
-
-export class JsonlParseError extends Data.TaggedError('JsonlParseError')<{
-  readonly path: string;
-  readonly line: number;
-  readonly cause?: unknown;
-}> {
-  get message(): string {
-    return `Invalid JSONL in ${this.path} at line ${this.line}: ${causeMessage(this.cause)}`;
-  }
-}
-
-export class JsonlValidationError extends Data.TaggedError('JsonlValidationError')<{
-  readonly path: string;
-  readonly line: number;
-  readonly reason: string;
-}> {
-  get message(): string {
-    return `Invalid record in ${this.path} at line ${this.line}: ${this.reason}`;
-  }
-}
-
-export class MissingMetaRecord extends Data.TaggedError('MissingMetaRecord')<{
-  readonly path: string;
-}> {
-  get message(): string {
-    return `${this.path} is missing meta record`;
-  }
-}
-
-export class TaskNotFound extends Data.TaggedError('TaskNotFound')<{
-  readonly planDir: string;
-  readonly taskId: string;
-}> {
-  get message(): string {
-    return `Task not found: ${this.taskId}`;
-  }
-}
-
-export class TasksFileNotFound extends Data.TaggedError('TasksFileNotFound')<{
-  readonly planDir: string;
-}> {
-  get message(): string {
-    return `No tasks.jsonl found in ${this.planDir}`;
-  }
-}
-
-export type PlanStorageError =
-  | PlanReadError
-  | PlanWriteError
-  | JsonlParseError
-  | JsonlValidationError
-  | MissingMetaRecord
-  | TaskNotFound
-  | TasksFileNotFound;
-
-export function causeMessage(cause: unknown): string {
-  if (cause instanceof Error) return cause.message;
-  return String(cause);
-}
-
-export function errorMessage(error: unknown): string {
-  if (error instanceof Error) return error.message;
-  if (typeof error === 'object' && error !== null && 'message' in error) {
-    const message = (error as { message?: unknown }).message;
-    if (typeof message === 'string') return message;
-  }
-  return String(error);
-}
-
-/** Convert any error (including tagged errors) into a native Error for the tool boundary. */
-export function toNativeError(error: unknown): Error {
-  if (error instanceof Error) return error;
-  const native = new Error(errorMessage(error));
-  if (typeof error === 'object' && error !== null && '_tag' in error) {
-    native.name = String((error as { _tag: unknown })._tag);
-  }
-  return native;
-}

package/extensions/plan-mode/initiative.ts

@@ -1,172 +0,0 @@
-/**
- * Initiative logic — ready-work computation and the initiative→plan projection.
- *
- * Two layers live here:
- *   - PURE: `computePlanReadiness`, `isInitiativeFinalizable`, `initiativeRollup`
- *     reason over a plans-manifest snapshot with no IO. They are the basis for
- *     "what work is unblocked right now" — the foundation for phase-2 subagent
- *     fan-out.
- *   - IO: `reconcileInitiativeStatus` / `reconcileInitiativeForPlan` keep an
- *     initiative's registry status a PROJECTION of its member plans, mirroring
- *     `reconcilePlanStatus` one level up. They read the PLANS manifest, so they
- *     live here (not in `initiatives-manifest.ts`) to keep the dependency
- *     direction one-way: initiative.ts → {plans-manifest, initiatives-manifest}.
- */
-
-import { Effect } from 'effect';
-import { FileSystem } from './effects/filesystem.js';
-import type { JsonlParseError, JsonlValidationError, PlanWriteError } from './errors.js';
-import { readPlansManifest, type PlanManifestEntry } from './storage/plans-manifest.js';
-import {
-  applyInitiativeUpsert,
-  mutateInitiativesManifest,
-} from './storage/initiatives-manifest.js';
-import type { PlanStatus } from './types.js';
-
-// ── Pure: readiness + projection rules ───────────────────────────────────────
-
-export interface PlanReadiness {
-  name: string;
-  /** True when every plan in `depends_on` is `done`. */
-  ready: boolean;
-  /** Dependency plan names that are not yet `done` (unknown deps count too). */
-  blockedBy: string[];
-}
-
-/**
- * For each `in-progress` plan, whether all of its plan-level dependencies are
- * `done`. Only a `done` dependency unblocks — a missing, in-progress, or
- * terminally-closed (superseded/abandoned) dependency keeps a plan blocked.
- */
-export function computePlanReadiness(plans: readonly PlanManifestEntry[]): PlanReadiness[] {
-  const statusByName = new Map(plans.map((plan) => [plan.name, plan.status]));
-  return plans
-    .filter((plan) => plan.status === 'in-progress')
-    .map((plan) => {
-      const deps = plan.depends_on ?? [];
-      const blockedBy = deps.filter((dep) => statusByName.get(dep) !== 'done');
-      return { name: plan.name, ready: blockedBy.length === 0, blockedBy };
-    });
-}
-
-/** Member plans of an initiative (linked by name in the plans manifest). */
-export function membersOf(
-  initiative: string,
-  plans: readonly PlanManifestEntry[],
-): PlanManifestEntry[] {
-  return plans.filter((plan) => plan.initiative === initiative);
-}
-
-/**
- * An initiative is finalizable (`done`) when it has ≥1 member plan AND every
- * member is terminal (no member is `in-progress`). Mirrors the plan-level rule
- * one level up.
- */
-export function isInitiativeFinalizable(
-  initiative: string,
-  plans: readonly PlanManifestEntry[],
-): boolean {
-  const members = membersOf(initiative, plans);
-  if (members.length === 0) return false;
-  return members.every((plan) => plan.status !== 'in-progress');
-}
-
-export interface InitiativeMemberRow {
-  name: string;
-  title: string;
-  status: PlanStatus;
-  /** Present for in-progress members. */
-  ready?: boolean;
-  blockedBy?: string[];
-}
-
-export interface InitiativeRollup {
-  name: string;
-  total: number;
-  done: number;
-  /** Terminal but not done (superseded / abandoned). */
-  closed: number;
-  inProgress: number;
-  ready: number;
-  blocked: number;
-  members: InitiativeMemberRow[];
-}
-
-/** Aggregate an initiative's member plans into counts + per-member readiness. */
-export function initiativeRollup(
-  initiative: string,
-  plans: readonly PlanManifestEntry[],
-): InitiativeRollup {
-  const members = membersOf(initiative, plans);
-  const readiness = new Map(computePlanReadiness(plans).map((row) => [row.name, row]));
-
-  let done = 0;
-  let closed = 0;
-  let inProgress = 0;
-  let ready = 0;
-  let blocked = 0;
-
-  const rows: InitiativeMemberRow[] = members.map((plan) => {
-    if (plan.status === 'done') done += 1;
-    else if (plan.status === 'in-progress') inProgress += 1;
-    else closed += 1; // superseded / abandoned
-
-    const row: InitiativeMemberRow = { name: plan.name, title: plan.title, status: plan.status };
-    if (plan.status === 'in-progress') {
-      const r = readiness.get(plan.name);
-      row.ready = r?.ready ?? true;
-      row.blockedBy = r?.blockedBy ?? [];
-      if (row.ready) ready += 1;
-      else blocked += 1;
-    }
-    return row;
-  });
-
-  return { name: initiative, total: members.length, done, closed, inProgress, ready, blocked, members: rows };
-}
-
-// ── IO: keep initiative registry status a projection of member plans ─────────
-
-type ReconcileError = JsonlParseError | JsonlValidationError | PlanWriteError;
-
-/**
- * Re-derive an initiative's registry status from its member plans.
- *
- * Like `reconcilePlanStatus`: only reflects state for a KNOWN initiative (never
- * conjures an entry), and never clobbers a manually-set terminal status
- * (`superseded` / `abandoned`). Only `in-progress` ⇄ `done` is derived.
- */
-export function reconcileInitiativeStatus(
-  name: string,
-): Effect.Effect<void, ReconcileError, FileSystem> {
-  // The whole read-decide-write runs under the initiatives lock so a concurrent
-  // writer cannot slip a status change between our read and our write.
-  return mutateInitiativesManifest((initiatives) =>
-    Effect.gen(function* () {
-      const existing = initiatives.find((entry) => entry.name === name);
-      if (!existing) return false;
-      if (existing.status === 'superseded' || existing.status === 'abandoned') return false;
-      const plans = yield* readPlansManifest();
-      const status: PlanStatus = isInitiativeFinalizable(name, plans) ? 'done' : 'in-progress';
-      if (existing.status === status) return false;
-      applyInitiativeUpsert(initiatives, name, { status, title: existing.title });
-      return true;
-    }),
-  );
-}
-
-/**
- * Reconcile the initiative that a given plan belongs to (no-op when the plan is
- * standalone). Call this after any plan-status write so the initiative level
- * stays in sync without callers needing to know the parent name.
- */
-export function reconcileInitiativeForPlan(
-  planName: string,
-): Effect.Effect<void, ReconcileError, FileSystem> {
-  return Effect.gen(function* () {
-    const plans = yield* readPlansManifest();
-    const plan = plans.find((entry) => entry.name === planName);
-    if (!plan?.initiative) return;
-    yield* reconcileInitiativeStatus(plan.initiative);
-  });
-}

package/extensions/plan-mode/plan-storage.ts

@@ -1,6 +0,0 @@
-export {
-  loadHandoff,
-  readAndClearExecPending,
-  saveHandoff,
-  writeExecPending,
-} from './storage/plan-storage.js';

package/extensions/plan-mode/reconcile.ts

@@ -1,235 +0,0 @@
-/**
- * Drift detection + repair between `tasks.jsonl` reality and registry status.
- *
- * Drift happens in both directions (FEEDBACK #6):
- *   - tasks all done but registry `in-progress` (completion never recorded), and
- *   - registry `in-progress`/`done` disagreeing with task state generally.
- *
- * It also surfaces two un-trackable classes:
- *   - registry-only plans (an entry with no `tasks.jsonl` directory), and
- *   - orphan task dirs (a `tasks.jsonl` with no registry entry).
- *
- * `collectPlanDrift` is a pure read; `applyReconcile` repairs only the safe
- * `in-progress` ⇄ `done` projection and never touches terminal statuses.
- */
-
-import { Effect } from 'effect';
-import { FileSystem } from './effects/filesystem.js';
-import type {
-  JsonlParseError,
-  JsonlValidationError,
-  MissingMetaRecord,
-  PlanWriteError,
-} from './errors.js';
-import { readPlansManifest, reconcilePlanStatus } from './storage/plans-manifest.js';
-import { readInitiativesManifest } from './storage/initiatives-manifest.js';
-import {
-  isInitiativeFinalizable,
-  membersOf,
-  reconcileInitiativeForPlan,
-  reconcileInitiativeStatus,
-} from './initiative.js';
-import { readTasksJsonl } from './storage/task-storage.js';
-import { isPlanFinalizable } from './task-status.js';
-import type { PlanStatus } from './types.js';
-
-const PLANS_DIR = '.plans';
-
-export interface PlanDriftRow {
-  name: string;
-  /** Registry status, or `undefined` when there is a task dir but no entry. */
-  registryStatus?: PlanStatus;
-  title?: string;
-  /** Derived from tasks: `done` when finalizable, else `in-progress`. */
-  derivedStatus?: 'in-progress' | 'done';
-  /** Resolved/total task counts when a tasks.jsonl exists. */
-  resolved?: number;
-  total?: number;
-  /** True when a `tasks.jsonl` snapshot was found for this plan. */
-  hasTasks: boolean;
-  /**
-   * Drift class:
-   *   - 'status'        : registry status disagrees with derived task status
-   *   - 'registry-only' : registry entry but no tasks.jsonl dir
-   *   - 'orphan'        : tasks.jsonl dir but no registry entry
-   *   - undefined       : in sync
-   */
-  drift?: 'status' | 'registry-only' | 'orphan';
-  /**
-   * For `status` drift, the direction the registry would move if projected from
-   * tasks:
-   *   - 'upgrade'   : registry `in-progress` → tasks `done` (safe; auto-repaired)
-   *   - 'downgrade' : registry `done` → tasks `in-progress` (NOT auto-repaired)
-   *
-   * A downgrade almost always means "work merged but tasks were never marked
-   * done" — auto-projecting tasks→registry there would REGRESS a finished plan
-   * back to in-progress (the wrong direction). We surface it for a human to
-   * resolve by marking the tasks done instead.
-   */
-  direction?: 'upgrade' | 'downgrade';
-}
-
-type CollectError = JsonlParseError | JsonlValidationError | MissingMetaRecord;
-
-/** Walk every plan (registry + task dirs) and classify drift. Pure read. */
-export function collectPlanDrift(): Effect.Effect<PlanDriftRow[], CollectError, FileSystem> {
-  return Effect.gen(function* () {
-    const fs = yield* FileSystem;
-    const manifest = yield* readPlansManifest();
-    const dirs = yield* Effect.orElseSucceed(fs.listDirectories(PLANS_DIR), () => [] as string[]);
-    // Ignore dotfile dirs like `.archive`.
-    const taskDirs = new Set(dirs.filter((name) => !name.startsWith('.')));
-
-    const rows: PlanDriftRow[] = [];
-    const seen = new Set<string>();
-
-    for (const entry of manifest) {
-      seen.add(entry.name);
-      const snapshot = yield* readTasksJsonl(`${PLANS_DIR}/${entry.name}`);
-      if (!snapshot) {
-        rows.push({
-          name: entry.name,
-          registryStatus: entry.status,
-          title: entry.title,
-          hasTasks: false,
-          drift: 'registry-only',
-        });
-        continue;
-      }
-      const total = snapshot.tasks.length;
-      const resolved = snapshot.tasks.filter(
-        (t) => t.status === 'done' || t.status === 'skipped',
-      ).length;
-      const derivedStatus = isPlanFinalizable(snapshot.tasks) ? 'done' : 'in-progress';
-      // Terminal statuses (superseded/abandoned) are intentional — never drift.
-      const isTerminalManual = entry.status === 'superseded' || entry.status === 'abandoned';
-      const drift = !isTerminalManual && entry.status !== derivedStatus ? 'status' : undefined;
-      const direction =
-        drift === 'status'
-          ? derivedStatus === 'done'
-            ? ('upgrade' as const)
-            : ('downgrade' as const)
-          : undefined;
-      rows.push({
-        name: entry.name,
-        registryStatus: entry.status,
-        title: entry.title,
-        derivedStatus,
-        resolved,
-        total,
-        hasTasks: true,
-        drift,
-        direction,
-      });
-    }
-
-    // Orphan task dirs: have tasks.jsonl but no registry entry.
-    for (const name of taskDirs) {
-      if (seen.has(name)) continue;
-      const snapshot = yield* readTasksJsonl(`${PLANS_DIR}/${name}`);
-      if (!snapshot) continue;
-      const total = snapshot.tasks.length;
-      const resolved = snapshot.tasks.filter(
-        (t) => t.status === 'done' || t.status === 'skipped',
-      ).length;
-      rows.push({
-        name,
-        title: snapshot.meta.title,
-        derivedStatus: isPlanFinalizable(snapshot.tasks) ? 'done' : 'in-progress',
-        resolved,
-        total,
-        hasTasks: true,
-        drift: 'orphan',
-      });
-    }
-
-    return rows;
-  });
-}
-
-// ── Initiative-level drift ───────────────────────────────────────────────────
-
-export interface InitiativeDriftRow {
-  name: string;
-  registryStatus: PlanStatus;
-  title: string;
-  /** Projected from member plans: `done` when finalizable, else `in-progress`. */
-  derivedStatus: 'in-progress' | 'done';
-  members: number;
-  /** 'status' when the registry status disagrees with the projection. */
-  drift?: 'status';
-}
-
-/** Compare each initiative's registry status against its member-plan projection. */
-export function collectInitiativeDrift(): Effect.Effect<
-  InitiativeDriftRow[],
-  CollectError,
-  FileSystem
-> {
-  return Effect.gen(function* () {
-    const initiatives = yield* readInitiativesManifest();
-    const plans = yield* readPlansManifest();
-    return initiatives.map((entry) => {
-      const derivedStatus: 'in-progress' | 'done' = isInitiativeFinalizable(entry.name, plans)
-        ? 'done'
-        : 'in-progress';
-      // Terminal statuses (superseded/abandoned) are intentional — never drift.
-      const isTerminalManual = entry.status === 'superseded' || entry.status === 'abandoned';
-      const drift = !isTerminalManual && entry.status !== derivedStatus ? ('status' as const) : undefined;
-      return {
-        name: entry.name,
-        registryStatus: entry.status,
-        title: entry.title,
-        derivedStatus,
-        members: membersOf(entry.name, plans).length,
-        drift,
-      };
-    });
-  });
-}
-
-/** Repair `status`-class initiative drift by re-projecting from member plans. */
-export function applyInitiativeReconcile(
-  rows: InitiativeDriftRow[],
-): Effect.Effect<InitiativeDriftRow[], CollectError | PlanWriteError, FileSystem> {
-  return Effect.gen(function* () {
-    const repaired: InitiativeDriftRow[] = [];
-    for (const row of rows) {
-      if (row.drift !== 'status') continue;
-      yield* reconcileInitiativeStatus(row.name);
-      repaired.push(row);
-    }
-    return repaired;
-  });
-}
-
-/**
- * Repair `status`-class drift by projecting derived status into the registry.
- *
- * Safety: only `upgrade` drift (registry `in-progress` → tasks `done`) is
- * auto-repaired. A `downgrade` (registry `done` → tasks `in-progress`) is
- * reported but NEVER auto-applied — it almost always means work merged without
- * marking tasks done, and projecting tasks→registry there would regress a
- * finished plan. The human resolves it by marking the tasks done instead.
- *
- * Orphans and registry-only rows are likewise reported but not auto-fixed.
- * Returns the rows that were repaired.
- */
-export function applyReconcile(
-  rows: PlanDriftRow[],
-): Effect.Effect<PlanDriftRow[], CollectError | PlanWriteError, FileSystem> {
-  return Effect.gen(function* () {
-    const repaired: PlanDriftRow[] = [];
-    for (const row of rows) {
-      if (row.drift !== 'status' || !row.derivedStatus) continue;
-      // Guard against the wrong-direction projection: never auto-regress a
-      // `done` plan back to `in-progress`.
-      if (row.direction === 'downgrade') continue;
-      yield* reconcilePlanStatus(row.name, row.derivedStatus === 'done', row.title);
-      // Repairing a plan's status can flip its parent initiative's projection.
-      yield* reconcileInitiativeForPlan(row.name);
-      repaired.push(row);
-    }
-    return repaired;
-  });
-}