npm - @splinterzzz/ouro - Versions diffs - 0.1.1 → 0.1.3 - Mend

@splinterzzz/ouro 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/dashboard-dist/assets/index-C21ZXjPS.css +1 -0
package/dashboard-dist/assets/index-DERJjla9.js +64 -0
package/dashboard-dist/index.html +2 -2
package/package.json +1 -1
package/src/commands/dashboard.js +2 -0
package/src/commands/init.js +168 -15
package/src/index.js +7 -1
package/src/lib/agentBackend.js +5 -1
package/src/lib/agents.js +89 -17
package/src/lib/artifacts.js +98 -0
package/src/lib/claudeCodeExec.js +60 -9
package/src/lib/codexExec.js +41 -9
package/src/lib/config.js +19 -0
package/src/lib/ouroLog.js +91 -0
package/src/lib/paths.js +8 -1
package/src/lib/preview.js +154 -0
package/src/lib/ship.js +2 -2
package/src/lib/staging.js +97 -0
package/src/lib/store.js +52 -4
package/src/server/index.js +347 -19
package/dashboard-dist/assets/index-ETSLKv6w.css +0 -1
package/dashboard-dist/assets/index-UHUWnWxM.js +0 -63

package/dashboard-dist/index.html CHANGED Viewed

@@ -9,8 +9,8 @@
          flash white around a near-black app on load. -->
     <meta name="theme-color" content="#0b0a12" />
     <title>ouro</title>
