@splinterzzz/ouro 0.1.0 → 0.1.2

package/src/lib/claudeCodeExec.js

@@ -122,22 +122,26 @@ export async function askJson({ prompt, cwd, signal }) {
 }
 
 /**
- * Triage: read-only tools only, no file writes. Claude Code doesn't have a
- * sandbox flag like Codex — read-only-ness comes from restricting
- * --allowedTools instead.
+ * Analyze: a read-only agent pass (the Analyst agent) that scopes the ticket.
+ * Read-only-ness comes from restricting --allowedTools — Claude Code has no
+ * sandbox flag like Codex. The agent's tools are intersected with the read-only
+ * set, so even a mis-granted Write can't take effect here. Streams events to
+ * `onEvent` so the analysis is visible on the card like any other run, and
+ * returns structured findings — crucially the acceptance criteria that plan/
+ * execute and the QA gate are both held to.
  */
-export async function triage({ prompt, cwd, signal }) {
+export async function analyze({ prompt, cwd, signal, agent, onEvent }) {
   const { lastMessage } = await runClaude(
     [
       "-p",
-      `${prompt}\n\nRespond with ONLY a JSON object: {"summary": string, "priority": "low"|"medium"|"high", "files_likely_affected": string[]}. No prose, no markdown fences.`,
+      `${prompt}\n\nRespond with ONLY a JSON object: {"summary": string, "priority": "low"|"medium"|"high", "files_likely_affected": string[], "acceptance_criteria": string[]}. Each acceptance_criteria item is a concrete, checkable definition-of-done statement a test or reviewer could mark pass/fail. No prose, no markdown fences.`,
       "--output-format",
       "stream-json",
       "--verbose",
-      "--allowedTools",
-      READ_ONLY_TOOLS.join(","),
+      ...agentFlags(agent, READ_ONLY_TOOLS),
+      ...(agent ? [] : ["--allowedTools", READ_ONLY_TOOLS.join(",")]),
     ],
-    { cwd, signal }
+    { cwd, signal, onEvent }
   );
 
   return (
@@ -145,6 +149,7 @@ export async function triage({ prompt, cwd, signal }) {
       summary: lastMessage ?? "(no summary returned)",
       priority: "medium",
       files_likely_affected: [],
+      acceptance_criteria: [],
     }
   );
 }
@@ -170,6 +175,46 @@ export function runAgent({ prompt, cwd, onEvent, signal, agent }) {
   );
 }
 
