pi-taskflow 0.0.6 → 0.0.8

package/extensions/schema.ts

@@ -5,6 +5,7 @@
  * to a subagent (an isolated `pi` process). Phases form a DAG via `dependsOn`.
  */
 
+import * as path from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 
@@ -102,6 +103,18 @@ const PhaseSchema = Type.Object(
 			Type.Boolean({ description: "If true, a failure does not abort the run", default: false }),
 		),
 		concurrency: Type.Optional(Type.Number({ description: "Override max concurrency for map/parallel" })),
+		context: Type.Optional(
+			Type.Array(Type.String(), {
+				description:
+					"File paths or {steps.X} refs to pre-read and inject before the task. Resolves interpolated refs first, then reads each file (capped per-file). Eliminates O(N²) turn-cost exploration.",
+			}),
+		),
+		contextLimit: Type.Optional(
+			Type.Number({
+				description: "Max characters to read per file referenced in context (default 8000).",
+				default: 8000,
+			}),
+		),
 	},
 	{ additionalProperties: false },
 );
@@ -126,7 +139,20 @@ export const TaskflowSchema = Type.Object(
 		agentScope: Type.Optional(
 			StringEnum(["user", "project", "both"] as const, { description: "Agent discovery scope", default: "user" }),
 		),
+		strictInterpolation: Type.Optional(
+			Type.Boolean({
+				description:
+					"When true, unresolved interpolation placeholders and validation warnings about missing deps/args become hard errors",
+				default: false,
+			}),
+		),
 		phases: Type.Array(PhaseSchema, { minItems: 1, description: "Ordered phase definitions (DAG via dependsOn)" }),
+		implicitGate: Type.Optional(
+			Type.Boolean({
+				description: "When true (default), a reviewer gate is auto-injected after all phases if no explicit gate or approval exists",
+				default: true,
+			}),
+		),
 	},
 	{ additionalProperties: false },
 );
