projectinator 0.1.5 → 0.2.0

package/README.md

@@ -7,7 +7,7 @@
 [![npm](https://img.shields.io/npm/v/projectinator.svg?color=e0a72d&label=npm)](https://www.npmjs.com/package/projectinator)
 ![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
 ![node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)
-![tests: 140 passing](https://img.shields.io/badge/tests-140%20passing-brightgreen.svg)
+![tests: 157 passing](https://img.shields.io/badge/tests-157%20passing-brightgreen.svg)
 ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)
 ![built on Pi](https://img.shields.io/badge/built%20on-Pi%20agent%20harness-e0a72d.svg)
 
@@ -49,7 +49,8 @@ npm start
 </details>
 
 > **Optional:** `npx playwright install chromium` lets the tester actually run web apps in a
-> headless browser and enables live preview. Everything else works without it.
+> headless browser and enables live preview. Without it the tester can only read the code —
+> such passes show as **PASS\*** with a warning. Everything else works without it.
 
 > Projectinator spends **your** API money. Every screen shows the running cost; you set a
 > budget cap and it halts before crossing it. A tiny landing page is cents; a full app is
@@ -64,13 +65,15 @@ Type an idea → it plans → you approve → it builds, tests, and hands you wo
 - **Best model per role.** Roles bind to a *capability + tier*, never a model name. A
   swappable registry maps capabilities to models — new frontier model next month, edit one
   place, every route updates. Run a **bake-off** to pick empirically.
-- **A real pipeline.** PM decomposes → Designer specs → Developer writes files → Tester
-  **runs the app headless and catches real bugs** → feedback loop re-runs the dev on failure.
+- **A real pipeline.** PM decomposes → Designer specs → Developer writes files → **Reviewer**
+  (cheap, read-only) checks the wiring → Tester **runs the app headless and catches real
+  bugs** → feedback loop re-runs the dev on failure.
 - **Multi-file apps.** Vanilla HTML/CSS/JS or **React (CDN, no build)** — your choice.
 - **The cockpit.** A polished terminal UI: editable board, Kanban, standup, per-task cost,
   live budget bar, desktop notification when done.
 - **Honest cost.** Live spend tracking, per-project budget cap + an alert before the cap,
-  and predicted-vs-actual reporting that sharpens itself over real runs.
+  **per-task timeout and cost ceiling**, and predicted-vs-actual reporting that sharpens
+  itself over real runs.
 
 ## Highlights
 
@@ -79,13 +82,16 @@ Type an idea → it plans → you approve → it builds, tests, and hands you wo
 | 🧠 **PM intake** | Vague request? The PM asks 2–4 clarifying questions (with pickable options) before planning. Specific requests skip straight through. |
 | 🏛 **Deep plan (council)** | Opt-in: architect + product + risk leads propose epics in parallel, a synthesizer merges them, you approve, then they expand into the backlog. |
 | 🆚 **Model bake-off** | Run one task across models, an LLM judge scores the outputs, compare cost/latency/quality — save the winner to the registry. |
-| 🧪 **Real test execution** | The tester loads the built app in headless Chromium and fails on JS/console errors — not just by reading the code. |
+| 🔍 **Reviewer** | A cheap read-only model checks each code task's wiring (missing files, unresolved `<script src>`, undefined functions, ES modules on a static site) before the Tester spends a browser run. Fails feed the same Developer fix loop. |
+| 🧪 **Real test execution** | The tester loads the built app in headless Chromium and fails on JS/console errors — not just by reading the code. Without Chromium, passes are marked **PASS\*** so you know the app was never run. |
 | 👁 **Live preview** | Local server + auto-reload; ES modules and fetch resolve like production. |
 | 🚀 **Deploy** | One click to Cloudflare Pages, Vercel, or Netlify (their CLI + your login). |
 | 📤 **Export** | Backlog → Markdown, CSV, **Jira** CSV, **Trello** CSV. |
 | 📜 **Git per build** | The workspace is a git repo; one commit per task. History view + **undo a task**. |
 | 📊 **Analytics** | Retro (with optional AI narrative), burndown, cost by epic/model, and estimate accuracy that self-calibrates from real runs. |
 | 💾 **Templates** | Save a project's brief as a reusable template; import/share as a file. |
+| ⛔ **Task limits** | Per-task timeout and cost ceiling (Settings → Preferences). A runaway task is aborted, billed for what it spent, and the build halts — resumable. |
+| ✎ **Task notes** | Annotate any task on the board (`n`). Yours only — never sent to a model; included in exports. |
 
 ## How it works
 
@@ -95,8 +101,7 @@ idea
  └─ intake?     PM asks clarifying questions if the request is vague
  └─ plan mode?  Quick (one PM) or Deep (planning council → approve epics)
  └─ decompose   → a routed, epic-tagged backlog with a cost estimate
- └─ approve     → auto-run, or gate the backlog / gate again before dev
- └─ build       toposort deps · design → code → test · Tester→Dev feedback loop
+ └─ build       toposort deps · design → code → review → test · Reviewer/Tester→Dev feedback loop
  └─ done        working files + retro + deploy/export/preview
 ```
 
@@ -120,8 +125,9 @@ npm start                                         # the cockpit (the normal way
 npm run build -- --live --mini                    # cheap end-to-end proof (~$0.10)
 npm run build -- --live --lock anthropic "idea"   # full pipeline on one provider
 npm run build -- --live --mini --resume           # resume a halted/finished build (skips done tasks)
+npm run build -- --live --mini --task-cap 0.5 --task-timeout 5   # per-task limits (USD / minutes)
 npm run bakeoff -- --capability design "Design a pricing page"   # model bake-off
-npm test                                          # 140 tests
+npm test                                          # 157 tests
 npm run typecheck
 ```
 
@@ -129,7 +135,8 @@ npm run typecheck
 
 - **Keys** are stored at `~/.projectinator/config.json` (chmod 0600) — never in the repo.
 - **Settings** (in the app): API keys, preferred provider, default workflow, default stack,
-  model assignments, budget cap + alert %, estimate accuracy.
+  model assignments (incl. the Reviewer), budget cap + alert %, per-task timeout + cost cap,
+  estimate accuracy.
 - **User data** lives under `~/.projectinator/` (config, calibration, templates, exports).
   Each build gets its own git-versioned workspace folder (one commit per finished task).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectinator",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Your AI build team in the terminal — hand it an app idea, a PM model plans a Scrum backlog, and the best model per role designs, codes, and tests it into working files. Bring your own API key.",
   "type": "module",
   "private": false,

package/src/build-state.ts

@@ -40,7 +40,8 @@ export function loadState(path: string): BuildState | undefined {
   }
 }
 
-/** Which task ids are already finished (last outcome wins). Used to skip on resume. */
+/** Which task ids are already finished (last outcome wins; a failed attempt does not
+ *  count). Used to skip on resume. */
 export function completedIds(state: BuildState): Set<string> {
-  return new Set(state.outcomes.map((o) => o.taskId));
+  return new Set(state.outcomes.filter((o) => !o.error).map((o) => o.taskId));
 }

package/src/cost.ts

@@ -22,7 +22,9 @@ function ratesFor(model: Model, inputTokens: number) {
 }
 
 /** Estimate USD cost for one task on a given model.
- *  A fraction of input can be served from cache at the cheaper cacheRead rate. */
+ *  A fraction of input can be served from cache at the cheaper cacheRead rate.
+ *  Kept to 4 decimals, not cents: a backlog of sub-cent tasks would otherwise
+ *  estimate to $0.00 and under-reserve budget in the parallel scheduler. */
 export function estimateCost(est: TokenEstimate, model: Model): number {
   const cachedFraction = clamp01(est.cachedInputFraction ?? 0);
   const rate = ratesFor(model, est.input);
@@ -33,13 +35,9 @@ export function estimateCost(est: TokenEstimate, model: Model): number {
   const inputCost = (freshInput / PER_MILLION) * rate.input + (cachedInput / PER_MILLION) * rate.cacheRead;
   const outputCost = (est.output / PER_MILLION) * rate.output;
 
-  return round2(inputCost + outputCost);
+  return Math.round((inputCost + outputCost) * 10_000) / 10_000;
 }
 
 function clamp01(n: number): number {
   return Math.max(0, Math.min(1, n));
 }
-
-function round2(n: number): number {
-  return Math.round(n * 100) / 100;
-}

package/src/estimate.ts

@@ -37,6 +37,13 @@ const BUCKETS: Record<Capability, Record<Difficulty, Bucket>> = {
     medium: { input: 25_000, output: 7_000 },
     high: { input: 60_000, output: 14_000 },
   },
+  // Review reads the same tree the tester does but never runs it — shorter output.
+  review: {
+    trivial: { input: 15_000, output: 800 },
+    low: { input: 25_000, output: 1_500 },
+    medium: { input: 50_000, output: 3_000 },
+    high: { input: 80_000, output: 5_000 },
+  },
   test: {
     trivial: { input: 15_000, output: 1_200 },
     low: { input: 25_000, output: 2_500 },

package/src/orchestrator.ts

@@ -8,12 +8,13 @@
 // The executor is INJECTED (RoleExecutor), so this entire control flow is testable
 // offline with a fake — no model, no spend. The real Pi executor lives in roles.ts.
 
-import type {
-  RegistryEntry,
-  RoleExecutor,
-  RoutingPolicy,
-  Task,
-  TaskOutcome,
+import {
+  TaskLimitError,
+  type RegistryEntry,
+  type RoleExecutor,
+  type RoutingPolicy,
+  type Task,
+  type TaskOutcome,
 } from "./types.js";
 import { route } from "./router.js";
 import { REGISTRY } from "./registry.js";
@@ -62,6 +63,7 @@ export interface RunOptions {
 export type OrchestratorEvent =
   | { type: "task_start"; task: Task; round: number; provider: string; modelId: string }
   | { type: "task_done"; outcome: TaskOutcome; runningTotal: number }
+  | { type: "task_failed"; outcome: TaskOutcome; runningTotal: number }
   | { type: "task_skipped"; taskId: string }
   | { type: "test_failed"; taskId: string; bugs: number; round: number }
   | { type: "retry_dev"; taskId: string; forTest: string; round: number }
@@ -107,14 +109,19 @@ export async function runBacklog(tasks: Task[], opts: RunOptions): Promise<RunRe
   let running = 0;
 
   // Resume: replay prior outcomes so finished tasks are skipped and cost is restored.
+  // A failed attempt is billed but never "done" — it is rebuilt.
   const seed = opts.seedOutcomes ?? [];
   for (const o of seed) {
     record.push(o);
-    outcomes.set(o.taskId, o); // last wins (retries overwrite)
+    if (o.error) outcomes.delete(o.taskId); // last wins: a later failure voids an earlier pass
+    else outcomes.set(o.taskId, o);
     running += o.cost;
   }
   running = round2(running);
-  const wasDone = new Set(seed.map((o) => o.taskId));
+  const wasDone = new Set(outcomes.keys());
+
+  let halted = false;
+  let haltReason: string | undefined;
 
   const emit = opts.onProgress ?? (() => {});
   const checkpoint = () => opts.onCheckpoint?.(record, round2(running));
@@ -132,39 +139,58 @@ export async function runBacklog(tasks: Task[], opts: RunOptions): Promise<RunRe
     const decision = route(task, { policy, registry, runningTotalBefore: running });
     emit({ type: "task_start", task, round, provider: decision.provider, modelId: decision.model.id });
     const contextText = contextOverride ?? gatherContext(task, outcomes);
-    const result = await execute({ task, decision, contextText, round });
-    const outcome: TaskOutcome = {
-      ...result,
-      taskId: task.id,
-      capability: task.capability,
-      provider: decision.provider,
-      modelId: decision.model.id,
-      round,
-    };
-    running += result.cost;
+    const meta = { taskId: task.id, capability: task.capability, provider: decision.provider, modelId: decision.model.id, round };
+    let outcome: TaskOutcome;
+    try {
+      outcome = { ...(await execute({ task, decision, contextText, round, limits: policy.taskLimits })), ...meta };
+    } catch (e) {
+      if (!(e instanceof TaskLimitError)) throw e;
+      // Limit breach: bill what was spent, record the failure, halt the build.
+      outcome = { finalText: "", files: [], cost: e.costSoFar, error: e.message, ...meta };
+      running += outcome.cost;
+      record.push(outcome);
+      halted = true;
+      haltReason = `${task.id} aborted: ${e.message}`;
+      emit({ type: "task_failed", outcome, runningTotal: round2(running) });
+      return outcome;
+    }
+    running += outcome.cost;
     outcomes.set(task.id, outcome);
     record.push(outcome);
     emit({ type: "task_done", outcome, runningTotal: round2(running) });
     return outcome;
   };
 
-  // One task's full lifecycle: run it, then its Tester->Developer feedback loop.
+  // One task's full lifecycle: run it, then its Reviewer/Tester -> Developer feedback loop.
   const runTaskUnit = async (task: Task): Promise<void> => {
     let outcome = await runOne(task, 0);
-    if (task.capability === "test" && outcome.verdict && !outcome.verdict.passed) {
-      const codeDeps = (task.dependsOn ?? [])
-        .map((id) => byId.get(id))
-        .filter((t): t is Task => !!t && t.capability === "code");
+    const judges = task.capability === "test" || task.capability === "review";
+    if (!outcome.error && judges && outcome.verdict && !outcome.verdict.passed) {
+      // The code to fix: direct code deps, plus code deps reached through a review
+      // (a test depends on the review, which depends on the code).
+      const codeDeps: Task[] = [];
+      for (const id of task.dependsOn ?? []) {
+        const dep = byId.get(id);
+        if (!dep) continue;
+        if (dep.capability === "code") codeDeps.push(dep);
+        else if (dep.capability === "review") {
+          for (const id2 of dep.dependsOn ?? []) {
+            const d2 = byId.get(id2);
+            if (d2?.capability === "code" && !codeDeps.includes(d2)) codeDeps.push(d2);
+          }
+        }
+      }
 
       let round = 1;
-      while (outcome.verdict && !outcome.verdict.passed && round <= policy.maxFeedbackRounds) {
+      fix: while (outcome.verdict && !outcome.verdict.passed && round <= policy.maxFeedbackRounds) {
         emit({ type: "test_failed", taskId: task.id, bugs: outcome.verdict.bugs.length, round });
         const fixContext = bugReport(outcome.verdict.bugs);
         for (const dep of codeDeps) {
           emit({ type: "retry_dev", taskId: dep.id, forTest: task.id, round });
-          await runOne(dep, round, fixContext);
+          if ((await runOne(dep, round, fixContext)).error) break fix;
         }
         outcome = await runOne(task, round); // re-test
+        if (outcome.error) break;
         round++;
       }
     }
@@ -201,6 +227,7 @@ export async function runBacklog(tasks: Task[], opts: RunOptions): Promise<RunRe
         return { outcomes: record, totalCost: round2(running), halted: true, haltReason: "budget cap" };
       }
       await runTaskUnit(task);
+      if (halted) return { outcomes: record, totalCost: round2(running), halted, haltReason };
     }
     return { outcomes: record, totalCost: round2(running), halted: false };
   }
@@ -215,8 +242,7 @@ export async function runBacklog(tasks: Task[], opts: RunOptions): Promise<RunRe
   const inFlight = new Map<string, Promise<void>>();
   let reserved = 0;
   let codeInFlight = 0; // code tasks are serialized (they share files) even in parallel mode
-  let halted = false;
-  let haltReason: string | undefined;
+  let failure: unknown; // first task error; rethrown after in-flight work drains
 
   const depsSatisfied = (t: Task) => (t.dependsOn ?? []).every((d) => !remaining.has(d));
   const readyTasks = () =>
@@ -235,8 +261,10 @@ export async function runBacklog(tasks: Task[], opts: RunOptions): Promise<RunRe
       if (inFlight.size >= concurrency) break;
       // Only one code task builds at a time — they write to the shared workspace.
       if (task.capability === "code" && codeInFlight >= 1) continue;
-      const est = route(task, { policy, registry, runningTotalBefore: round2(running + reserved) });
-      if (round2(running + reserved + est.cost) > policy.budgetCapUSD) {
+      // Reservations keep full precision: rounding each one to cents drops sub-cent
+      // estimates entirely, so a wide backlog of cheap tasks would under-reserve.
+      const est = route(task, { policy, registry, runningTotalBefore: running + reserved });
+      if (running + reserved + est.cost > policy.budgetCapUSD) {
         if (inFlight.size === 0) {
           emit({ type: "budget_halt", runningTotal: round2(running + est.cost), cap: policy.budgetCapUSD });
           halted = true;
@@ -244,15 +272,25 @@ export async function runBacklog(tasks: Task[], opts: RunOptions): Promise<RunRe
         }
         break; // wait for in-flight tasks to free budget/capacity
       }
-      reserved = round2(reserved + est.cost);
+      reserved += est.cost;
       const cost = est.cost;
       const isCode = task.capability === "code";
       if (isCode) codeInFlight++;
-      const p = runTaskUnit(task).then(() => {
+      const settle = () => {
         if (isCode) codeInFlight--;
-        reserved = round2(reserved - cost);
+        reserved -= cost;
         remaining.delete(task.id);
         inFlight.delete(task.id);
+      };
+      // A rejection must NOT escape through Promise.race below: that abandons the
+      // sibling promises, and their later rejections would have no handler attached
+      // (unhandled rejection -> the host process dies mid-build). Capture the first
+      // failure, stop launching, drain what's running, checkpoint, then rethrow.
+      const p = runTaskUnit(task).then(settle, (e: unknown) => {
+        settle();
+        halted = true;
+        haltReason ??= e instanceof Error ? e.message : String(e);
+        failure ??= e;
       });
       inFlight.set(task.id, p);
     }
@@ -263,6 +301,7 @@ export async function runBacklog(tasks: Task[], opts: RunOptions): Promise<RunRe
 
   await Promise.all(inFlight.values());
   checkpoint();
+  if (failure) throw failure;
   return { outcomes: record, totalCost: round2(running), halted, haltReason };
 }
 

package/src/pm.ts

@@ -31,7 +31,7 @@ const TaskSchema = Type.Object(
   {
     id: Type.String({ description: "Unique task id, e.g. T-01" }),
     title: Type.String({ description: "One concrete, buildable unit of work" }),
-    capability: Type.String({ description: "one of: plan | design | code | test | ops" }),
+    capability: Type.String({ description: "one of: plan | design | code | review | test | ops" }),
     difficulty: Type.String({ description: "one of: trivial | low | medium | high" }),
     dependsOn: Type.Optional(Type.Array(Type.String(), { description: "task ids that must finish first" })),
     epic: Type.Optional(Type.String({ description: "optional grouping label" })),
@@ -41,7 +41,7 @@ const TaskSchema = Type.Object(
 );
 const BacklogSchema = Type.Object({ tasks: Type.Array(TaskSchema) }, { additionalProperties: true });
 
-const CAPS = new Set<Capability>(["plan", "design", "code", "test", "ops"]);
+const CAPS = new Set<Capability>(["plan", "design", "code", "review", "test", "ops"]);
 const DIFFS = new Set<Difficulty>(["trivial", "low", "medium", "high"]);
 function coerceCap(s: string): Capability {
   const v = s?.toLowerCase().trim() as Capability;
@@ -78,9 +78,10 @@ export function pmSystemPrompt(scope: Scope = "full"): string {
     scope === "change"
       ? [
           "This is a CHANGE to an EXISTING project whose files are already on disk.",
-          "Produce the FEWEST tasks that accomplish the change — usually 1 code task,",
-          "plus 1 test task only if the change is risky. Do NOT re-plan the whole project,",
-          "do NOT add design/setup/deploy tasks. One small tweak = one task.",
+          "Produce the FEWEST tasks that accomplish the change — usually 1 code task plus 1",
+          "`review` task that dependsOn it (cheap read-only wiring check), plus 1 test task",
+          "(dependsOn the review) only if the change is risky. Do NOT re-plan the whole project,",
+          "do NOT add design/setup/deploy tasks. One small tweak = code + review.",
         ]
       : [
           "Scale the number of tasks to the request. A tiny page = a few tasks; a full app = many.",
@@ -92,6 +93,9 @@ export function pmSystemPrompt(scope: Scope = "full"): string {
           "src/components/Header.jsx') and keep file names CONSISTENT across tasks — decide one",
           "structure and reuse it. When several files must agree, add ONE early design task that",
           "defines the file tree, and have the code tasks depend on it.",
+          "After EVERY code task add one `review` task that dependsOn that code task (a cheap",
+          "read-only wiring check). The test task must dependsOn the review task(s), not the code",
+          "task(s) directly. Order: design -> code -> review -> test.",
         ];
   return [
     "You are the PROJECT MANAGER on an autonomous software team.",
@@ -100,7 +104,7 @@ export function pmSystemPrompt(scope: Scope = "full"): string {
     "",
     "Each TASK must be:",
     "- atomic: one model can complete it in one focused turn",
-    "- tagged with a capability: plan | design | code | test | ops",
+    "- tagged with a capability: plan | design | code | review | test | ops",
     "- tagged with a difficulty: trivial | low | medium | high (how hard the thinking is)",
     "Optional per task: dependsOn (ids that must finish first, e.g. code depends on design),",
     "and epic/story labels for grouping. Use ids like T-01, unique across the list.",

package/src/preview.ts

@@ -10,7 +10,7 @@
 // relative paths all resolve the way they will in production.
 
 import { createServer, type Server } from "node:http";
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { extname, join, normalize } from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -145,6 +145,20 @@ async function renderOne(
   }
 }
 
+/** Whether the tester can actually run apps: Playwright's Chromium is installed.
+ *  No launch, just the executable lookup — cheap enough to call per task.
+ *  Dynamic import on purpose (same as renderCheck): playwright is optional. */
+export async function chromiumAvailable(): Promise<boolean> {
+  try {
+    const { chromium } = await import("playwright");
+    return existsSync(chromium.executablePath());
+  } catch {
+    return false;
+  }
+}
+
+export const CHROMIUM_INSTALL_HINT = "run `npx playwright install chromium` to enable real test execution";
+
 /** Load a built page in headless Chromium and report what actually happened —
  *  over http (production-like) AND over file:// (how a user double-clicks it). */
 export async function renderCheck(

package/src/registry.ts

@@ -66,6 +66,18 @@ export const REGISTRY: RegistryEntry[] = [
     updated: "2026-07-15",
   },
 
+  // --- REVIEW (read-only wiring check before the tester; one row -> every difficulty is cheap) ---
+  {
+    capability: "review",
+    tier: "fast",
+    byBackend: {
+      web: { provider: "google", model: "gemini-3.1-pro-preview" },
+      api: { provider: "google", model: "gemini-3-flash-preview" },
+    },
+    evidence: "Read-only static check; cheapest tier is adequate, same picks as test",
+    updated: "2026-09-15",
+  },
+
   // --- TEST (QA / review, high volume -> cheap) ---
   {
     capability: "test",

package/src/retro.ts

@@ -2,7 +2,7 @@
 // build-state: what passed, what the tester flagged, cost per epic and per
 // model, retries, and the priciest tasks. No model call.
 
-import type { BuildState } from "./build-state.js";
+import { completedIds, type BuildState } from "./build-state.js";
 import type { Bug, Difficulty } from "./types.js";
 import { baselineTokens } from "./estimate.js";
 import { estimateCost } from "./cost.js";
@@ -30,7 +30,7 @@ export function computeRetro(state: BuildState): RetroReport {
   const epicById = new Map(state.tasks.map((t) => [t.id, t.epic || "General"]));
   const diffById = new Map(state.tasks.map((t) => [t.id, t.difficulty]));
   const outcomes = state.outcomes;
-  const doneIds = new Set(outcomes.map((o) => o.taskId));
+  const doneIds = completedIds(state);
 
   // Baseline-predicted cost for each run: static token budget × the model that ran it.
   let estCost = 0;