+/**
+ * Staging QA gate: the Senior QA Engineer agent validates the running result.
+ *
+ * Deliberately READ-ONLY — Read/Grep/Glob, no Bash, no bypassPermissions. QA is
+ * a validator, not an implementer: ouro runs the tests and hands QA the results
+ * and the diff, so QA only needs to read the change, the source, and any built
+ * HTML. Denying Bash matters because ticket title/body are untrusted (Telegram
+ * intake is external), and an unrestricted Bash validator would turn a prompt-
+ * injected ticket into arbitrary command execution. Returns the parsed JSON
+ * verdict (null if unparseable).
+ */
+export async function qaReview({ prompt, cwd, signal, onEvent, agent }) {
+  const { lastMessage } = await runClaude(
+    [
+      "-p",
+      prompt,
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      ...agentFlags(agent, READ_ONLY_TOOLS),
+      ...(agent ? [] : ["--allowedTools", READ_ONLY_TOOLS.join(",")]),
+    ],
+    { cwd, signal, onEvent }
+  );
+  return parseJsonish(lastMessage);
+}
+
+/**
+ * Read-only run that returns the raw final message. Backs `ouro init --spec`
+ * (reverse-engineering a CLAUDE.md): the agent explores but never writes — ouro
+ * writes the file from what comes back, so "read-only" stays literally true.
+ */
+export async function generateSpec({ prompt, cwd, signal, onEvent }) {
+  const { lastMessage } = await runClaude(
+    ["-p", prompt, "--output-format", "stream-json", "--verbose", "--allowedTools", READ_ONLY_TOOLS.join(",")],
+    { cwd, signal, onEvent }
+  );
+  return lastMessage;
+}
+
 /**
  * Human-in-the-loop, phase 1: plan only, read-only tools, no edits. Returns
  * the session_id so the UI can resume it once the person approves.

package/src/lib/codexExec.js

@@ -16,14 +16,17 @@ import path from "node:path";
 
 const CODEX_BIN = process.env.OURO_CODEX_BIN || "codex";
 
-const TRIAGE_SCHEMA = {
+const ANALYZE_SCHEMA = {
   type: "object",
   properties: {
     summary: { type: "string" },
     priority: { type: "string", enum: ["low", "medium", "high"] },
     files_likely_affected: { type: "array", items: { type: "string" } },
+    // Checkable definition-of-done items. Plan/execute implement against these
+    // and the QA gate validates against them, so they must be concrete.
+    acceptance_criteria: { type: "array", items: { type: "string" } },
   },
-  required: ["summary", "priority", "files_likely_affected"],
+  required: ["summary", "priority", "files_likely_affected", "acceptance_criteria"],
   additionalProperties: false,
 };
 
@@ -124,18 +127,18 @@ export async function askJson({ prompt, cwd, signal }) {
 }
 
 /**
- * Triage: read-only, schema-constrained call. Cheap, safe, no repo writes.
+ * Analyze: read-only, schema-constrained call. Cheap, safe, no repo writes.
  */
