@tianhai/pi-workflow-kit 0.4.1

package/extensions/subagent/lifecycle.ts

@@ -0,0 +1,25 @@
+import type { ChildProcess } from "node:child_process";
+
+export class ProcessTracker {
+  private processes = new Set<ChildProcess>();
+
+  get size(): number {
+    return this.processes.size;
+  }
+
+  add(proc: ChildProcess): void {
+    this.processes.add(proc);
+  }
+
+  remove(proc: ChildProcess): void {
+    this.processes.delete(proc);
+  }
+
+  killAll(): void {
+    for (const proc of this.processes) {
+      if (!proc.killed) {
+        proc.kill("SIGTERM");
+      }
+    }
+  }
+}

package/extensions/subagent/timeout.ts

@@ -0,0 +1,13 @@
+export const DEFAULT_SUBAGENT_TIMEOUT_MS = 600_000; // 10 minutes
+
+export function getSubagentTimeoutMs(agentTimeout?: number): number {
+  if (agentTimeout !== undefined && agentTimeout > 0) return agentTimeout;
+
+  const envVal = process.env.PI_SUBAGENT_TIMEOUT_MS;
+  if (envVal) {
+    const parsed = Number.parseInt(envVal, 10);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+
+  return DEFAULT_SUBAGENT_TIMEOUT_MS;
+}

package/extensions/workflow-monitor/debug-monitor.ts

@@ -0,0 +1,98 @@
+import { isSourceFile } from "./heuristics";
+
+const EXCESSIVE_FIX_THRESHOLD = 3;
+
+export type DebugViolationType = "fix-without-investigation" | "excessive-fix-attempts";
+
+export interface DebugViolation {
+  type: DebugViolationType;
+  file: string;
+  fixAttempts: number;
+}
+
+export class DebugMonitor {
+  private active = false;
+  private investigated = false;
+  private fixAttempts_ = 0;
+  private sourceWrittenSinceLastTest = false;
+
+  getState(): { active: boolean; investigated: boolean; fixAttempts: number } {
+    return {
+      active: this.active,
+      investigated: this.investigated,
+      fixAttempts: this.fixAttempts_,
+    };
+  }
+
+  setState(state: { active: boolean; investigated: boolean; fixAttempts: number }): void {
+    this.active = state.active;
+    this.investigated = state.investigated;
+    this.fixAttempts_ = state.fixAttempts;
+    this.sourceWrittenSinceLastTest = false;
+  }
+
+  isActive(): boolean {
+    return this.active;
+  }
+
+  hasInvestigated(): boolean {
+    return this.investigated;
+  }
+
+  getFixAttempts(): number {
+    return this.fixAttempts_;
+  }
+
+  onTestFailed(): void {
+    if (this.active && this.sourceWrittenSinceLastTest) {
+      this.fixAttempts_++;
+    }
+    this.active = true;
+    this.investigated = false;
+    this.sourceWrittenSinceLastTest = false;
+  }
+
+  onTestPassed(): void {
+    this.reset();
+  }
+
+  onInvestigation(): void {
+    this.investigated = true;
+  }
+
+  onSourceWritten(path: string): DebugViolation | null {
+    if (!this.active) return null;
+    if (!isSourceFile(path)) return null;
+
+    this.sourceWrittenSinceLastTest = true;
+
+    if (this.fixAttempts_ >= EXCESSIVE_FIX_THRESHOLD) {
+      return {
+        type: "excessive-fix-attempts",
+        file: path,
+        fixAttempts: this.fixAttempts_,
+      };
+    }
+
+    if (!this.investigated) {
+      return {
+        type: "fix-without-investigation",
+        file: path,
+        fixAttempts: this.fixAttempts_,
+      };
+    }
+
+    return null;
+  }
+
+  onCommit(): void {
+    this.reset();
+  }
+
+  private reset(): void {
+    this.active = false;
+    this.investigated = false;
+    this.fixAttempts_ = 0;
+    this.sourceWrittenSinceLastTest = false;
+  }
+}

package/extensions/workflow-monitor/git.ts

@@ -0,0 +1,31 @@
+import { execSync } from "node:child_process";
+import { log } from "../lib/logging.js";
+
+/**
+ * Returns the current git branch name, or (if detached) the short HEAD SHA.
+ * Returns null if the current working directory is not in a git repo.
+ */
+export function getCurrentGitRef(cwd: string = process.cwd()): string | null {
+  try {
+    const branch = execSync("git branch --show-current", {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+
+    if (branch) return branch;
+
+    const sha = execSync("git rev-parse --short HEAD", {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+
+    return sha || null;
+  } catch (err) {
+    log.warn(`Failed to determine git ref in ${cwd}: ${err instanceof Error ? err.message : err}`);
+    return null;
+  }
+}

package/extensions/workflow-monitor/heuristics.ts

@@ -0,0 +1,58 @@
+import path from "node:path";
+
+const TEST_PATTERNS = [
+  /\.(test|spec)\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)$/,
+  /(^|\/)tests?\//,
+  /\/__tests__\//,
+  /^test_\w+\.py$/,
+  /\/test_\w+\.py$/,
+  /\w+_test\.py$/,
+  /\w+_test\.go$/,
+];
+
+const SOURCE_EXTENSIONS = /\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)$/;
+
+const CONFIG_PATTERNS = [
+  /\.config\.(ts|js|mjs|cjs)$/,
+  /^\./, // dotfiles
+  /package\.json$/,
+  /tsconfig.*\.json$/,
+];
+
+export function isTestFile(path: string): boolean {
+  return TEST_PATTERNS.some((p) => p.test(path));
+}
+
+export function isSourceFile(path: string): boolean {
+  if (!SOURCE_EXTENSIONS.test(path)) return false;
+  if (isTestFile(path)) return false;
+  if (CONFIG_PATTERNS.some((p) => p.test(path))) return false;
+  return true;
+}
+
+export function findCorrespondingTestFile(filePath: string): string[] {
+  const parsed = path.posix.parse(filePath);
+  const baseDir = parsed.dir;
+  const stem = parsed.name;
+  const ext = parsed.ext;
+
+  if (!stem || !ext) return [];
+
+  const candidates = [
+    path.posix.join(baseDir, `${stem}.test${ext}`),
+    path.posix.join(baseDir, `${stem}.spec${ext}`),
+    path.posix.join(baseDir, "__tests__", `${stem}.test${ext}`),
+    path.posix.join(baseDir, "__tests__", `${stem}.spec${ext}`),
+  ];
+
+  if (filePath.startsWith("src/")) {
+    const relFromSrc = filePath.slice("src/".length);
+    const relParsed = path.posix.parse(relFromSrc);
+    candidates.push(
+      path.posix.join("tests", relParsed.dir, `${relParsed.name}.test${relParsed.ext}`),
+      path.posix.join("tests", relParsed.dir, `${relParsed.name}.spec${relParsed.ext}`),
+    );
+  }
+
+  return candidates;
+}

package/extensions/workflow-monitor/investigation.ts

@@ -0,0 +1,52 @@
+const INVESTIGATION_PATTERNS = [
+  /\bgrep\b/,
+  /\brg\b/,
+  /\bag\b/,
+  /\bgit\s+(log|diff|show|blame)\b/,
+  /\bfind\b/,
+  /\bls\b/,
+  /\bcat\b/,
+  /\bhead\b/,
+  /\btail\b/,
+  /\bless\b/,
+  /\bwc\b/,
+  /\becho\b/,
+  /\bprintf\b/,
+  /\benv\b/,
+  /\bprintenv\b/,
+];
+
+export function isInvestigationCommand(command: string): boolean {
+  return INVESTIGATION_PATTERNS.some((p) => p.test(command));
+}
+
+const INVESTIGATION_TOOL_NAMES = new Set([
+  "kota_search",
+  "kota_deps",
+  "kota_usages",
+  "kota_impact",
+  "kota_task_context",
+  "web_search",
+  "fetch_content",
+]);
+
+const INVESTIGATION_LSP_ACTIONS = new Set([
+  "definition",
+  "references",
+  "hover",
+  "symbols",
+  "diagnostics",
+  "workspace-diagnostics",
+]);
+
+export function isInvestigationToolCall(toolName: string, params?: Record<string, unknown>): boolean {
+  if (INVESTIGATION_TOOL_NAMES.has(toolName)) {
+    return true;
+  }
+
+  if (toolName === "lsp" && params?.action && INVESTIGATION_LSP_ACTIONS.has(params.action as string)) {
+    return true;
+  }
+
+  return false;
+}

package/extensions/workflow-monitor/reference-tool.ts

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { log } from "../lib/logging.js";
+
+// extensions/workflow-monitor/reference-tool.ts is 2 levels below package root
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+
+const TOPIC_MAP: Record<string, string> = {
+  "tdd-rationalizations": "skills/test-driven-development/reference/rationalizations.md",
+  "tdd-examples": "skills/test-driven-development/reference/examples.md",
+  "tdd-when-stuck": "skills/test-driven-development/reference/when-stuck.md",
+  "tdd-anti-patterns": "skills/test-driven-development/testing-anti-patterns.md",
+  "debug-rationalizations": "skills/systematic-debugging/reference/rationalizations.md",
+  "debug-tracing": "skills/systematic-debugging/root-cause-tracing.md",
+  "debug-defense-in-depth": "skills/systematic-debugging/defense-in-depth.md",
+  "debug-condition-waiting": "skills/systematic-debugging/condition-based-waiting.md",
+  "brainstorming-guide": "skills/brainstorming/SKILL.md",
+  "writing-plans-guide": "skills/writing-plans/SKILL.md",
+  "executing-tasks-guide": "skills/executing-tasks/SKILL.md",
+  "dispatching-agents-guide": "skills/dispatching-parallel-agents/SKILL.md",
+  "receiving-review-guide": "skills/receiving-code-review/SKILL.md",
+  "worktree-guide": "skills/using-git-worktrees/SKILL.md",
+};
+
+export const REFERENCE_TOPICS = Object.keys(TOPIC_MAP);
+
+export async function loadReference(topic: string): Promise<string> {
+  const relativePath = TOPIC_MAP[topic];
+  if (!relativePath) {
+    return `Unknown topic: "${topic}". Available topics: ${REFERENCE_TOPICS.join(", ")}`;
+  }
+
+  const fullPath = resolve(PACKAGE_ROOT, relativePath);
+
+  try {
+    return await readFile(fullPath, "utf-8");
+  } catch (err) {
+    log.warn(`Failed to load reference "${topic}" from ${fullPath}: ${err instanceof Error ? err.message : err}`);
+    return `Error loading reference "${topic}": file not found at ${fullPath}`;
+  }
+}

package/extensions/workflow-monitor/skip-confirmation.ts

@@ -0,0 +1,19 @@
+import { type Phase, type PhaseStatus, WORKFLOW_PHASES, type WorkflowTrackerState } from "./workflow-tracker";
+
+export function isPhaseUnresolved(status: PhaseStatus): boolean {
+  return status === "pending";
+}
+
+export function getUnresolvedPhasesBefore(target: Phase, state: WorkflowTrackerState): Phase[] {
+  const targetIndex = WORKFLOW_PHASES.indexOf(target);
+  if (targetIndex === -1) {
+    return [];
+  }
+
+  const phasesBefore = WORKFLOW_PHASES.slice(0, targetIndex);
+  return getUnresolvedPhases(phasesBefore, state);
+}
+
+export function getUnresolvedPhases(phases: Phase[], state: WorkflowTrackerState): Phase[] {
+  return phases.filter((phase) => isPhaseUnresolved(state.phases[phase]));
+}

package/extensions/workflow-monitor/tdd-monitor.ts

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import { findCorrespondingTestFile, isSourceFile, isTestFile } from "./heuristics";
+
+export type TddPhase = "idle" | "red-pending" | "red" | "green" | "refactor";
+
+export type TddViolationType = "source-before-test" | "source-during-red" | "existing-tests-not-run-before-change";
+
+export interface TddViolation {
+  type: TddViolationType;
+  file: string;
+}
+
+export class TddMonitor {
+  private phase: TddPhase = "idle";
+  private testFilesWritten = new Set<string>();
+  private sourceFilesWritten = new Set<string>();
+  private redVerificationPending = false;
+  private nonCodeMode = false;
+  private testsRunBeforeLastWrite = false;
+  private fileExists: (path: string) => boolean;
+
+  constructor(fileExists?: (path: string) => boolean) {
+    this.fileExists = fileExists ?? ((filePath) => fs.existsSync(filePath));
+  }
+
+  getPhase(): TddPhase {
+    return this.phase;
+  }
+
+  isRedVerificationPending(): boolean {
+    return this.phase === "red-pending" && this.redVerificationPending;
+  }
+
+  setNonCodeMode(value: boolean): void {
+    this.nonCodeMode = value;
+  }
+
+  onFileWritten(path: string): TddViolation | null {
+    if (this.nonCodeMode) return null;
+
+    if (isTestFile(path)) {
+      this.testFilesWritten.add(path);
+      this.phase = "red-pending";
+      this.redVerificationPending = true;
+      return null;
+    }
+
+    if (isSourceFile(path)) {
+      this.sourceFilesWritten.add(path);
+
+      const wasTestsRun = this.testsRunBeforeLastWrite;
+      this.testsRunBeforeLastWrite = false;
+
+      if (this.testFilesWritten.size === 0) {
+        const existingTestFile = findCorrespondingTestFile(path).some((candidatePath) =>
+          this.fileExists(candidatePath),
+        );
+        if (!existingTestFile) {
+          return { type: "source-before-test", file: path };
+        }
+        // Existing test coverage detected — Scenario 2 check
+        if (!wasTestsRun) {
+          return { type: "existing-tests-not-run-before-change", file: path };
+        }
+        return null;
+      }
+
+      if (this.phase === "red-pending") {
+        return { type: "source-during-red", file: path };
+      }
+
+      if (this.phase === "green") {
+        this.phase = "refactor";
+      }
+      return null;
+    }
+
+    return null;
+  }
+
+  onTestResult(passed: boolean): void {
+    this.testsRunBeforeLastWrite = true;
+
+    if (this.phase === "red-pending") {
+      this.redVerificationPending = false;
+      if (passed) {
+        this.phase = "green";
+      } else {
+        this.phase = "red";
+      }
+      return;
+    }
+
+    if (passed && (this.phase === "red" || this.phase === "refactor")) {
+      this.phase = "green";
+    }
+  }
+
+  onCommit(): void {
+    this.phase = "idle";
+    this.redVerificationPending = false;
+    this.testFilesWritten.clear();
+    this.sourceFilesWritten.clear();
+    this.testsRunBeforeLastWrite = false;
+  }
+
+  setState(
+    phase: TddPhase,
+    testFiles: string[],
+    sourceFiles: string[],
+    redVerificationPending = false,
+    nonCodeMode = false,
+  ): void {
+    this.phase = phase;
+    this.testFilesWritten = new Set(testFiles);
+    this.sourceFilesWritten = new Set(sourceFiles);
+    this.redVerificationPending = redVerificationPending;
+    this.nonCodeMode = nonCodeMode;
+    this.testsRunBeforeLastWrite = false;
+  }
+
+  getState(): {
+    phase: TddPhase;
+    testFiles: string[];
+    sourceFiles: string[];
+    redVerificationPending: boolean;
+    nonCodeMode: boolean;
+  } {
+    return {
+      phase: this.phase,
+      testFiles: [...this.testFilesWritten],
+      sourceFiles: [...this.sourceFilesWritten],
+      redVerificationPending: this.redVerificationPending,
+      nonCodeMode: this.nonCodeMode,
+    };
+  }
+}

package/extensions/workflow-monitor/test-runner.ts

@@ -0,0 +1,37 @@
+const TEST_COMMANDS = [
+  /\bnpm\s+test\b/,
+  /\bnpx\s+(vitest|jest)\b/,
+  /\bpytest\b/,
+  /\bgo\s+test\b/,
+  /\bcargo\s+test\b/,
+  /\bjest\b/,
+  /\bvitest\b/,
+  /\bmocha\b/,
+  /\brspec\b/,
+  /\bphpunit\b/,
+  /\bdotnet\s+test\b/,
+];
+
+const PASS_PATTERNS = [
+  /\d+\s+(tests?\s+)?passed/i,
+  /^ok\s+/m,
+  /Tests:\s+\d+ passed/,
+  /\d+ passing/,
+  /BUILD SUCCESSFUL/,
+];
+
+const FAIL_PATTERNS = [/\bfailed\b/i, /^FAIL\b/m, /\d+ failing/, /BUILD FAILED/, /ERRORS!/];
+
+export function parseTestCommand(command: string): boolean {
+  return TEST_COMMANDS.some((p) => p.test(command));
+}
+
+export function parseTestResult(output: string, exitCode: number | undefined): boolean | null {
+  const hasFail = FAIL_PATTERNS.some((p) => p.test(output));
+  const hasPass = PASS_PATTERNS.some((p) => p.test(output));
+
+  if (hasFail && !hasPass) return false;
+  if (hasPass && !hasFail) return true;
+  if (exitCode !== undefined) return exitCode === 0;
+  return null;
+}

package/extensions/workflow-monitor/verification-monitor.ts

@@ -0,0 +1,61 @@
+export interface VerificationViolation {
+  type: "commit-without-verification" | "push-without-verification" | "pr-without-verification";
+  command: string;
+}
+
+const COMMIT_RE = /\bgit\s+commit\b/;
+const PUSH_RE = /\bgit\s+push\b/;
+const PR_RE = /\bgh\s+pr\s+create\b/;
+
+export class VerificationMonitor {
+  private verified = false;
+  private verificationWaived = false;
+
+  getState(): { verified: boolean; verificationWaived: boolean } {
+    return {
+      verified: this.verified,
+      verificationWaived: this.verificationWaived,
+    };
+  }
+
+  setState(state: { verified: boolean; verificationWaived: boolean }): void {
+    this.verified = state.verified;
+    this.verificationWaived = state.verificationWaived;
+  }
+
+  recordVerification(): void {
+    this.verified = true;
+  }
+
+  recordVerificationWaiver(): void {
+    this.verificationWaived = true;
+  }
+
+  onSourceWritten(): void {
+    this.verified = false;
+    this.verificationWaived = false;
+  }
+
+  hasRecentVerification(): boolean {
+    return this.verified;
+  }
+
+  checkCommitGate(command: string): VerificationViolation | null {
+    const allowed = this.verified || this.verificationWaived;
+    if (COMMIT_RE.test(command)) {
+      return allowed ? null : { type: "commit-without-verification", command };
+    }
+    if (PUSH_RE.test(command)) {
+      return allowed ? null : { type: "push-without-verification", command };
+    }
+    if (PR_RE.test(command)) {
+      return allowed ? null : { type: "pr-without-verification", command };
+    }
+    return null;
+  }
+
+  reset(): void {
+    this.verified = false;
+    this.verificationWaived = false;
+  }
+}

package/extensions/workflow-monitor/warnings.ts

@@ -0,0 +1,81 @@
+export type TddViolationType = "source-before-test" | "source-during-red" | "existing-tests-not-run-before-change";
+
+export function getTddViolationWarning(type: TddViolationType, file: string, _phase?: string): string {
+  if (type === "source-before-test") {
+    return `⚠️ TDD: Writing source code (${file}) without a failing test. Consider whether this change needs a test first, or if existing tests already cover it.`;
+  }
+
+  if (type === "source-during-red") {
+    return `⚠️ TDD: Writing source code (${file}) before running your new test. Run the test suite to verify your test fails, then implement.`;
+  }
+
+  if (type === "existing-tests-not-run-before-change") {
+    return `⚠️ TDD SCENARIO 2: You modified ${file} without running existing tests first.\nRun the tests, observe their current state, THEN make your change.`;
+  }
+
+  return `⚠️ TDD: Unexpected violation type "${type}" for ${file}`;
+}
+
+export type DebugViolationType = "fix-without-investigation" | "excessive-fix-attempts";
+
+export type VerificationViolationType =
+  | "commit-without-verification"
+  | "push-without-verification"
+  | "pr-without-verification";
+
+export function getDebugViolationWarning(type: DebugViolationType, file: string, fixAttempts: number): string {
+  if (type === "fix-without-investigation") {
+    return `
+⚠️ DEBUG VIOLATION: You edited production code (${file}) without investigating first.
+
+The Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
+
+Before editing code, you must:
+1. Read the error messages and stack traces carefully
+2. Read the relevant source files to understand the code
+3. Trace the data flow to find where the bad value originates
+
+You're treating symptoms, not causes. Symptom fixes create new bugs.
+
+Stop. Read. Understand. Then fix.
+`.trim();
+  }
+
+  if (type === "excessive-fix-attempts") {
+    return `
+⚠️ DEBUG WARNING: ${fixAttempts} failed fix attempts on ${file}.
+
+${fixAttempts} fix attempts haven't resolved the issue. Consider stepping back to investigate root cause.
+
+Pattern indicating architectural problem:
+- Each fix reveals new problems in different places
+- Fixes require "massive refactoring" to implement
+- Each fix creates new symptoms elsewhere
+
+STOP and question fundamentals:
+- Is this pattern fundamentally sound?
+- Are we sticking with it through sheer inertia?
+- Should we refactor architecture vs. continue fixing symptoms?
+
+Discuss with your human partner before attempting more fixes.
+`.trim();
+  }
+
+  return `⚠️ DEBUG WARNING: Unexpected violation type "${type}" for ${file}`;
+}
+
+export function getVerificationViolationWarning(type: VerificationViolationType, command: string): string {
+  const action =
+    type === "commit-without-verification" ? "commit" : type === "push-without-verification" ? "push" : "create a PR";
+
+  return `
+⚠️ VERIFICATION REQUIRED: You're about to ${action} without running verification.
+
+Command: ${command}
+
+Run the test/build/lint command FIRST. Read the output. Confirm it passes.
+THEN ${action}.
+
+Evidence before claims. No shortcuts.
+`.trim();
+}