@@ -164,7 +190,11 @@ export function isShorthand(def: unknown): boolean {
 	if (typeof def !== "object" || def === null) return false;
 	const d = def as Record<string, unknown>;
 	if (Array.isArray(d.phases)) return false;
-	return Array.isArray(d.chain) || Array.isArray(d.tasks) || typeof d.task === "string";
+	return (
+		(Array.isArray(d.chain) && d.chain.length > 0) ||
+		(Array.isArray(d.tasks) && d.tasks.length > 0) ||
+		typeof d.task === "string"
+	);
 }
 
 function readStep(s: unknown): ShorthandStep {
@@ -190,6 +220,8 @@ export function desugar(def: unknown): Taskflow {
 	if (typeof d.concurrency === "number") meta.concurrency = d.concurrency;
 	if (d.agentScope === "user" || d.agentScope === "project" || d.agentScope === "both") meta.agentScope = d.agentScope;
 	if (d.args && typeof d.args === "object") meta.args = d.args as Taskflow["args"];
+	if (d.budget) meta.budget = d.budget;
+	if (typeof d.strictInterpolation === "boolean") meta.strictInterpolation = d.strictInterpolation;
 	const nameOf = (fallback: string) => (typeof d.name === "string" && d.name.trim() ? d.name.trim() : fallback);
 
 	// chain → sequential agent phases
@@ -228,20 +260,35 @@ export function desugar(def: unknown): Taskflow {
 export interface ValidationResult {
 	ok: boolean;
 	errors: string[];
+	/** Non-fatal issues the user should fix; e.g. `{steps.X}` references that
+	 *  aren't declared in `dependsOn` (the phase will run in parallel with its
+	 *  producer and see the literal placeholder). */
+	warnings: string[];
+}
+
+export interface ValidationOptions {
+	/** Resolved invocation args, used for runtime checks like missing `{args.X}`. */
+	args?: Record<string, unknown>;
+	/** Runtime working directory, used for mismatch warnings (e.g. cwd vs args.codebase). */
+	cwd?: string;
+	/** Override the flow's own `strictInterpolation` flag for this validation call. */
+	strict?: boolean;
 }
 
-export function validateTaskflow(def: unknown): ValidationResult {
+export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): ValidationResult {
 	const errors: string[] = [];
+	const warnings: string[] = [];
 
 	if (typeof def !== "object" || def === null) {
-		return { ok: false, errors: ["Taskflow must be an object"] };
+		return { ok: false, errors: ["Taskflow must be an object"], warnings };
 	}
 	const flow = def as Partial<Taskflow>;
+	const strict = opts.strict ?? flow.strictInterpolation === true;
 
 	if (!flow.name || typeof flow.name !== "string") errors.push("Missing or invalid 'name'");
 	if (!Array.isArray(flow.phases) || flow.phases.length === 0) {
 		errors.push("Taskflow must have at least one phase");
-		return { ok: false, errors };
+		return { ok: false, errors, warnings };
 	}
 
 	const ids = new Set<string>();
@@ -318,7 +365,106 @@ export function validateTaskflow(def: unknown): ValidationResult {
 	const finals = (flow.phases as Phase[]).filter((p) => p?.final);
 	if (finals.length > 1) errors.push(`Only one phase may be marked 'final' (found ${finals.length})`);
 
-	return { ok: errors.length === 0, errors };
+	// --- Hard errors: {steps.X.*} references that aren't declared deps ------
+	// Catches the most common authoring mistake: the task talks about
+	// `{steps.review.output}` but `dependsOn: ["review"]` is missing, so the
+	// phase runs in parallel with `review` and the model sees the literal
+	// placeholder string. The runtime can't infer the intent — fail fast at
+	// validation time so the mistake is caught before the run starts.
+	//
+	// Phases with `join: "any"` are exempt: by design they only need ONE of
+	// their declared deps to complete, and may reference other phases as
+	// informational context (not as true dependencies).
+	if (errors.length === 0) {
+		const idToPhase = new Map((flow.phases as Phase[]).map((p) => [p.id, p]));
+		for (const p of flow.phases as Phase[]) {
+			if (!p?.id) continue;
+			const isJoinAny = p.join === "any";
+			if (isJoinAny) continue;
+			const deps = new Set(dependenciesOf(p));
+			const refs = collectRefs(p);
+			for (const ref of refs.steps) {
+				if (ref === p.id) {
+					errors.push(`Phase '${p.id}': references its own output via {steps.${ref}.*}; this is almost always a bug.`);
+					continue;
+				}
+				if (!idToPhase.has(ref)) {
+					// Unknown ref is already an error from the dependsOn check, but
+					// {steps.X.*} can appear in a task without dependsOn. Don't
+					// double-warn — the dependsOn loop above already flags it.
+					continue;
+				}
+				if (!deps.has(ref)) {
+					errors.push(
+						`Phase '${p.id}': task references {steps.${ref}.*} but '${ref}' is not in dependsOn. ` +
+							`The phase will run in parallel with '${ref}' and see the literal placeholder. ` +
+							`Add "dependsOn": ["${ref}"] (or include '${ref}' transitively).`,
+					);
+				}
+			}
+		}
+	}
+
+	// --- Runtime/invocation warnings: missing args + cwd/codebase mismatch -----
+	if (errors.length === 0 && opts.args) {
+		const argRefs = new Set<string>();
+		for (const p of flow.phases as Phase[]) {
+			if (!p?.id) continue;
+			for (const ref of collectRefs(p).args) argRefs.add(ref);
+		}
+		for (const ref of argRefs) {
+			if (!(ref in opts.args)) {
+				warnings.push(
+					`Taskflow references {args.${ref}} but the invocation did not provide '${ref}'. ` +
+						`The placeholder will remain literal unless a default or runtime arg is supplied.`,
+				);
+			}
+		}
+		if (opts.cwd && typeof opts.args.codebase === "string" && opts.args.codebase.trim()) {
+			const cwd = path.resolve(opts.cwd);
+			const codebase = path.resolve(cwd, opts.args.codebase);
+			// Safe case: cwd is the codebase root or a subdirectory within it.
+			// Warn when cwd is a sibling, unrelated path, or a parent of the
+			// codebase (agents that rely on cwd would inspect too broad a tree).
+			if (!pathContains(codebase, cwd)) {
+				warnings.push(
+					`Invocation cwd '${cwd}' does not match args.codebase '${codebase}'. ` +
+						`Some agents may inspect the wrong repo if they rely on cwd. Prefer running from the codebase root or set phase.cwd explicitly.`,
+				);
+			}
+		}
+	}
+
+	if (strict && warnings.length) {
+		errors.push(...warnings.map((w) => `Strict interpolation: ${w}`));
+	}
+
+	return { ok: errors.length === 0, errors, warnings };
+}
+
+function collectRefs(phase: Phase): { steps: string[]; args: string[] } {
+	const steps = new Set<string>();
+	const args = new Set<string>();
+	const scan = (s: string | undefined) => {
+		if (!s) return;
+		let m: RegExpExecArray | null;
+		const stepRe = /\{steps\.([a-zA-Z0-9_-]+)/g;
+		while ((m = stepRe.exec(s)) !== null) steps.add(m[1]);
+		const argRe = /\{args\.([a-zA-Z0-9_-]+)/g;
+		while ((m = argRe.exec(s)) !== null) args.add(m[1]);
+	};
+	scan(phase.task);
+	scan(phase.over);
+	scan(phase.when);
+	for (const b of phase.branches ?? []) scan(b.task);
+	for (const v of Object.values(phase.with ?? {})) if (typeof v === "string") scan(v);
+	for (const c of phase.context ?? []) scan(c);
+	return { steps: Array.from(steps), args: Array.from(args) };
+}
+
+function pathContains(parent: string, child: string): boolean {
+	const rel = path.relative(parent, child);
+	return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
 
 /** Returns a cycle path if the DAG has one, else null. */

package/extensions/store.ts

@@ -8,6 +8,7 @@
 
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { Taskflow } from "./schema.ts";
@@ -45,6 +46,12 @@ export interface PhaseState {
 	budgetTruncated?: boolean;
 	/** Human-in-the-loop outcome (approval phases only). */
 	approval?: { decision: "approve" | "reject" | "edit"; note?: string; auto?: boolean };
+	/** Non-fatal diagnostic warnings accumulated during this phase (e.g.
+	 *  unresolved interpolation placeholders, suspicious templates). */
+	warnings?: string[];
+	/** Truncated previews of interpolated strings used to execute this phase,
+	 *  useful when diagnosing why a model saw a literal placeholder. */
+	interpolation?: Array<{ source: string; text: string; missing?: string[] }>;
 }
 
 export interface RunState {
@@ -63,12 +70,20 @@ function userFlowsDir(): string {
 	return path.join(getAgentDir(), "taskflows");
 }
 
-function findProjectFlowsDir(cwd: string, create = false): string | null {
+function findProjectFlowsDirInternal(cwd: string, create = false): string | null {
 	// Prefer an existing .pi dir up the tree; else use cwd/.pi when creating.
+	// **Never treat `~/.pi/` as a project flow dir** — the home directory is
+	// the user-scope boundary, and the user's `~/.pi/` is the agent dir, not a
+	// project. We skip the home entry entirely during the walk-up, so even a
+	// deeply nested cwd under home will return null (create=false) when no
+	// project `.pi` exists on the path.
+	const home = os.homedir();
 	let dir = cwd;
 	while (true) {
-		const candidate = path.join(dir, ".pi");
-		if (fs.existsSync(candidate)) return path.join(candidate, "taskflows");
+		if (dir !== home) {
+			const candidate = path.join(dir, ".pi");
+			if (fs.existsSync(candidate)) return path.join(candidate, "taskflows");
+		}
 		const parent = path.dirname(dir);
 		if (parent === dir) break;
 		dir = parent;
@@ -88,6 +103,11 @@ function readFlowFile(filePath: string, scope: "user" | "project"): SavedFlow |
 }
 
 /** List all saved flows (project overrides user on name collision). */
+/** Internal-but-exported for tests: walk-up `.pi` finder with home-dir stop. */
+export function findProjectFlowsDir(cwd: string, create = false): string | null {
+	return findProjectFlowsDirInternal(cwd, create);
+}
+
 export function listFlows(cwd: string): SavedFlow[] {
 	const map = new Map<string, SavedFlow>();
 	const dirs: Array<{ dir: string; scope: "user" | "project" }> = [{ dir: userFlowsDir(), scope: "user" }];
@@ -143,13 +163,56 @@ export function newRunId(flowName: string): string {
 export function saveRun(state: RunState): void {
 	const dir = runsDir(state.cwd);
 	fs.mkdirSync(dir, { recursive: true });
-	state.updatedAt = Date.now();
-	writeFileAtomic(path.join(dir, `${state.runId}.json`), JSON.stringify(state, null, 2));
+	// Clone before stamping updatedAt so the caller's RunState reference is not
+	// mutated as a hidden side effect (v0.0.6 audit, F-009). Shallow clone is
+	// sufficient: saveRun only serializes; it does not mutate nested objects.
+	const toSave = { ...state, updatedAt: Date.now() };
+	writeFileAtomic(path.join(dir, `${state.runId}.json`), JSON.stringify(toSave, null, 2));
 }
 
 export function loadRun(cwd: string, runId: string): RunState | null {
+	const dir = runsDir(cwd);
+
+	// Reject runIds that could be used for path traversal or filesystem abuse.
+	// Legitimate runIds are produced by newRunId() and contain only
+	// [A-Za-z0-9._-]; anything else (empty string, path separators, NUL bytes,
+	// backslashes on POSIX, forward slashes on Windows) is suspicious.
+	if (
+		typeof runId !== "string" ||
+		runId.length === 0 ||
+		runId.includes("/") ||
+		runId.includes("\\") ||
+		runId.includes("\0")
+	) {
+		return null;
+	}
+
+	const filePath = path.resolve(dir, `${runId}.json`);
+	// Reject runIds that would escape the runs directory (e.g. "../etc/passwd").
+	// Compare with a path-separator suffix so legitimate filenames like "..foo"
+	// (a name that just happens to start with two dots) are not false-positives.
+	const rel = path.relative(dir, filePath);
+	if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return null;
+
+	// Resolve symlinks on both the runs dir and the file, so the containment
+	// check below is on a consistent physical path. Without normalizing `dir`,
+	// a legitimate run on macOS (where /var → /private/var) would compare a
+	// symlinked dir prefix to a real path and falsely flag traversal. A
+	// malicious file already placed inside the runs dir could otherwise also
+	// point at an arbitrary path on disk and bypass the lexical check above.
+	let realDir: string;
+	let realFilePath: string;
+	try {
+		realDir = fs.realpathSync(dir);
+		realFilePath = fs.realpathSync(filePath);
+	} catch {
+		return null;
+	}
+	const realRel = path.relative(realDir, realFilePath);
+	if (realRel === ".." || realRel.startsWith(`..${path.sep}`) || path.isAbsolute(realRel)) return null;
+
 	try {
-		const raw = fs.readFileSync(path.join(runsDir(cwd), `${runId}.json`), "utf-8");
+		const raw = fs.readFileSync(realFilePath, "utf-8");
 		return JSON.parse(raw) as RunState;
 	} catch {
 		return null;
@@ -173,7 +236,14 @@ export function listRuns(cwd: string, limit = 20): RunState[] {
 			/* ignore */
 		}
 	}
-	return runs.sort((a, b) => b.updatedAt - a.updatedAt).slice(0, limit);
+	// Guard against records missing/with non-numeric `updatedAt` — a bare
+	// `JSON.parse` may yield an object without it, and `undefined - undefined`
+	// is NaN, which makes `Array.prototype.sort` produce implementation-defined
+	// order. Drop those before sorting. (v0.0.8 audit, F-010.)
+	return runs
+		.filter((r) => typeof r.updatedAt === "number" && !Number.isNaN(r.updatedAt))
+		.sort((a, b) => b.updatedAt - a.updatedAt)
+		.slice(0, limit);
 }
 
 /** Stable hash of a phase's resolved task + inputs, for resume caching. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Lightweight workflow orchestration for the Pi coding agent — declarative multi-phase taskflows with dynamic fan-out, isolated subagent context, resumable runs, and saveable commands.",
   "keywords": [
     "pi-package",

package/skills/taskflow/SKILL.md

@@ -172,6 +172,36 @@ Review the audit results below. If any endpoint is missing auth, end with
 {steps.audit.output}
 ```
 
+### Structured-verify phases (v0.0.8.1)
+
+A "verify" phase typically runs `npx tsc --noEmit && npm test && git diff --stat`
+and reports whether everything is green. **Don't** delegate this to a generic
+verifier subagent that summarizes the output in prose — LLMs commonly misread
+shell output (e.g., 234 tests reported as 230, 745 insertions as 599, "1 type
+error" reported as "clean"). Instead, **use a dedicated agent whose task is a
+structured shell pipeline** that echoes structured key/value lines the next
+phase can parse directly. Recommended pattern:
+
+```jsonc
+{
+  "id": "verify",
+  "type": "agent",
+  "agent": "verifier",
+  "dependsOn": ["apply-fixes"],
+  "task": "Run the verification pipeline and report structured results.\n\nExecute:\n```bash\ncd $REPO && npx tsc --noEmit 2>&1 | tee /tmp/tsc.log\ncd $REPO && npm test 2>&1 | tee /tmp/test.log | tail -10\ncd $REPO && git diff --shortstat HEAD | tee /tmp/diff.log\n```\n\nReport EXACTLY in this format (one key=value pair per line, no prose):\ntypecheck=PASS|FAIL\ntests_total=N\ntests_pass=N\ntests_fail=N\ninsertions=N\ndeletions=N\nfiles_changed=N\n\nIf any field is missing, you failed the task — re-run the command and re-read the output.",
+  "tools": ["read", "edit", "write", "bash"]
+}
+```
+
+The key insight: **LLMs are bad at summarizing shell output, good at copying
+structured data**. Asking for `key=value` pairs with explicit fields and "if
+missing, you failed" forces the agent to read each field carefully. Downstream
+phases that consume `{steps.verify.output}` can then `safeParse`-it into a
+JSON object and assert against expected values.
+
+For audits where the upstream is LLM-generated prose (not shell output), use a
+plain `gate` phase with `VERDICT:` instead.
+
 ### Interpolation
 
 - `{args.X}` — invocation argument
@@ -188,6 +218,87 @@ Review the audit results below. If any endpoint is missing auth, end with
 3. Reference upstream results explicitly with `{steps.ID...}` and set `dependsOn`.
 4. Mark the result-bearing phase with `"final": true` (else the last phase wins).
 
+## Common mistakes (the runtime will reject these at validation time)
+
+The runtime validates your flow at startup. As of v0.0.8.1, the two most
+common authoring mistakes below are **hard validation errors** (the flow
+refuses to start). Fix the flow before running it.
+
+### 1. Referencing `{steps.X}` without `dependsOn: ["X"]`
+
+```jsonc
+// ❌ WRONG — 'fix-issues' will run in parallel with 'code-review-1' and see the
+// literal string "{steps.code-review-1.output}" instead of the review text.
+{
+  "id": "code-review-1", "type": "agent", "task": "review code"
+},
+{
+  "id": "fix-issues", "type": "agent",
+  "task": "fix {steps.code-review-1.output}"   // ← no dependsOn!
+}
+```
+
+Validation now rejects this with: `Phase 'fix-issues': task references
+{steps.code-review-1.*} but 'code-review-1' is not in dependsOn. ...`
+**Always declare the chain:**
+
+```jsonc
+// ✅ RIGHT
+{
+  "id": "code-review-1", "type": "agent", "task": "review code"
+},
+{
+  "id": "fix-issues", "type": "agent",
+  "task": "fix {steps.code-review-1.output}",
+  "dependsOn": ["code-review-1"]                // ← declared
+},
+{
+  "id": "code-review-2", "type": "agent",
+  "task": "re-review {steps.fix-issues.output}",
+  "dependsOn": ["fix-issues"]
+}
+```
+
+Tip: write the `task` first (it tells you what each phase needs), then scan for
+`{steps.*}` references and add the matching `dependsOn`. If a phase truly does
+not depend on anything in its task, you can omit the reference.
+
+Exception: phases with `join: "any"` are exempt from this check, since they
+deliberately wait for only one of their declared deps to complete and may
+reference others as informational context.
+
+### 2. Assuming the runtime knows "this is a chain"
+
+Phase order in the `phases` array is **documentation, not execution order**.
+The DAG comes from `dependsOn`. If you list `code-review-1`, `fix-issues`,
+`code-review-2`, `fix-final` in that order with no `dependsOn`, the runtime
+treats them as four independent phases and runs all of them in **layer 0** in
+parallel. A phase that finishes first may not be the one you expected.
+
+```jsonc
+// ❌ This is not a chain — it's 4 parallel phases, all racing.
+"phases": [
+  { "id": "code-review-1", ... },
+  { "id": "fix-issues",    ... },
+  { "id": "code-review-2", ... },
+  { "id": "fix-final",     ... }
+]
+```
+
+Use the shorthand if you literally just want `a → b → c → d`:
+
+```jsonc
+{ "chain": [
+  { "agent": "reviewer", "task": "review code" },
+  { "agent": "executor", "task": "fix {previous.output}" },
+  { "agent": "reviewer", "task": "re-review" },
+  { "agent": "executor", "task": "apply final fixes" }
+] }
+```
+
+…or write the full DAG with explicit `dependsOn` (so reviewers/fixers can run
+in parallel against multiple review streams when you want that).
+
 ## Configuration
 
 For the full set of knobs — per-phase `model`/`thinking`/`tools`/`cwd`, the
@@ -197,7 +308,7 @@ variables, and storage paths — read `configuration.md` (next to this file).
 
 Quick reference:
 
-- **Flow:** `name`, `description`, `concurrency` (default 8), `budget` (`maxUSD`/`maxTokens`), `agentScope` (user|project|both), `args`.
+- **Flow:** `name`, `description`, `concurrency` (default 8), `budget` (`maxUSD`/`maxTokens`), `agentScope` (user|project|both), `args`, `strictInterpolation`.
 - **Phase:** `model`, `thinking`, `tools` (whitelist), `cwd`, `output:"json"`, `concurrency` (map/parallel fan-out), `when`, `join` (all|any), `retry`, `use`/`with` (flow), `final`.
 - **Precedence (model/thinking/tools):** phase value → `settings.subagents.agentOverrides[agent]` → agent frontmatter → global/default.
 - **Concurrency:** same-layer phases use `flow.concurrency`; a `map`/`parallel` phase uses `phase.concurrency ?? flow.concurrency ?? 8`.

package/skills/taskflow/configuration.md

@@ -86,7 +86,6 @@ Keys of each object in `phases[]`. Some only apply to specific `type`s.
 | `cwd` | all | flow cwd | Run this phase's subagent in a different directory. |
 | `concurrency` | map, parallel | flow concurrency | Fan-out cap for this phase only. See §4. |
 | `final` | all | last phase | Exactly one phase may be `final`; its output is returned. |
-| `optional` | all | `false` | ⚠️ Declared in schema but **not yet enforced** — a failed phase still skips downstream. |
 
 ---
 
@@ -270,6 +269,5 @@ Taskflow shares the subagent settings file at `~/.pi/agent/settings.json`:
 These keys validate but the runtime does **not** act on them yet — don't rely on
 them for behavior:
 
-- `phase.optional` — a failed phase still marks downstream phases as skipped.
 - `arg.required` — missing required args are not rejected.
 - `flow.version` — informational only.