-export async function triage({ prompt, cwd, signal }) {
+export async function analyze({ prompt, cwd, signal, agent, onEvent }) {
   // os.tmpdir(), not a hardcoded /tmp — this has to work on Windows too. The
-  // pid suffix keeps concurrent triages off one another's schema file.
-  const schemaPath = path.join(os.tmpdir(), `ouro-triage-schema-${process.pid}.json`);
-  fs.writeFileSync(schemaPath, JSON.stringify(TRIAGE_SCHEMA));
+  // pid suffix keeps concurrent analyses off one another's schema file.
+  const schemaPath = path.join(os.tmpdir(), `ouro-analyze-schema-${process.pid}.json`);
+  fs.writeFileSync(schemaPath, JSON.stringify(ANALYZE_SCHEMA));
 
   try {
     const { lastMessage } = await runCodexExec(
-      ["exec", prompt, "--json", "--sandbox", "read-only", "--output-schema", schemaPath],
-      { cwd, signal }
+      ["exec", prompt, "--json", "--sandbox", "read-only", "--output-schema", schemaPath, ...agentFlags(agent)],
+      { cwd, signal, onEvent }
     );
 
     return (
@@ -143,6 +146,7 @@ export async function triage({ prompt, cwd, signal }) {
         summary: lastMessage ?? "(no summary returned)",
         priority: "medium",
         files_likely_affected: [],
+        acceptance_criteria: [],
       }
     );
   } finally {
@@ -161,6 +165,34 @@ export function runAgent({ prompt, cwd, onEvent, signal, agent }) {
   );
 }
 
+/**
+ * Staging QA gate on the Codex backend. Read-only sandbox — Codex has no
+ * per-tool grant, so read-only is how "validate, don't modify" is enforced (the
+ * tests were already run by ouro). Returns the parsed JSON verdict.
+ */
+export async function qaReview({ prompt, cwd, signal, onEvent, agent }) {
+  const { lastMessage } = await runCodexExec(["exec", prompt, "--json", "--sandbox", "read-only", ...agentFlags(agent)], {
+    cwd,
+    signal,
+    onEvent,
+  });
+  return parseJsonish(lastMessage);
+}
+
+/**
+ * Read-only run that returns the raw final message. Backs `ouro init --spec` —
+ * the agent explores under a read-only sandbox and ouro writes the file, so
+ * "read-only" holds literally.
+ */
+export async function generateSpec({ prompt, cwd, signal, onEvent }) {
+  const { lastMessage } = await runCodexExec(["exec", prompt, "--json", "--sandbox", "read-only"], {
+    cwd,
+    signal,
+    onEvent,
+  });
+  return lastMessage;
+}
+
 /**
  * Human-in-the-loop, phase 1: plan only, read-only sandbox, no writes.
  * Non-interactive headless mode can't reliably pause mid-run for approval

package/src/lib/config.js

@@ -20,6 +20,15 @@ const DEFAULTS = {
     botTokenEnvVar: "OURO_TELEGRAM_BOT_TOKEN",
     chatIdEnvVar: "OURO_TELEGRAM_CHAT_ID",
   },
+  // Staging stage (Feature 9). All null by default: ouro resolves the test and
+  // preview commands from the repo when these aren't set, so a fresh repo needs
+  // zero config. Set them to pin exact commands. previewPort is where the
+  // preview is expected to listen (used to build the clickable URL).
+  staging: {
+    testCommand: null,
+    previewCommand: null,
+    previewPort: null,
+  },
 };
 
 export function readConfig() {
@@ -85,6 +94,16 @@ export function getAutoShip() {
   return readConfig().autoShip !== false;
 }
 
+/** Staging config, each field null when unset (ouro then resolves it per-repo). */
+export function getStaging() {
+  const s = readConfig().staging ?? {};
+  return {
+    testCommand: s.testCommand ?? null,
+    previewCommand: s.previewCommand ?? null,
+    previewPort: s.previewPort ?? null,
+  };
+}
+
 export function setAutoShip(on) {
   writeConfig({ autoShip: Boolean(on) });
   return Boolean(on);

package/src/lib/ouroLog.js

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import { contextDir } from "./paths.js";
+
+// ouro-log.md — a human-readable run history. Not a git-log clone: the skimmable
+// summary for people who don't want to read git history.
+//
+// One entry per run, appended at run end regardless of outcome (shipped, failed,
+// no-change, cancelled — all recorded). Templated from ticket state ouro already
+// holds — NOT an extra LLM call. It lives in .ouro/context/, so it's both a
+// viewable log AND an auto-attached artifact (cross-ticket memory), and it's
+// committed (see .ouro/.gitignore) as team memory that travels with the repo.
+//
+// Populated post-`ouro init` only — there is no retrace of prior git history.
+
+const LOG_FILENAME = "ouro-log.md";
+
+const HEADER = `# ouro run log
+
+Skimmable run history — one line per run, newest at the bottom of each day.
+Templated from ticket state (not an LLM call) and committed as team memory.
+`;
+
+function logPath() {
+  return path.join(contextDir(), LOG_FILENAME);
+}
+
+export function logFilename() {
+  return LOG_FILENAME;
+}
+
+function modeLabel(mode) {
+  return mode === "agent" ? "agent loop" : "human-in-loop";
+}
+
+function prNumber(url) {
+  const m = String(url || "").match(/\/pull\/(\d+)/);
+  return m ? `#${m[1]}` : null;
+}
+
+// File count from the stored unified diff — one "diff --git" line per file. Kept
+// here rather than re-shelling to git so the log never depends on the worktree
+// still existing at write time.
+function fileCount(diff) {
+  if (!diff) return 0;
+  return (diff.match(/^diff --git /gm) || []).length;
+}
+
+/**
+ * Append one entry for a finished run. `outcome` is the short result phrase;
+ * PR link and file count are derived from the ticket. Best-effort: a failure to
+ * write the log (e.g. .ouro/context/ absent pre-init) never fails the run.
+ */
+export function appendRunLog(ticket, outcome, when = new Date()) {
+  if (!ticket) return;
+  try {
+    const dateStr = when.toISOString().slice(0, 10); // YYYY-MM-DD
+    const timeStr = when.toTimeString().slice(0, 5); // HH:MM (local)
+
+    const bits = [outcome];
+    const pr = prNumber(ticket.prUrl);
+    if (pr) bits.push(`PR ${pr}`);
+    const files = fileCount(ticket.diff);
+    if (files) bits.push(`${files} file${files === 1 ? "" : "s"}`);
+
+    const title = String(ticket.title ?? "").replace(/\s+/g, " ").trim() || "(untitled)";
+    const entry = `- **${timeStr}** · [#${ticket.id}] ${title} · ${modeLabel(ticket.mode)}\n  → ${bits.join(" · ")}\n`;
+
+    let existing;
+    try {
+      existing = fs.readFileSync(logPath(), "utf-8");
+    } catch {
+      existing = HEADER; // first write seeds the header
+    }
+
+    // A fresh date header only when today isn't already present.
+    const needsDateHeader = !existing.includes(`\n## ${dateStr}\n`);
+    fs.writeFileSync(logPath(), existing + (needsDateHeader ? `\n## ${dateStr}\n` : "") + entry);
+  } catch {
+    // Logging is memory, not control flow — never let it break a run.
+  }
+}
+
+/** Raw markdown of the log, or "" if it doesn't exist yet. Backs the Logs tab. */
+export function readRunLog() {
+  try {
+    return fs.readFileSync(logPath(), "utf-8");
+  } catch {
+    return "";
+  }
+}

package/src/lib/paths.js

@@ -29,6 +29,13 @@ export function agentsDir() {
   return path.join(ouroDir(), "agents");
 }
 
+// Shared, committed context payload — the droppable artifacts every run can
+// discover (manifest-injected, never content-dumped) plus the ouro-log.md run
+// history. Committed via .ouro/.gitignore's `!context/`. See lib/artifacts.js.
+export function contextDir() {
+  return path.join(ouroDir(), "context");
+}
+
 // Daemon bookkeeping: one pid file and one log per background service.
 // See lib/daemon.js.
 export function runDir() {
@@ -47,7 +54,7 @@ export function envPath() {
 }
 
 export function ensureOuroDir() {
-  for (const dir of [ouroDir(), worktreesDir(), agentsDir(), runDir(), logsDir()]) {
+  for (const dir of [ouroDir(), worktreesDir(), agentsDir(), contextDir(), runDir(), logsDir()]) {
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   }
 }

package/src/lib/preview.js

@@ -0,0 +1,120 @@
+import { spawn } from "node:child_process";
+import net from "node:net";
+import { getStaging } from "./config.js";
+import { askJson } from "./agentBackend.js";
+
+// Staging preview servers — launch, track, and stop the local deployment a
+// ticket is reviewed against. Tracked per-ticket so it can be torn down when the
+// ticket ships, loops back, or is cancelled.
+//
+// Everything here is best-effort: if no command resolves, or it won't start, or
+// the port never opens, the stage proceeds tests-only. A preview problem must
+// NEVER fail the stage (spec).
+
+const previews = new Map(); // ticketId -> { proc, url, command, port }
+
+/**
+ * Resolve how to start the preview: config.staging.previewCommand + previewPort
+ * if set, else a cheap read-only agent inference. Returns { command, port,
+ * source } with source "config" | "inferred" | "none".
+ */
+export async function resolvePreview({ cwd, signal }) {
+  const s = getStaging();
+  if (s.previewCommand && s.previewPort) {
+    return { command: String(s.previewCommand), port: Number(s.previewPort), source: "config" };
+  }
+
+  const inferred = await askJson({
+    prompt:
+      "Infer how to start this project's local preview / dev server and the port it listens on, from its config (package.json scripts, framework config). " +
+      'Respond with ONLY JSON: {"command": string|null, "port": number|null}. Use null if there is no runnable preview. No prose, no fences.',
+    cwd,
+    signal,
+  }).catch(() => null);
+
+  const command = typeof inferred?.command === "string" ? inferred.command.trim() : "";
+  if (!command) return { command: null, port: s.previewPort ? Number(s.previewPort) : null, source: "none" };
+  const port = Number.isInteger(inferred?.port) ? inferred.port : s.previewPort ? Number(s.previewPort) : null;
+  return { command, port, source: "inferred" };
+}
+
+// Kill the whole process tree. A `shell:true` child on Windows is cmd.exe with
+// the real server underneath it — proc.kill() would leave the grandchild (and
+// the port) alive, so use taskkill /T there.
+function killTree(proc) {
+  if (!proc?.pid) return;
+  try {
+    if (process.platform === "win32") {
+      spawn("taskkill", ["/pid", String(proc.pid), "/T", "/F"], { stdio: "ignore" });
+    } else {
+      proc.kill("SIGTERM");
+    }
+  } catch {
+    /* already gone */
+  }
+}
+
+// Best-effort wait until something accepts a TCP connection on the port.
+function waitForPort(port, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve) => {
+    const attempt = () => {
+      const sock = net.connect({ host: "127.0.0.1", port }, () => {
+        sock.destroy();
+        resolve(true);
+      });
+      sock.on("error", () => {
+        sock.destroy();
+        if (Date.now() > deadline) resolve(false);
+        else setTimeout(attempt, 400);
+      });
+    };
+    attempt();
+  });
+}
+
+/**
+ * Start (or restart) the preview for a ticket. Returns a status object; never
+ * throws. `started:false` means nothing resolved — the card shows "no preview"
+ * and the stage goes on.
+ */
+export async function startPreview(ticketId, { cwd, signal } = {}) {
+  stopPreview(ticketId); // never two for one ticket
+
+  const { command, port, source } = await resolvePreview({ cwd, signal });
+  if (!command) return { started: false, reason: "no preview command resolved", source };
+
+  let proc;
+  try {
+    proc = spawn(command, { cwd, shell: true });
+  } catch (err) {
+    return { started: false, reason: `spawn failed: ${err.message || err}`, source };
+  }
+  proc.on("error", () => {}); // a preview that fails to launch must not crash the stage
+  proc.stdout?.on("data", () => {});
+  proc.stderr?.on("data", () => {});
+
+  const url = port ? `http://localhost:${port}` : null;
+  previews.set(ticketId, { proc, url, command, port });
+
+  const reachable = port ? await waitForPort(port) : false;
+  return { started: true, url, command, port, source, reachable };
+}
+
+export function stopPreview(ticketId) {
+  const p = previews.get(ticketId);
+  if (!p) return false;
+  killTree(p.proc);
+  previews.delete(ticketId);
+  return true;
+}
+
+export function previewInfo(ticketId) {
+  const p = previews.get(ticketId);
+  return p ? { url: p.url, command: p.command, port: p.port } : null;
+}
+
+/** Tear down every preview — used when the dashboard process shuts down. */
+export function stopAllPreviews() {
+  for (const id of [...previews.keys()]) stopPreview(id);
+}

package/src/lib/ship.js

@@ -4,13 +4,13 @@ import { hasGh, createPullRequest } from "./github.js";
 
 // Turning a finished run into a reviewable PR.
 //
-// Before this, a run ended in the Review column with a diff living in a local
+// Before this, a run ended in the Staging column with a diff living in a local
 // worktree on an unpushed branch — real work in a place nobody else could see.
 // Shipping is the step that makes it a thing a human can actually review.
 //
 // Each stage logs to the ticket, so the terminal dock narrates the push and PR
 // the same way it narrates the agent's tool calls. Every failure mode leaves
-// the ticket in `review` with the work intact: committing and pushing are
+// the ticket in `staging` with the work intact: committing and pushing are
 // worth keeping even when the PR itself can't be opened.
 
 function commitMessage(ticket) {

package/src/lib/staging.js

@@ -0,0 +1,97 @@
+import { spawn } from "node:child_process";
+import { getStaging } from "./config.js";
+import { askJson } from "./agentBackend.js";
+
+// Staging test execution. ouro runs the tests (deterministic capture) and the
+// QA agent judges the result — so the test command has to be resolved and run
+// here, not left to the agent's Bash tool.
+//
+// Resolution order: config.staging.testCommand if set, else a cheap read-only
+// agent inference from the repo (package.json scripts, CLAUDE.md, etc.). If
+// nothing resolves, the stage proceeds tests-only-absent — never a hard failure.
+
+/**
+ * Resolve the test command. Returns { command, source } where source is
+ * "config" | "inferred" | "none".
+ */
+export async function resolveTestCommand({ cwd, signal }) {
+  const configured = getStaging().testCommand;
+  if (configured) return { command: String(configured), source: "config" };
+
+  const inferred = await askJson({
+    prompt:
+      "Infer the single shell command that runs this project's automated tests, from its config (package.json scripts, Makefile, pyproject, etc.). " +
+      'Respond with ONLY JSON: {"command": string|null}. Use null if the repo has no test setup. No prose, no fences.',
+    cwd,
+    signal,
+  }).catch(() => null);
+
+  const command = typeof inferred?.command === "string" ? inferred.command.trim() : "";
+  return { command: command || null, source: command ? "inferred" : "none" };
+}
+
+/**
+ * Run a shell command, capturing output. Bounded by a timeout so a hanging
+ * suite can't wedge the stage. Never rejects — a spawn error resolves as a
+ * failed result the QA agent can read.
+ */
+export function runShell(command, { cwd, signal, timeoutMs = 10 * 60 * 1000 } = {}) {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    // shell:true so a full command string ("npm test", "pytest -q") runs as-is.
+    const proc = spawn(command, { cwd, shell: true, signal });
+
+    const timer = setTimeout(() => {
+      try {
+        proc.kill();
+      } catch {
+        /* already gone */
+      }
+    }, timeoutMs);
+
+    proc.stdout?.on("data", (d) => (stdout += d.toString()));
+    proc.stderr?.on("data", (d) => (stderr += d.toString()));
+
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ code: null, passed: false, stdout, stderr: `${stderr}${err.message || err}` });
+    });
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code, passed: code === 0, stdout, stderr });
+    });
+  });
+}
+
+// Keep only the tail — the QA agent and the card need the verdict-relevant end
+// of the output (failures, summary line), not a multi-thousand-line firehose.
+function tail(text, lines = 40) {
+  return String(text || "")
+    .trim()
+    .split("\n")
+    .slice(-lines)
+    .join("\n");
+}
+
+/**
+ * Resolve + run the tests. Returns a structured result for the card and the QA
+ * agent. `ran: false` means no command resolved — the stage goes on tests-only-
+ * absent, never failing on the absence itself.
+ */
+export async function runTests({ cwd, signal }) {
+  const { command, source } = await resolveTestCommand({ cwd, signal });
+  if (!command) {
+    return { ran: false, command: null, source, passed: null, output: "No test command resolved for this repo." };
+  }
+
+  const res = await runShell(command, { cwd, signal });
+  return {
+    ran: true,
+    command,
+    source,
+    passed: res.passed,
+    code: res.code,
+    output: tail(`${res.stdout}\n${res.stderr}`),
+  };
+}