-    <script type="module" crossorigin src="/assets/index-UHUWnWxM.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-ETSLKv6w.css">
+    <script type="module" crossorigin src="/assets/index-DERJjla9.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-C21ZXjPS.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@splinterzzz/ouro",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Loop engineering CLI: repo-rooted kanban + agent loop, powered by Claude Code / Codex headless mode (no API key required).",
   "type": "module",
   "keywords": [

package/src/commands/dashboard.js CHANGED Viewed

@@ -5,6 +5,7 @@ import { isInitialized } from "../lib/paths.js";
 import { seedDefaultAgents } from "../lib/agents.js";
 import { store } from "../lib/store.js";
 import * as runs from "../lib/runs.js";
+import { stopAllPreviews } from "../lib/preview.js";
 export async function dashboardCommand(opts) {
   if (!isInitialized()) {
@@ -41,6 +42,7 @@ export async function dashboardCommand(opts) {
     closing = true;
     console.log(chalk.gray("\nShutting down — stopping agent runs…"));
     runs.cancelAll();
+    stopAllPreviews();
     store.flush();
     server.close(() => process.exit(0));
     setTimeout(() => process.exit(0), 2000).unref(); // don't hang on a stuck socket

package/src/commands/init.js CHANGED Viewed

@@ -1,30 +1,178 @@
 import fs from "node:fs";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 import chalk from "chalk";
-import { ensureOuroDir, isInitialized, agentsDir, ouroDir } from "../lib/paths.js";
+import { ensureOuroDir, isInitialized, agentsDir, ouroDir, repoRoot } from "../lib/paths.js";
 import { writeConfig } from "../lib/config.js";
 import { seedDefaultAgents } from "../lib/agents.js";
+import { generateSpec } from "../lib/agentBackend.js";
+import { listReferencedFiles } from "../lib/artifacts.js";
 // What inside .ouro/ is machine state vs. yours.
 //
-// agents/*.md and config.json are meant to be committed — that's the whole
-// point of agents-as-markdown. Everything here is either a secret (.env holds
-// a bot token), a scratch checkout, or per-machine runtime noise.
-const GITIGNORE = `# ouro runtime state — not yours to commit.
-# agents/*.md and config.json are deliberately NOT ignored: they're the
-# reviewable config this tool exists to give you.
+// agents/, context/ and config.json are meant to be committed — that's the
+// whole point of agents-as-markdown and a shared context folder. Everything
+// else is a secret (.env holds a bot token), a scratch checkout, or per-machine
+// runtime noise.
+//
+// The pattern is ignore-everything-then-unignore-safe, never the reverse: a new
+// runtime file added in a later version is ignored by default (fails safe)
+// rather than silently tracked until someone remembers to add it. The trailing
+// .env guards keep a token out even if an un-ignore above is ever loosened.
+const GITIGNORE = `# .ouro/.gitignore
+# ignore everything by default
+/*
+# un-ignore only what's safe to commit
+!agents/
+!context/
+!config.json
+!.gitignore
+# hard guard: secrets stay out even if a rule above is loosened later
 .env
-run/
-logs/
-worktrees/
-tickets.json
+context/**/*.env
 `;
+// Headers of a .ouro/.gitignore this tool has written — the current default-deny
+// form and the pre-default-deny form it replaced. An install predating the safe
+// pattern gets upgraded; a hand-authored file (neither header) is left alone.
+const OURO_GITIGNORE_SIGNATURES = ["# .ouro/.gitignore", "# ouro runtime state"];
+/**
+ * Writes/updates `.ouro/.gitignore`. Returns "created", "upgraded", "current",
+ * or "kept" (an existing file we didn't recognise as ours — never clobbered).
+ */
 function writeGitignore() {
   const file = path.join(ouroDir(), ".gitignore");
-  if (fs.existsSync(file)) return false;
+  if (fs.existsSync(file)) {
+    const current = fs.readFileSync(file, "utf-8");
+    if (current === GITIGNORE) return "current";
+    const ouroManaged = OURO_GITIGNORE_SIGNATURES.some((sig) => current.includes(sig));
+    if (!ouroManaged) return "kept";
+    fs.writeFileSync(file, GITIGNORE);
+    return "upgraded";
+  }
   fs.writeFileSync(file, GITIGNORE);
-  return true;
+  return "created";
+}
+/**
+ * The nested .ouro/.gitignore only works if no *outer* rule already excludes
+ * the directory — git won't re-include a path under a parent an ancestor
+ * .gitignore (root, or a global core.excludesFile) has excluded. So a user who
+ * added `.ouro` to their root .gitignore would get every agent/config silently
+ * untracked with no error. We can't safely edit their root file, but we can
+ * detect the shadow and tell them exactly which rule to remove.
+ *
+ * Best-effort: probes a path the nested file explicitly un-ignores. If git is
+ * absent or this isn't a repo, `git check-ignore` throws and we stay quiet.
+ */
+function warnIfOuroShadowed() {
+  // Decide ignored-ness with -q, NOT -v: `check-ignore -v` exits 0 whenever a
+  // pattern *matched*, including our own `!config.json` negation, which would
+  // false-fire on a perfectly healthy repo. Plain -q reflects the final state —
+  // it exits non-zero (throws here) when the path is ultimately un-ignored.
+  try {
+    execFileSync("git", ["check-ignore", "-q", ".ouro/config.json"], { cwd: repoRoot(), stdio: "ignore" });
+  } catch {
+    return; // not ignored (the good case), or git / not-a-repo — stay quiet
+  }
+  // Confirmed ignored — the only way, given our nested `!config.json`, is an
+  // outer blanket rule. Fetch it with -v purely for the message.
+  let match = "";
+  try {
+    match = execFileSync("git", ["check-ignore", "-v", ".ouro/config.json"], {
+      cwd: repoRoot(),
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    /* keep going — we know it's ignored, we just couldn't name the rule */
+  }
+  console.log("");
+  console.log(chalk.yellow("⚠ Your repo's git config ignores .ouro/ before .ouro/.gitignore can act on it."));
+  if (match) console.log(chalk.gray(`  Rule: ${match}`));
+  console.log(chalk.gray("  Result: agents/, context/ and config.json won't be tracked — the point of committing them is lost."));
+  console.log(chalk.gray("  Fix: remove the .ouro entry from that file. .ouro/.gitignore already keeps run/, logs/, .env and tickets.json out."));
+}
+function reportGitignore(result) {
+  if (result === "created") {
+    console.log(
+      chalk.green("✔ Wrote .ouro/.gitignore") +
+        chalk.gray(" — commits agents/, context/, config.json; ignores run/, logs/, worktrees/, .env, tickets.json")
+    );
+  } else if (result === "upgraded") {
+    console.log(chalk.green("✔ Upgraded .ouro/.gitignore to the ignore-everything-then-unignore-safe pattern"));
+  } else if (result === "kept") {
+    console.log(
+      chalk.yellow("• Left your custom .ouro/.gitignore untouched") +
+        chalk.gray(" — make sure it ignores .env and the run/, logs/, worktrees/ dirs")
+    );
+  }
+  // "current" — already up to date, nothing worth a line.
+}
+const SPEC_PROMPT = `Explore this repository read-only and write a CLAUDE.md that would help an engineer or an AI agent work in it effectively.
+Cover, based only on what the code actually shows:
+- What the project is and does, in a sentence or two.
+- The layout: the key directories and what lives in each.
+- How to install, build, test, and run it — use the real commands from package.json / scripts / config you actually find.
+- Conventions worth knowing: language, frameworks, module style, how the pieces are wired together.
+- The main entry points and the handful of files a newcomer should read first.
+Base every claim on files you actually read. Do not invent commands or features. If something isn't discoverable, omit it rather than guess.
+Output ONLY the CLAUDE.md markdown content — no preamble, no sign-off, and no code fence wrapping the whole document.`;
+// Prepended to the generated file. Reverse-engineering describes what the code
+// *currently does*, so it faithfully documents existing bugs as if intended —
+// say so, in the file itself, where whoever reads it will see it.
+const SPEC_CAVEAT = `> **Auto-generated by \`ouro init --spec\`.** Reverse-engineered from the code, so it
+> documents what the project *currently does* — including any bugs, as if they were
+> intended. A starting point to review and correct, not ground truth.
+`;
+/** Unwrap a single code fence if the model wrapped the whole document in one. */
+function cleanSpec(text) {
+  const s = String(text ?? "").trim();
+  const fenced = s.match(/^```(?:markdown|md)?\n([\s\S]*)\n```$/);
+  return (fenced ? fenced[1] : s).trim();
+}
+/**
+ * `ouro init --spec`: if the repo has no CLAUDE.md / AGENTS.md, run a read-only
+ * agent pass that explores the codebase and writes one. Best-effort and never
+ * fatal — init has already succeeded by the time this runs, so a failure here
+ * (agent unreachable, empty output) just prints a note and leaves init intact.
+ */
+async function maybeReverseEngineerSpec() {
+  const existing = listReferencedFiles();
+  if (existing.length) {
+    console.log(chalk.gray(`• --spec: ${existing.map((f) => f.path).join(", ")} already present — skipping.`));
+    return;
+  }
+  console.log(chalk.cyan("Reverse-engineering a spec from the codebase (read-only)…"));
+  try {
+    const body = cleanSpec(await generateSpec({ prompt: SPEC_PROMPT, cwd: repoRoot() }));
+    if (!body) {
+      console.log(chalk.yellow("• --spec: the pass returned nothing — skipped, init is unaffected."));
+      return;
+    }
+    fs.writeFileSync(path.join(repoRoot(), "CLAUDE.md"), SPEC_CAVEAT + body + "\n");
+    console.log(chalk.green("✔ Wrote CLAUDE.md") + chalk.gray(" — reverse-engineered from the code."));
+    console.log(
+      chalk.gray("  It describes what the code CURRENTLY does, so it documents existing bugs as if intended. Review it.")
+    );
+  } catch (err) {
+    console.log(
+      chalk.yellow(`• --spec: couldn't generate a spec (${String(err.message || err).split("\n")[0]}) — init is unaffected.`)
+    );
+  }
 }
 export async function initCommand(opts) {
@@ -34,12 +182,14 @@ export async function initCommand(opts) {
     // feature has a config but neither, and would otherwise stay broken.
     const seeded = seedDefaultAgents();
     if (seeded) console.log(chalk.green(`✔ Added ${seeded} default agents in ${agentsDir()}`));
-    if (writeGitignore()) console.log(chalk.green("✔ Added .ouro/.gitignore"));
+    reportGitignore(writeGitignore());
+    warnIfOuroShadowed();
+    if (opts?.spec) await maybeReverseEngineerSpec();
     return;
   }
   ensureOuroDir();
-  writeGitignore();
+  const gitignoreResult = writeGitignore();
   const backend = opts?.backend === "codex" ? "codex" : "claude-code";
@@ -57,6 +207,9 @@ export async function initCommand(opts) {
   console.log(chalk.green("✔ ouro initialized.") + ` Created .ouro/config.json (backend: ${backend})`);
   console.log(chalk.green(`✔ Seeded ${seeded} agents`) + ` in .ouro/agents/ — plain markdown, edit them in your editor.`);
+  reportGitignore(gitignoreResult);
+  warnIfOuroShadowed();
+  if (opts?.spec) await maybeReverseEngineerSpec();
   console.log("");
   console.log("Next steps:");
   console.log("  1. Run " + chalk.cyan("ouro start") + " — dashboard + intake agent, in the background.");

package/src/index.js CHANGED Viewed

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import { Command } from "commander";
 import chalk from "chalk";
 import { loadEnvFile } from "./lib/env.js";
@@ -10,6 +11,10 @@ import { stopCommand } from "./commands/stop.js";
 import { statusCommand } from "./commands/status.js";
 import { logsCommand } from "./commands/logs.js";
+const pkg = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+);
 // Before any command reads a token: the detached daemon has no shell to
 // inherit exports from, so `.ouro/.env` is what survives a closed terminal or
 // a reboot. A real export still wins over the file. See lib/env.js.
@@ -24,12 +29,13 @@ program
       "and agents that run on your existing Claude Code / Codex subscription.\n" +
       "No API key required."
   )
-  .version("0.1.0");
+  .version(pkg.version);
 program
   .command("init")
   .description("Configure the current repo for ouro (creates .ouro/ config + ticket store)")
   .option("--backend <backend>", "claude-code | codex", "claude-code")
+  .option("--spec", "if no CLAUDE.md / AGENTS.md exists, reverse-engineer one (read-only, best-effort)")
   .action(initCommand);
 program

package/src/lib/agentBackend.js CHANGED Viewed

@@ -32,7 +32,11 @@ function backend() {
 // Unified interface — every route calls through here instead of importing
 // codexExec/claudeCodeExec directly, so switching backends is a one-line
 // config change picked up on the next call.
-export const triage = (args) => backend().triage(args);
+export const analyze = (args) => backend().analyze(args);
+// Read-only exploration returning raw markdown. Backs `ouro init --spec`.
+export const generateSpec = (args) => backend().generateSpec(args);
+// Staging QA gate — validates the running result, returns a JSON verdict.
+export const qaReview = (args) => backend().qaReview(args);
 export const runAgent = (args) => backend().runAgent(args);
 export const planTicket = (args) => backend().planTicket(args);
 export const executeTicket = (args) => backend().executeTicket(args);

package/src/lib/agents.js CHANGED Viewed

@@ -3,6 +3,7 @@ import path from "node:path";
 import { EventEmitter } from "node:events";
 import { agentsDir, ensureOuroDir } from "./paths.js";
 import { parseFrontmatter, stringifyFrontmatter } from "./frontmatter.js";
+import { readConfig, writeConfig } from "./config.js";
 // Agents are plain markdown on disk — `.ouro/agents/<id>.md` — so they're
 // diffable, reviewable in a PR, and editable in your editor without ouro
@@ -173,8 +174,12 @@ export function deleteAgent(id) {
   }
 }
-// Shipped defaults. Written only when `.ouro/agents/` has no files at all, so
-// `ouro init` in an existing repo never resurrects an agent you deleted.
+// Shipped defaults. The original three seed only into a fresh `.ouro/agents/`
+// (an empty dir) so `ouro init` in an existing repo never resurrects one you
+// deleted. Seeds marked `topUp` were added in a later version — they're also
+// pushed by id into an already-populated install so an upgrade actually
+// delivers them; a ledger of shipped ids (config.seededAgentIds) then keeps a
+// topUp agent gone once you delete it.
 const SEEDS = [
   {
     id: "senior-engineer",
@@ -182,16 +187,22 @@ const SEEDS = [
       name: "Senior Engineer",
       glyph: "◆",
       description: "Ships production changes with minimal, well-tested diffs.",
-      model: DEFAULT_MODEL,
-      tools: ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
+      model: "opus",
+      tools: ["Read", "Grep", "Glob", "Edit", "Write", "Bash", "*"],
     },
-    body: `You are a senior engineer working in an isolated git worktree.
+    body: `You are a senior engineer working in an isolated git worktree, and you orchestrate — you do not do every edit yourself.
+Orchestration, before you touch anything:
+1. Break the ticket into subtasks. Independent ones (separate components, unrelated modules — nothing that shares state or a file with anything else in flight) are delegation candidates; anything ambiguous, architectural, or touching shared state is yours to do directly.
+2. Dispatch each independent subtask to a Task subagent rather than editing it yourself. If the Task tool exposes a model choice, request sonnet or haiku for these — applying a known, scoped change to one file is mechanical execution, not a judgment call, and doesn't need your tier. If it doesn't expose model choice, dispatch anyway — the parallelism is the primary win, the cost saving is secondary.
+3. Do the judgment work yourself: resolving the ticket's ambiguity, anything touching shared state, and the final integration once subagents land.
+4. Keep verification (typecheck/lint/tests) serial, after every subagent lands — never per-subtask, and never delegated.
 Work to these standards:
-- Read the surrounding code before you edit it. Match its idiom, naming, and comment density.
+- Read the surrounding code before you edit it (yourself, or brief a subagent to). Match its idiom, naming, and comment density.
 - Prefer the smallest diff that fully solves the ticket. No drive-by refactors.
 - Never delete or weaken a test to make something pass.
-- Run the relevant tests before you call the work done, and report what you ran.
+- Verify with the fastest check that actually proves correctness: typecheck + lint first. Only run a full production build if the ticket specifically needs to validate build output — tsc and lint already catch what a build would, slower.
 - If the ticket is ambiguous, state the assumption you made in your final message rather than guessing silently.`,
   },
   {
@@ -200,17 +211,18 @@ Work to these standards:
       name: "Bug Fixer",
       glyph: "▲",
       description: "Reproduces first, then fixes the root cause — not the symptom.",
-      model: DEFAULT_MODEL,
-      tools: ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
+      model: "opus",
+      tools: ["Read", "Grep", "Glob", "Edit", "Write", "Bash", "*"],
     },
-    body: `You are a debugging specialist working in an isolated git worktree.
+    body: `You are a debugging specialist working in an isolated git worktree, and you orchestrate — evidence-gathering delegates, diagnosis doesn't.
 Method, in order:
 1. Reproduce the bug and state the exact failing behaviour you observed.
-2. Find the root cause. Trace it — do not pattern-match a plausible-looking fix.
-3. Fix the cause, not the symptom. If the real fix is out of scope, say so explicitly.
-4. Add or extend a test that fails before your change and passes after it.
-5. Report the reproduction, the cause, and the fix separately in your final message.`,
+2. Find the root cause. Trace it — do not pattern-match a plausible-looking fix. If more than one cause is plausible, dispatch a Task subagent per hypothesis to gather evidence for or against it in parallel, rather than chasing them one at a time. If the Task tool exposes a model choice, request sonnet or haiku for these — each is a bounded, scoped investigation, not the diagnosis itself.
+3. Weigh the evidence and decide the real cause yourself — a subagent reports what it found, it does not get to conclude the diagnosis.
+4. Fix the cause, not the symptom. If the real fix is out of scope, say so explicitly.
+5. Add or extend a test that fails before your change and passes after it.
+6. Report the reproduction, the cause, and the fix separately in your final message.`,
   },
   {
     id: "reviewer",
@@ -230,17 +242,77 @@ Review for, in priority order:
 For each finding give: the file and line, what breaks, and the concrete input or state that triggers it. Skip anything you cannot substantiate — a speculative finding is worse than no finding.`,
   },
+  {
+    id: "analyst",
+    // topUp: a default added after the original three. Seeded into existing
+    // installs by id (not just brand-new repos), while a later deletion sticks.
+    topUp: true,
+    data: {
+      name: "Analyst",
+      glyph: "◇",
+      description: "Read-only. Scopes a ticket into a summary and checkable acceptance criteria.",
+      model: DEFAULT_MODEL,
+      tools: ["Read", "Grep", "Glob"],
+    },
+    body: `You are an analyst. You scope a ticket before any code is written. You have read-only tools — explore the codebase to ground your assessment, but never edit.
+Produce, in your final message:
+1. A one-paragraph summary of what the ticket actually asks for, restated so an engineer could pick it up cold.
+2. A priority — low, medium, or high — with a one-line justification.
+3. The files and modules most likely to change, from reading the code rather than guessing.
+4. Explicit acceptance criteria: a short, checkable list that defines "done". Each item must be something a test or a reviewer could mark pass or fail. These are the contract the implementation and the QA gate are both held to — vague criteria let a bad change slip through, so make them concrete and hard to game.
+If the ticket is too vague to write checkable criteria, say exactly what is missing instead of inventing plausible-sounding ones.`,
+  },
+  {
+    id: "senior-qa-engineer",
+    topUp: true,
+    data: {
+      name: "Senior QA Engineer",
+      glyph: "◎",
+      description: "Read-only. Validates the running result against acceptance criteria — ready to ship, or loop back.",
+      model: DEFAULT_MODEL,
+      tools: ["Read", "Grep", "Glob"],
+    },
+    body: `You are a senior QA engineer validating a change that has already been implemented, in an isolated git worktree. You have read-only tools — you validate, you never modify or run the code. You are an independent check, separate from code review: the reviewer reads the diff, you validate the running result against the ticket's acceptance criteria.
+Method:
+1. Take the acceptance criteria from the analysis as your definition of "ready". Validate against them, not against your own idea of done.
+2. Assess the test results ouro ran for you — what passed, what failed. Never call for weakening or deleting a test to make it pass.
+3. Read the diff. If the change touches UI (.jsx / .tsx / .css / .html and the like) and no screenshot is available, review the rendered/built HTML and the UI files with your Read tool instead — do not silently skip visual validation, substitute HTML analysis for it.
+4. Decide: ready to ship, or loop back to In Progress with specific, actionable reasons. "Not ready" with no concrete reason is not a verdict.
+Judge the running result, not the intent. A change that reads correctly but fails its acceptance criteria is not ready.`,
+  },
 ];
 export function seedDefaultAgents() {
   ensureOuroDir();
-  const existing = fs.existsSync(agentsDir()) ? fs.readdirSync(agentsDir()).filter((f) => f.endsWith(".md")) : [];
-  if (existing.length > 0) return 0;
+  const files = fs.existsSync(agentsDir()) ? fs.readdirSync(agentsDir()).filter((f) => f.endsWith(".md")) : [];
+  const isEmpty = files.length === 0;
+  const shipped = new Set(readConfig().seededAgentIds ?? []);
+  const recorded = new Set(shipped);
+  let seeded = 0;
   for (const seed of SEEDS) {
+    if (files.includes(`${seed.id}.md`)) {
+      recorded.add(seed.id); // already on disk (e.g. a pre-ledger install) — record, don't rewrite
+      continue;
+    }
+    if (shipped.has(seed.id)) continue; // shipped before and now absent = deleted on purpose
+    // Legacy seeds only on a clean slate; topUp seeds also fill an existing repo.
+    if (!isEmpty && !seed.topUp) continue;
     fs.writeFileSync(agentPath(seed.id), stringifyFrontmatter(seed.data, seed.body));
+    recorded.add(seed.id);
+    seeded++;
   }
-  return SEEDS.length;
+  // Persist the ledger only when it actually grew, so a steady-state init stays
+  // a no-op write. config.json is committed, so the record travels with the repo.
+  if (recorded.size !== shipped.size) writeConfig({ seededAgentIds: [...recorded] });
+  return seeded;
 }
 /** The agent a ticket runs as when it has no explicit assignment. */

package/src/lib/artifacts.js ADDED Viewed

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import path from "node:path";
+import { contextDir, repoRoot } from "./paths.js";
+// The artifacts system — a shared, per-run context payload.
+//
+// One folder (.ouro/context/), one manifest. ouro guarantees *discoverability*:
+// every run gets the folder path plus a manifest — the filenames, each with a
+// one-line description — injected into its prompt. The agent controls
+// *consumption*: it reads only what it judges relevant via its normal Read tool.
+// We never dump file contents into the prompt. That's the whole point — it keeps
+// context lean and lets self-describing filenames do the routing.
+//
+// Nothing is copied. Root convention files (CLAUDE.md / AGENTS.md) that the
+// underlying CLIs already auto-read stay where they are; copying CLAUDE.md into
+// the folder would just create two sources of truth that drift.
+// Root convention files, referenced in place (never copied) and surfaced in the
+// artifacts UI so "everything the agent can see" is one view.
+const REFERENCED_FILENAMES = ["CLAUDE.md", "AGENTS.md", "CLAUDE.local.md"];
+/**
+ * A one-line description for a context file: its frontmatter `description:` if
+ * present, else its first meaningful line (heading hashes stripped). Best-effort
+ * and truncated — this is a manifest label, not the file.
+ */
+function describeFile(filePath) {
+  let text;
+  try {
+    text = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return "";
+  }
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (fm) {
+    const m = fm[1].match(/^description:\s*(.+)$/m);
+    if (m) return m[1].trim().replace(/^["']|["']$/g, "").slice(0, 140);
+  }
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line || line === "---") continue;
+    return line.replace(/^#+\s*/, "").slice(0, 140);
+  }
+  return "";
+}
+/** Files dropped in .ouro/context/, each with a one-line description. */
+export function listContextFiles() {
+  let names = [];
+  try {
+    names = fs.readdirSync(contextDir()).filter((f) => !f.startsWith("."));
+  } catch {
+    return []; // no context dir yet — nothing to advertise
+  }
+  return names
+    .map((name) => {
+      const full = path.join(contextDir(), name);
+      let stat;
+      try {
+        stat = fs.statSync(full);
+      } catch {
+        return null;
+      }
+      if (!stat.isFile()) return null;
+      return { name, description: describeFile(full), size: stat.size };
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Root convention files that exist — referenced in place, not copied. */
+export function listReferencedFiles() {
+  return REFERENCED_FILENAMES.filter((name) => fs.existsSync(path.join(repoRoot(), name))).map((name) => ({
+    name,
+    path: name,
+  }));
+}
+/**
+ * The manifest string injected into a run's prompt. Manifest-only: folder path,
+ * filenames, one-line descriptions — never file contents. Returns "" when the
+ * folder is empty, so callers can concatenate unconditionally.
+ */
+export function contextManifest() {
+  const files = listContextFiles();
+  if (files.length === 0) return "";
+  const lines = [
+    "Shared context files live in .ouro/context/. They are listed here, NOT included — read any that look relevant with your Read tool:",
+  ];
+  for (const f of files) {
+    lines.push(`- .ouro/context/${f.name}${f.description ? ` — ${f.description}` : ""}`);
+  }
+  return lines.join("\n");
+}