@tianhai/pi-workflow-kit 0.5.3 → 0.6.0

package/docs/plans/completed/2026-04-09-workflow-next-handoff-state-implementation.md

@@ -1,253 +0,0 @@
-# /workflow-next Handoff State Implementation Plan
-
-> **REQUIRED SUB-SKILL:** Use the executing-tasks skill to implement this plan task-by-task.
-
-**Goal:** Make `/workflow-next` preserve prior completed workflow history for same-feature handoffs, enforce immediate-next-only transitions, and rename the persisted local state file with legacy fallback.
-
-**Architecture:** Add a small workflow-next state helper that validates allowed handoffs and derives the workflow snapshot for the new session. Update the workflow monitor to seed the new session through `ctx.newSession({ setup })` with derived workflow state plus fresh monitor state, and add focused tests for validation, state derivation, and file migration behavior.
-
-**Tech Stack:** TypeScript, Vitest, pi extension API (`ctx.newSession({ setup })`, `SessionManager.appendCustomEntry`)
-
----
-
-## Verification
-
-All tasks completed. Final test results:
-- `tests/extension/workflow-monitor/workflow-next-command.test.ts` — 17/17 pass
-- `tests/extension/workflow-monitor/state-persistence.test.ts` — 25/25 pass
-- `tests/extension/workflow-monitor/` (full suite) — 360/360 pass
-
-No regressions. All acceptance criteria met.
-
-
----
-
-### Task 1: Add failing tests for workflow-next handoff validation and state seeding
-
-**Type:** code
-**TDD scenario:** Modifying tested code — run existing tests first
-
-**Files:**
-- Modify: `tests/extension/workflow-monitor/workflow-next-command.test.ts`
-- Test: `tests/extension/workflow-monitor/workflow-next-command.test.ts`
-
-**Step 1: Write the failing tests**
-
-Add tests covering:
-- allows `plan -> execute` only when `plan` is complete
-- rejects same-phase handoff
-- rejects backward handoff
-- rejects direct jump handoff
-- rejects handoff when current phase is active
-- seeds new session setup with derived workflow state preserving earlier completed phases, artifacts, and prompted flags
-- resets TDD/debug/verification state in the seeded session snapshot
-
-**Step 2: Run test to verify it fails**
-
-Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts`
-Expected: FAIL with missing validation and missing setup-state assertions
-
-**Step 3: Write minimal implementation support in test scaffolding only if needed**
-
-If needed, extend the fake `ctx.newSession` stub in the test so it records the `setup` callback and lets the test invoke it with a fake session manager that captures appended custom entries.
-
-**Step 4: Run test to verify it still fails for the intended production behavior gap**
-
-Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts`
-Expected: FAIL only on the new assertions tied to unimplemented production code
-
-**Step 5: Commit**
-
-```bash
-git add tests/extension/workflow-monitor/workflow-next-command.test.ts
-git commit -m "test: cover workflow-next handoff validation"
-```
-
-### Task 2: Add failing tests for state-file rename and legacy fallback
-
-**Type:** code
-**TDD scenario:** Modifying tested code — run existing tests first
-
-**Files:**
-- Modify: `tests/extension/workflow-monitor/state-persistence.test.ts`
-- Test: `tests/extension/workflow-monitor/state-persistence.test.ts`
-
-**Step 1: Write the failing tests**
-
-Add tests covering:
-- `getStateFilePath()` returns `.pi/workflow-kit-state.json`
-- `reconstructState()` prefers `.pi/workflow-kit-state.json` when present
-- `reconstructState()` falls back to `.pi/superpowers-state.json` when the new file is absent
-- extension persistence writes the new filename only
-
-**Step 2: Run test to verify it fails**
-
-Run: `npx vitest run tests/extension/workflow-monitor/state-persistence.test.ts`
-Expected: FAIL because current code still uses `.pi/superpowers-state.json`
-
-**Step 3: Keep test fixtures minimal**
-
-Reuse existing `withTempCwd()` and fake pi helpers. When testing persistence wiring, assert against files under `.pi/` in the temp directory rather than broad repo state.
-
-**Step 4: Run test to verify it still fails for the intended production behavior gap**
-
-Run: `npx vitest run tests/extension/workflow-monitor/state-persistence.test.ts`
-Expected: FAIL only on filename/migration assertions
-
-**Step 5: Commit**
-
-```bash
-git add tests/extension/workflow-monitor/state-persistence.test.ts
-git commit -m "test: cover workflow state file migration"
-```
-
-### Task 3: Implement workflow-next handoff validation and derived state helper
-
-**Type:** code
-**TDD scenario:** New feature — full TDD cycle
-
-**Files:**
-- Create: `extensions/workflow-monitor/workflow-next-state.ts`
-- Modify: `extensions/workflow-monitor.ts`
-- Test: `tests/extension/workflow-monitor/workflow-next-command.test.ts`
-
-**Step 1: Write the helper module with pure functions**
-
-Implement functions such as:
-- `getImmediateNextPhase(currentPhase)`
-- `validateWorkflowNextRequest(currentState, requestedPhase)`
-- `deriveWorkflowHandoffState(currentState, requestedPhase)`
-
-Behavior:
-- require an existing current phase
-- require current phase status to be exactly `complete`
-- allow only the immediate next phase
-- reject same/backward/direct-jump handoffs with precise messages
-- derive workflow state with earlier phases `complete`, target `active`, later `pending`
-- preserve earlier-phase artifacts and prompted flags
-
-**Step 2: Update `/workflow-next` to use the helper and seed session state**
-
-In `extensions/workflow-monitor.ts`:
-- import the helper functions
-- validate before calling `ctx.newSession(...)`
-- use `ctx.newSession({ parentSession, setup })`
-- inside `setup`, append a `superpowers_state` custom entry containing:
-  - derived `workflow`
-  - fresh `tdd` from `TDD_DEFAULTS`
-  - fresh `debug` from `DEBUG_DEFAULTS`
-  - fresh `verification` from `VERIFICATION_DEFAULTS`
-  - `savedAt: Date.now()`
-- keep the editor prefill behavior unchanged
-
-**Step 3: Run targeted tests**
-
-Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts`
-Expected: PASS
-
-**Step 4: Review for YAGNI and edge cases**
-
-Verify:
-- helper stays pure and focused
-- no generic tracker semantics are changed outside `/workflow-next`
-- invalid requests exit before session creation
-
-**Step 5: Commit**
-
-```bash
-git add extensions/workflow-monitor/workflow-next-state.ts extensions/workflow-monitor.ts tests/extension/workflow-monitor/workflow-next-command.test.ts
-git commit -m "feat: preserve workflow state across workflow-next"
-```
-
-### Task 4: Implement state-file rename with legacy fallback
-
-**Type:** code
-**TDD scenario:** Modifying tested code — run existing tests first
-
-**Files:**
-- Modify: `extensions/workflow-monitor.ts`
-- Test: `tests/extension/workflow-monitor/state-persistence.test.ts`
-
-**Step 1: Update state file path helpers**
-
-In `extensions/workflow-monitor.ts`:
-- change `getStateFilePath()` to return `.pi/workflow-kit-state.json`
-- add a legacy-path helper for `.pi/superpowers-state.json` if needed
-- update `reconstructState()` to check new path first, then legacy path
-
-**Step 2: Keep persistence write path singular**
-
-Ensure `persistState()` writes only the new path and does not continue writing the legacy file.
-
-**Step 3: Run targeted tests**
-
-Run: `npx vitest run tests/extension/workflow-monitor/state-persistence.test.ts`
-Expected: PASS
-
-**Step 4: Verify no unintended regressions in reconstruction logic**
-
-Confirm the existing session-entry reconstruction behavior still works when no file exists.
-
-**Step 5: Commit**
-
-```bash
-git add extensions/workflow-monitor.ts tests/extension/workflow-monitor/state-persistence.test.ts
-git commit -m "refactor: rename workflow state file"
-```
-
-### Task 5: Update user-facing docs for the new workflow-next contract
-
-**Type:** non-code
-
-**Files:**
-- Modify: `README.md`
-- Modify: `docs/developer-usage-guide.md`
-- Modify: `docs/workflow-phases.md`
-
-**Acceptance criteria:**
-- Criterion 1: `/workflow-next` docs describe immediate-next-only handoff semantics.
-- Criterion 2: docs mention that the command preserves prior completed workflow history for the same feature.
-- Criterion 3: docs do not claim arbitrary phase jumps are supported.
-
-**Implementation notes:**
-- Keep examples aligned with allowed transitions only.
-- Mention the stricter behavior near existing `/workflow-next` examples rather than adding a long new section.
-- If the local state file is mentioned anywhere, rename it to `.pi/workflow-kit-state.json`.
-
-**Verification:**
-- Review each acceptance criterion one-by-one.
-- Confirm wording matches the implemented behavior and test coverage.
-
-### Task 6: Run focused verification and capture final status
-
-**Type:** code
-**TDD scenario:** Trivial change — use judgment
-
-**Files:**
-- Modify: `docs/plans/2026-04-09-workflow-next-handoff-state-implementation.md`
-- Test: `tests/extension/workflow-monitor/workflow-next-command.test.ts`
-- Test: `tests/extension/workflow-monitor/state-persistence.test.ts`
-
-**Step 1: Run focused verification**
-
-Run:
-- `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts`
-- `npx vitest run tests/extension/workflow-monitor/state-persistence.test.ts`
-
-Expected: PASS
-
-**Step 2: Run a broader confidence check**
-
-Run: `npx vitest run tests/extension/workflow-monitor`
-Expected: PASS
-
-**Step 3: Update the implementation plan artifact with verification notes if useful**
-
-Add a short note under the plan or in a small completion section summarizing which test commands passed.
-
-**Step 4: Commit**
-
-```bash
-git add docs/plans/2026-04-09-workflow-next-handoff-state-implementation.md
-git commit -m "test: verify workflow-next handoff changes"
-```

package/extensions/constants.ts

@@ -1,15 +0,0 @@
-/**
- * Shared constants for pi-workflow-kit extensions.
- *
- * PLAN_TRACKER_TOOL_NAME is the stable integration contract between plan-tracker
- * and workflow-monitor: when plan-tracker receives an "init" action,
- * workflow-monitor observes it to advance the workflow phase to "execute".
- * This tool id intentionally remains unchanged across the rebrand.
- */
-export const PLAN_TRACKER_TOOL_NAME = "plan_tracker";
-
-/**
- * Custom entry type written by workflow-monitor's /workflow-reset so that
- * plan-tracker's reconstructState picks up an empty task list.
- */
-export const PLAN_TRACKER_CLEARED_TYPE = "plan_tracker_cleared";

package/extensions/lib/logging.ts

@@ -1,138 +0,0 @@
-/**
- * File-based logger for pi-workflow-kit.
- *
- * Default singleton writes to ~/.pi/logs/workflow-kit.log.
- * Info/warn/error always write. Debug writes when PI_WORKFLOW_KIT_DEBUG=1.
- * The legacy PI_SUPERPOWERS_DEBUG env var is also honored for compatibility.
- * One-deep rotation when file exceeds 5 MB.
- */
-
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-export interface LoggerOptions {
-  verbose?: boolean;
-  maxSizeBytes?: number;
-  rotationCheckInterval?: number;
-}
-
-export interface Logger {
-  info(message: string): void;
-  warn(message: string): void;
-  error(message: string, err?: unknown): void;
-  debug(message: string): void;
-}
-
-const DEFAULT_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
-const DEFAULT_ROTATION_CHECK_INTERVAL = 60 * 60 * 1000; // 1 hour
-export const MAX_MESSAGE_LENGTH = 10 * 1024; // 10 KB
-const TRUNCATED_MARKER = "...(truncated)";
-
-function formatError(err: unknown): string {
-  if (err instanceof Error) {
-    return err.stack ?? `${err.name}: ${err.message}`;
-  }
-  return String(err);
-}
-
-function timestamp(): string {
-  // Strip milliseconds + trailing Z so log lines stay compact and second-precision.
-  return new Date().toISOString().replace(/\.\d{3}Z$/, "");
-}
-
-function truncateMessage(message: string): string {
-  if (message.length <= MAX_MESSAGE_LENGTH) return message;
-  return message.slice(0, MAX_MESSAGE_LENGTH - TRUNCATED_MARKER.length) + TRUNCATED_MARKER;
-}
-
-export function createLogger(logPath: string, options?: LoggerOptions): Logger {
-  const verbose = options?.verbose ?? false;
-  const maxSizeBytes = options?.maxSizeBytes ?? DEFAULT_MAX_SIZE;
-  const rotationCheckInterval = options?.rotationCheckInterval ?? DEFAULT_ROTATION_CHECK_INTERVAL;
-  /** Timestamp (ms) of the last rotation size check. Re-checks after rotationCheckInterval. */
-  let lastRotationCheck = -Infinity;
-  /** Set after the first error is reported to stderr, to avoid spamming. */
-  let stderrFallbackFired = false;
-
-  function ensureDir(): void {
-    const dir = path.dirname(logPath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-  }
-
-  /**
-   * Emit a one-time warning to stderr so the user knows logging is broken.
-   * Only fires once per logger instance to avoid spamming.
-   */
-  function stderrFallback(context: string, err: unknown): void {
-    if (stderrFallbackFired) return;
-    stderrFallbackFired = true;
-    const detail = err instanceof Error ? err.message : String(err);
-    process.stderr.write(
-      `[pi-workflow-kit] Logger ${context} failed: ${detail}. Further log errors will be silenced.\n`,
-    );
-  }
-
-  /**
-   * Rotate the log file if it exceeds maxSizeBytes.
-   * Re-checks at most once per rotationCheckInterval (default 1 hour)
-   * so long-running processes can still rotate without checking on every write.
-   */
-  function rotateIfNeeded(): void {
-    const now = Date.now();
-    if (now - lastRotationCheck < rotationCheckInterval) return;
-    lastRotationCheck = now;
-    try {
-      const stat = fs.statSync(logPath);
-      if (stat.size > maxSizeBytes) {
-        fs.renameSync(logPath, `${logPath}.1`);
-      }
-    } catch (err) {
-      // File doesn't exist yet — nothing to rotate. But surface unexpected errors once.
-      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
-        stderrFallback("rotation", err);
-      }
-    }
-  }
-
-  /**
-   * Append a log line to the file. Uses synchronous I/O for simplicity and ordering guarantees — acceptable for low-volume diagnostic logging.
-   */
-  function write(level: string, message: string): void {
-    try {
-      ensureDir();
-      rotateIfNeeded();
-      const line = `${timestamp()} [${level}] ${truncateMessage(message)}\n`;
-      fs.appendFileSync(logPath, line, "utf-8");
-    } catch (err) {
-      // Logger must never crash the application, but surface the first failure.
-      stderrFallback("write", err);
-    }
-  }
-
-  return {
-    info(message: string): void {
-      write("INFO", message);
-    },
-    warn(message: string): void {
-      write("WARN", message);
-    },
-    error(message: string, err?: unknown): void {
-      const suffix = err ? ` — ${formatError(err)}` : "";
-      write("ERROR", message + suffix);
-    },
-    debug(message: string): void {
-      if (!verbose) return;
-      write("DEBUG", message);
-    },
-  };
-}
-
-/** Default singleton logger used across all extensions. */
-const LOG_PATH = path.join(os.homedir(), ".pi", "logs", "workflow-kit.log");
-
-export const log: Logger = createLogger(LOG_PATH, {
-  verbose: process.env.PI_WORKFLOW_KIT_DEBUG === "1" || process.env.PI_SUPERPOWERS_DEBUG === "1",
-});