package/src/lib/store.js

@@ -7,7 +7,12 @@ import { ticketsPath, ensureOuroDir } from "./paths.js";
 // sqlite/postgres — a JSON file + an in-memory EventEmitter for the WS layer
 // is plenty, and it means `ouro init` produces zero external dependencies.
 
-export const STATUSES = ["inbox", "triaged", "in_progress", "review", "done", "cancelled"];
+export const STATUSES = ["inbox", "analyzed", "in_progress", "staging", "done", "cancelled"];
+
+// Legacy status values from before the Analyze/Staging rename. Mapped forward on
+// load so a tickets.json written by an older ouro doesn't strand cards in a
+// column that no longer exists.
+const STATUS_MIGRATION = { triaged: "analyzed", review: "staging" };
 
 // A streaming agent emits events far faster than a board needs to persist.
 // Writes are coalesced onto a trailing timer so a chatty run costs one write
@@ -42,11 +47,30 @@ class TicketStore extends EventEmitter {
     // it to a terminal state at startup instead.
     let reconciled = 0;
     for (const ticket of this.tickets) {
+      // Forward-migrate legacy status names (triaged → analyzed, review → staging).
+      if (STATUS_MIGRATION[ticket.status]) {
+        ticket.status = STATUS_MIGRATION[ticket.status];
+        reconciled++;
+      }
       if (ticket.status === "in_progress") {
         ticket.status = "cancelled";
         ticket.cancelReason = "Dashboard stopped while this run was in flight.";
         reconciled++;
       }
+      // A read-only Analyze pass has no worktree to reconcile — it just leaves
+      // the ticket where it was. But a stranded `analyzing` flag would keep the
+      // card stuck on "Analyzing…" forever, so clear it.
+      if (ticket.analyzing) {
+        ticket.analyzing = false;
+        reconciled++;
+      }
+      // A preview server is a child of the dashboard process — it didn't survive
+      // the restart, so a stored URL now points at nothing.
+      if (ticket.previewUrl) {
+        ticket.previewUrl = null;
+        ticket.previewNote = "preview stopped when the dashboard restarted";
+        reconciled++;
+      }
     }
     // Write it back immediately. Reconciling only in memory leaves the file
     // claiming in_progress until some unrelated edit happens to flush it —
@@ -91,11 +115,24 @@ class TicketStore extends EventEmitter {
       title,
       body,
       source,
-      status: "inbox", // inbox -> triaged -> in_progress -> review -> done | cancelled
+      status: "inbox", // inbox -> analyzed -> in_progress -> staging -> done | cancelled
       mode, // "agent" | "human" — null inherits the board's default
       agentId, // which .ouro/agents/<id>.md runs this ticket
       priority,
       summary,
+      // Analyst findings — carried forward into plan/execute (Feature 1 findings
+      // passthrough) and validated by the QA gate.
+      filesLikelyAffected: [],
+      acceptanceCriteria: [],
+      analyzing: false, // transient: the read-only Analyze pass is in flight
+      // Staging stage (Feature 9).
+      testResult: null, // { ran, command, source, passed, code, output }
+      previewUrl: null, // clickable local-preview link while one is running
+      previewNote: null, // why there's no preview, when there isn't
+      qaVerdict: null, // { ready, summary, reasons, uiChange, visualMethod, questions }
+      qaAttempts: 0, // QA passes so far — the loop-stop guard escalates at 2
+      awaitingQa: false, // QA posted its verdict and is waiting on a human (popup)
+      escalated: false, // hit the loop-stop guard: a human must decide
       sessionId: null,
       log: [],
       worktree: null,
@@ -155,17 +192,28 @@ class TicketStore extends EventEmitter {
     return this.update(id, {
       status: "cancelled",
       awaitingApproval: false,
+      awaitingQa: false,
+      escalated: false,
+      analyzing: false,
       cancelReason: reason ?? "Cancelled from the dashboard.",
     });
   }
 
-  /** Back to the board as a fresh triaged ticket, keeping title/body/agent. */
+  /** Back to the board as a fresh analyzed ticket, keeping title/body/agent. */
   reopen(id) {
     const ticket = this.get(id);
     if (!ticket) return null;
     return this.update(id, {
-      status: ticket.summary ? "triaged" : "inbox",
+      status: ticket.summary ? "analyzed" : "inbox",
       awaitingApproval: false,
+      analyzing: false,
+      awaitingQa: false,
+      escalated: false,
+      testResult: null,
+      qaVerdict: null,
+      qaAttempts: 0,
+      previewUrl: null,
+      previewNote: null,
       cancelReason: null,
       diff: null,
       plan: null,