scriptonia 0.5.0 → 0.6.0

package/bin/scriptonia.mjs

@@ -155,10 +155,11 @@ function nextStep(s, plansN, recentPlan, repo, C) {
 async function add(args) {
   const cfg = activeCreds();
   const flags = parseFlags(args);
-  const files = args.filter((a) => !a.startsWith("--"));
-  if (files.length === 0) {
+  const items = args.filter((a) => !a.startsWith("--"));
+  if (items.length === 0) {
     fail(
-      'usage: scriptonia add <file...>    e.g. scriptonia add slack.txt notes.md call.vtt\n' +
+      'usage: scriptonia add <file...>            e.g. scriptonia add slack.txt notes.md call.vtt\n' +
+      '       scriptonia add "Issue #42: …"       inline signal — also analyzed against the brain → context.md\n' +
       "       flags: --source slack|ticket|sales_call|voice_note|founder_note|email|notion|github\n" +
       "              --segment enterprise|mid_market|smb|free\n" +
       "       pipe:  cat thread.txt | scriptonia add -",
@@ -166,21 +167,30 @@ async function add(args) {
   }
 
   const C = colors();
+  // A single non-file argument with whitespace is inline signal text (an issue,
+  // a pasted message). A bare word that isn't a file stays a "not found" error
+  // so typo'd filenames don't get silently ingested as one-word signals.
+  const inline = items.length === 1 && items[0] !== "-" && !fs.existsSync(items[0]) && /\s/.test(items[0]);
   let created = 0, dup = 0, failed = 0;
+  let inlineSignalId = null;
 
-  for (const file of files) {
+  for (const item of inline ? [items[0]] : items) {
     let body, ref, srcHint;
-    if (file === "-") {
+    if (inline) {
+      body = item;
+      ref = null;
+      srcHint = flags.source ?? "ticket";
+    } else if (item === "-") {
       body = fs.readFileSync(0, "utf8"); // stdin
       ref = null;
       srcHint = "founder_note";
     } else {
-      if (!fs.existsSync(file)) { console.log(`  ${C.w}skip${C.r} ${file} (not found)`); failed++; continue; }
-      body = fs.readFileSync(file, "utf8");
-      ref = `upload/${path.basename(file)}`;
-      srcHint = detectSource(file);
+      if (!fs.existsSync(item)) { console.log(`  ${C.w}skip${C.r} ${item} (not found)`); failed++; continue; }
+      body = fs.readFileSync(item, "utf8");
+      ref = `upload/${path.basename(item)}`;
+      srcHint = detectSource(item);
     }
-    if (!body.trim()) { console.log(`  ${C.w}skip${C.r} ${file} (empty)`); continue; }
+    if (!body.trim()) { console.log(`  ${C.w}skip${C.r} ${item} (empty)`); continue; }
 
     const res = await fetch(`${cfg.url}/api/ingest`, {
       method: "POST",
@@ -188,19 +198,60 @@ async function add(args) {
       body: JSON.stringify({
         source: flags.source ?? srcHint,
         body,
-        externalRef: ref,
+        // omit when absent — the API's schema rejects an explicit null
+        externalRef: ref ?? undefined,
         segment: flags.segment,
       }),
     });
     const data = await res.json().catch(() => ({}));
-    if (!res.ok) { console.log(`  ${C.w}fail${C.r} ${file} (${res.status})`); failed++; continue; }
-    if (data.status === "duplicate") { console.log(`  ${C.dim}dup ${C.r} ${file}`); dup++; }
-    else { console.log(`  ${C.g}✓${C.r}   ${file} ${C.dim}→ ${flags.source ?? srcHint}${C.r}`); created++; }
+    if (!res.ok) { console.log(`  ${C.w}fail${C.r} ${inline ? "inline signal" : item} (${res.status})`); failed++; continue; }
+    const label = inline ? `"${body.slice(0, 56)}${body.length > 56 ? "…" : ""}"` : item;
+    if (data.status === "duplicate") { console.log(`  ${C.dim}dup ${C.r} ${label}`); dup++; }
+    else { console.log(`  ${C.g}✓${C.r}   ${label} ${C.dim}→ ${flags.source ?? srcHint} · sig_${(data.signalId ?? "").slice(0, 8)}${C.r}`); created++; }
+    if (inline) inlineSignalId = data.signalId ?? null;
+
+    // Local receipt so an agent reading the brain sees what signal exists.
+    if (cfg.inited && data.signalId) {
+      writeSignalReceipt(cfg.dir, {
+        id: data.signalId,
+        source: flags.source ?? srcHint,
+        externalRef: ref,
+        segment: flags.segment ?? null,
+        preview: body.slice(0, 240),
+        status: data.status === "duplicate" ? "duplicate" : "queued_for_embedding",
+      });
+    }
   }
 
+  if (cfg.inited) appendLog(cfg.dir, "add", `${created} added, ${dup} dup, ${failed} failed${inline ? " (inline)" : ""}`);
   console.log(`\n  ${created} added${dup ? `, ${dup} already there` : ""}${failed ? `, ${failed} failed` : ""}.`);
+
+  // Inline signal = an issue. Analyze it against the brain now (the existing
+  // embedded signal + decisions) and materialize context.md.
+  if (inline && (created > 0 || dup > 0)) {
+    console.log(`  ${C.dim}Analyzing against the brain — retrieved signal · prior decisions… (~10s)${C.r}`);
+    try {
+      const qres = await fetch(`${cfg.url}/api/query`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${cfg.token}`, "content-type": "application/json" },
+        body: JSON.stringify({ query: items[0], window: "all" }),
+      });
+      const q = await qres.json();
+      if (qres.ok) {
+        const md = renderContextLive(items[0], q, cfg.project, inlineSignalId);
+        if (cfg.inited) fs.writeFileSync(path.join(cfg.dir, "context.md"), md);
+        const unresolved = (q.contradictions ?? []).length;
+        console.log(`\n  ${C.g}✓${C.r} context synthesized${cfg.inited ? ` → ${C.dim}${path.join(cfg.dir, "context.md")}${C.r}` : ""}`);
+        console.log(`  ${C.dim}${(q.sources ?? []).length} signal(s) cited${unresolved ? ` · ${C.r}${C.w}⚠ ${unresolved} contradiction(s) with prior decisions — gate is UNRESOLVED${C.r}` : ""}${C.r}`);
+        if (cfg.inited) appendLog(cfg.dir, "add", `context.md synthesized (${(q.sources ?? []).length} cited, ${unresolved} contradictions)`);
+      }
+    } catch { /* analysis is best-effort; the signal is already ingested */ }
+    console.log(`\n  ${C.b}Next:${C.r} ${C.g}scriptonia plan "${items[0].slice(0, 48)}${items[0].length > 48 ? "…" : ""}"${C.r}\n`);
+    return;
+  }
+
   if (created > 0) {
-    console.log(`  ${C.dim}The brain is enriching them now. In ~2 min:${C.r} ${C.g}scriptonia contexts${C.r}\n`);
+    console.log(`  ${C.dim}The brain is enriching them now. Then:${C.r} ${C.g}scriptonia plan "<issue>"${C.r}\n`);
   }
 }
 
@@ -290,6 +341,16 @@ async function comment(args) {
     const data = await res.json().catch(() => ({}));
     if (res.status === 404) fail(`no plan "${slug}" — generate one first: scriptonia plan "<issue>"`);
     if (!res.ok) fail(`comment failed (${res.status}): ${JSON.stringify(data).slice(0, 200)}`);
+    // Approval-chain receipt: which human note produced which plan version.
+    if (cfg.inited) {
+      const cdir = path.join(cfg.dir, "comments", "plan", slug);
+      fs.mkdirSync(cdir, { recursive: true });
+      fs.writeFileSync(
+        path.join(cdir, `v${data.version}.json`),
+        JSON.stringify({ author: flags.as ?? cfg.email, body: text, applied_in_version: data.version, at: new Date().toISOString() }, null, 2),
+      );
+      appendLog(cfg.dir, "comment", `plan/${slug} — regenerated to v${data.version}`);
+    }
     writePlan(cfg, data, flags);
     return;
   }
@@ -575,10 +636,14 @@ function activeCreds() {
   if (!g) fail("run `scriptonia login` first");
   const proj = findProjectForCwd();
   if (proj) {
+    // v0.6 brains are flat (REPO.md etc. at the project dir root); older ones
+    // used a brain/ subfolder — keep reading those until re-init.
+    const legacy = !fs.existsSync(path.join(proj.dir, "REPO.md")) && fs.existsSync(path.join(proj.dir, "brain"));
     return {
       url: g.url, email: g.email,
       token: proj.data.token, project: proj.data.name, projectId: proj.data.projectId,
-      dir: proj.dir, brainDir: path.join(proj.dir, "brain"), plansDir: path.join(proj.dir, "plans"),
+      dir: proj.dir, brainDir: legacy ? path.join(proj.dir, "brain") : proj.dir,
+      plansDir: path.join(proj.dir, "plans"),
       repoPath: proj.data.repoPath, inited: true,
     };
   }
@@ -643,8 +708,16 @@ async function init(args) {
 
   const pitch = flags.about ?? (await ask(`  In one or two sentences — what is ${name} and who is it for?\n  > `));
 
-  fs.mkdirSync(path.join(dir, "brain", "contexts"), { recursive: true });
-  fs.mkdirSync(path.join(dir, "plans"), { recursive: true });
+  // Brain structure (v0.6, flat): everything an agent needs to be grounded,
+  // as plain files. cache/ + embeddings/ intentionally absent — vectors live
+  // server-side (pgvector); writing fake index files here would be theater.
+  for (const sub of ["signals", "rules", "contexts", "plans", "comments/plan", "logs"]) {
+    fs.mkdirSync(path.join(dir, sub), { recursive: true });
+  }
+  // Migrate a legacy brain/ subfolder layout if present.
+  const legacyBrain = path.join(dir, "brain");
+  if (fs.existsSync(legacyBrain)) fs.rmSync(legacyBrain, { recursive: true, force: true });
+
   fs.writeFileSync(
     path.join(dir, "project.json"),
     JSON.stringify({ projectId, token, name, slug, repoPath, pitch: pitch || null, createdAt: new Date().toISOString() }, null, 2),
@@ -652,14 +725,18 @@ async function init(args) {
   );
   writeProjectMd(dir, scan, pitch);
   writeRepoMd(dir, scan);
+  writeAgentsBrainMd(dir, { name, pitch, stack: scan.stack }, []);
+  fs.writeFileSync(path.join(dir, ".gitignore"), "logs/\nproject.json\n");
   injectAgentsMd(cwd);
   installSkill();
+  appendLog(dir, "init", `Initialized brain for ${name} (${repoPath}) — stack: ${scan.stack}`);
 
   console.log(`\n  ${C.g}✓${C.r} Brain created for ${C.b}${name}${C.r}  ${C.dim}→ ${dir}${C.r}`);
-  console.log(`  ${C.g}✓${C.r} Scanned repo (${scan.stack})  ${C.dim}→ brain/PROJECT.md · brain/REPO.md${C.r}`);
+  console.log(`      ${C.dim}AGENTS.md · PROJECT.md · REPO.md · signals/ · rules/ · contexts/ · plans/ · comments/ · logs/${C.r}`);
+  console.log(`  ${C.g}✓${C.r} Scanned repo (${scan.stack})`);
   console.log(`  ${C.g}✓${C.r} Wrote agent instructions  ${C.dim}→ ./AGENTS.md${C.r}`);
   console.log(`\n  ${C.b}Feed it customer signal, then turn an issue into a plan:${C.r}\n`);
-  console.log(`    ${C.g}scriptonia add${C.r} feedback.txt call.vtt notes.md`);
+  console.log(`    ${C.g}scriptonia add${C.r} feedback.txt call.vtt   ${C.dim}(or:  scriptonia add "Issue #42: …")${C.r}`);
   console.log(`    ${C.g}scriptonia plan${C.r} "the issue you want to build"\n`);
 }
 
@@ -676,9 +753,22 @@ async function sync() {
   fs.mkdirSync(cdir, { recursive: true });
   for (const f of fs.readdirSync(cdir)) if (f.endsWith(".md")) fs.rmSync(path.join(cdir, f));
   for (const c of brain.contexts) fs.writeFileSync(path.join(cdir, `${c.slug}.md`), renderContextFile(c));
-  fs.writeFileSync(path.join(cfg.brainDir, "DECISIONS.md"), renderDecisions(brain.decisions));
 
-  console.log(`  ${C.g}✓${C.r} synced ${brain.contexts.length} context(s), ${brain.decisions.length} decision(s) → ${C.dim}${cfg.brainDir}${C.r}`);
+  // Decisions → machine-checkable rules/. The server enforces these during
+  // `plan` (conflicts come back ⚠ UNRESOLVED); the local copies ground agents.
+  const rdir = path.join(cfg.brainDir, "rules");
+  fs.mkdirSync(rdir, { recursive: true });
+  for (const f of fs.readdirSync(rdir)) if (f.endsWith(".rule")) fs.rmSync(path.join(rdir, f));
+  for (const d of brain.decisions) {
+    fs.writeFileSync(path.join(rdir, `${slugify(d.title)}.rule`), renderRule(d));
+  }
+
+  // Refresh the brain's master contract with the live constraint set.
+  const pj = readProjectJson(cfg.dir);
+  writeAgentsBrainMd(cfg.brainDir, { name: cfg.project, pitch: pj?.pitch ?? "", stack: null }, brain.decisions);
+
+  appendLog(cfg.dir, "sync", `${brain.contexts.length} contexts, ${brain.decisions.length} decisions → rules/`);
+  console.log(`  ${C.g}✓${C.r} synced ${brain.contexts.length} context(s) → contexts/, ${brain.decisions.length} decision(s) → rules/ ${C.dim}(${cfg.brainDir})${C.r}`);
 }
 
 // ── plan (the money command) ──────────────────────────────────
@@ -719,6 +809,10 @@ function writePlan(cfg, data, flags) {
   if (cfg.inited) {
     fs.mkdirSync(cfg.plansDir, { recursive: true });
     fs.writeFileSync(path.join(cfg.plansDir, `${data.slug}.md`), data.markdown);
+    // Live copy in the brain, so an agent grounded on the brain dir sees the
+    // current plan without knowing the slug.
+    fs.writeFileSync(path.join(cfg.brainDir, "plan.md"), data.markdown);
+    appendLog(cfg.dir, "plan", `${data.slug} v${data.version} — ${(data.sources ?? []).length} sources, ${data.contradictions ?? 0} unresolved`);
   }
   console.log(`\n  ${C.g}✓${C.r} Plan ${C.b}${data.slug}${C.r} ${C.dim}v${data.version}${C.r} → ${C.v}${out}${C.r}`);
   console.log(`  ${C.dim}${(data.sources ?? []).length} cited signal(s)${data.contradictions ? `, ${data.contradictions} unresolved contradiction(s)` : ""}${C.r}`);
@@ -799,26 +893,170 @@ function gitRemoteName(cwd) {
 // ── brain file writers ────────────────────────────────────────
 function writeProjectMd(dir, scan, pitch) {
   const md = [
+    "---",
+    `project_name: ${JSON.stringify(scan.name)}`,
+    `stack: ${JSON.stringify(scan.stack)}`,
+    scan.scripts.length ? `scripts: [${scan.scripts.join(", ")}]` : null,
+    `initialized: ${new Date().toISOString().slice(0, 10)}`,
+    "---",
+    "",
     `# ${scan.name}`,
     "",
     pitch ? `> ${pitch}` : (scan.pkgDescription ? `> ${scan.pkgDescription}` : "> (describe this product with `scriptonia init --force`)"),
     "",
     `**Stack:** ${scan.stack}`,
-    scan.scripts.length ? `**Scripts:** ${scan.scripts.join(", ")}` : "",
     scan.deps.length ? `**Key deps:** ${scan.deps.join(", ")}` : "",
     scan.entryPoints.length ? `**Entry points:** ${scan.entryPoints.join(", ")}` : "",
     "",
     scan.readmeHead ? "## From the README\n\n" + scan.readmeHead : "",
     "",
     "---",
-    "*This is the product brain. Customer signal, contexts, and decisions live alongside this file. Generated by `scriptonia init`.*",
-  ].filter((l) => l !== "").join("\n");
-  fs.writeFileSync(path.join(dir, "brain", "PROJECT.md"), md);
+    "*The product brain. Signal receipts in `signals/`, constraints in `rules/`, enriched contexts in `contexts/`, live synthesis in `context.md`, live plan in `plan.md`. Generated by `scriptonia init`.*",
+  ].filter((l) => l !== "" && l !== null).join("\n");
+  fs.writeFileSync(path.join(dir, "PROJECT.md"), md);
 }
 
 function writeRepoMd(dir, scan) {
-  fs.mkdirSync(path.join(dir, "brain"), { recursive: true });
-  fs.writeFileSync(path.join(dir, "brain", "REPO.md"), buildRepoMd(scan));
+  // v0.6 flat layout; keep writing into brain/ for pre-0.6 projects.
+  const target = fs.existsSync(path.join(dir, "brain")) && !fs.existsSync(path.join(dir, "REPO.md"))
+    ? path.join(dir, "brain")
+    : dir;
+  fs.mkdirSync(target, { recursive: true });
+  fs.writeFileSync(path.join(target, "REPO.md"), buildRepoMd(scan));
+}
+
+/**
+ * AGENTS.md — the brain's master contract. What an agent must respect when
+ * acting on this project: identity, the Scriptonia workflow, and the
+ * non-negotiable constraints (mirrored from the decisions corpus; the server
+ * enforces them during `plan`, this copy grounds agents working offline).
+ */
+function writeAgentsBrainMd(dir, meta, decisions) {
+  const L = [
+    `# AGENTS.md — ${meta.name} project brain`,
+    `# Generated by: scriptonia (refreshed on \`sync\`)`,
+    "",
+    "## 1. Identity",
+    "",
+    meta.pitch ? `${meta.pitch}` : "(run `scriptonia init --force` to describe this product)",
+    meta.stack ? `\nStack: ${meta.stack}` : "",
+    "",
+    "## 2. Workflow — non-negotiable",
+    "",
+    '1. Before building any user-facing change, run `scriptonia plan "<the issue>"`.',
+    "   It writes PLAN.md, grounded in real customer signal and checked against",
+    "   the rules below.",
+    "2. Execute PLAN.md **exactly**. Its **Non-goals** section is a fence — do not",
+    "   build past it.",
+    "3. Any constraint marked **⚠ UNRESOLVED** is an approval gate: STOP and get a",
+    '   human comment (`scriptonia comment plan/<slug> "…"`) before writing code.',
+    "4. Cite PLAN.md's `sources` signal ids in your PR description.",
+    "",
+    "## 3. Non-negotiable constraints (from the decisions corpus)",
+    "",
+  ];
+  if (decisions.length === 0) {
+    L.push("_None synced yet — run `scriptonia sync` after decisions exist. The server_", "_still enforces them during `plan` regardless._");
+  } else {
+    for (const d of decisions) {
+      L.push(`### ${d.title}${d.ref ? ` (${d.ref})` : ""}`, "", d.body, "");
+    }
+  }
+  L.push(
+    "",
+    "## 4. Approval gates",
+    "",
+    "- Overriding any constraint above requires an explicit human comment on the",
+    "  plan. The comment is recorded in `comments/plan/<slug>/` and flips the",
+    "  plan's gate to RESOLVED on regeneration.",
+    "",
+  );
+  fs.writeFileSync(path.join(dir, "AGENTS.md"), L.join("\n"));
+}
+
+/** Decision → machine-checkable rule file. */
+function renderRule(d) {
+  const id = slugify(d.title);
+  return [
+    "---",
+    `rule_id: ${JSON.stringify(id)}`,
+    `name: ${JSON.stringify(d.title)}`,
+    "severity: BLOCKING",
+    d.ref ? `source: ${JSON.stringify(d.ref)}` : null,
+    d.decidedAt ? `decided_at: ${JSON.stringify(String(d.decidedAt).slice(0, 10))}` : null,
+    "check: |",
+    ...String(d.body).split("\n").map((l) => `  ${l}`),
+    "enforcement: |",
+    "  Server-side during `scriptonia plan`: any issue conflicting with this rule",
+    "  is marked ⚠ UNRESOLVED in PLAN.md until a human comment approves the",
+    "  override (recorded in comments/plan/<slug>/).",
+    "---",
+  ].filter(Boolean).join("\n") + "\n";
+}
+
+/** Per-signal local receipt: signals/sig_<8>.json */
+function writeSignalReceipt(dir, sig) {
+  const sdir = path.join(dir, "signals");
+  fs.mkdirSync(sdir, { recursive: true });
+  fs.writeFileSync(
+    path.join(sdir, `sig_${sig.id.slice(0, 8)}.json`),
+    JSON.stringify({ ...sig, added_at: new Date().toISOString() }, null, 2),
+  );
+}
+
+/** context.md — live synthesis of the current issue against the brain. */
+function renderContextLive(issue, q, project, signalId) {
+  const cite = (ids) => (ids?.length ? `  \`[${ids.map((i) => i.slice(0, 8)).join(", ")}]\`` : "");
+  const L = [
+    `# Context — ${issue.slice(0, 90)}${issue.length > 90 ? "…" : ""}`,
+    "",
+    `> Synthesized ${new Date().toISOString().slice(0, 10)} against the **${project}** brain · ${(q.sources ?? []).length} signal(s) retrieved${signalId ? ` · this issue ingested as \`sig_${signalId.slice(0, 8)}\`` : ""}`,
+    "",
+    "## TL;DR",
+    q.tldr ?? "(no synthesis)",
+    "",
+    "## What customers actually asked for",
+  ];
+  for (const r of q.requirements ?? []) {
+    L.push(`- **${r.title}** _[${r.strength}]_ — ${r.detail}${cite(r.source_ids)}`);
+  }
+  if (!(q.requirements ?? []).length) L.push("- (no supporting signal retrieved — treat scope with caution)");
+  L.push("");
+
+  const cons = q.contradictions ?? [];
+  if (cons.length) {
+    L.push("## ⚠ CONTRADICTION GATE — UNRESOLVED");
+    for (const c of cons) L.push(`- ${c.detail} (${c.decision_ref})`);
+    L.push("", "**STATUS: ⚠ UNRESOLVED.** A human must approve the override before any plan", "built on this context is executed. `scriptonia plan` will carry this gate.", "");
+  } else {
+    L.push("## Contradiction gate", "", "✓ No conflicts with prior decisions on record.", "");
+  }
+
+  if ((q.edge_cases ?? []).length) {
+    L.push("## Edge cases — fold into any plan");
+    for (const e of q.edge_cases) L.push(`- ${e}`);
+    L.push("");
+  }
+
+  L.push("## Cited signals");
+  for (const s of q.sources ?? []) {
+    L.push(`- \`sig_${s.signal_id.slice(0, 8)}\` ${s.source}${s.ref ? ` — ${s.ref}` : ""} _(similarity ${s.similarity})_`);
+  }
+  L.push("", "---", `*Next: \`scriptonia plan "${issue.slice(0, 60)}${issue.length > 60 ? "…" : ""}"\` → PLAN.md.*`);
+  return L.join("\n");
+}
+
+function readProjectJson(dir) {
+  try { return JSON.parse(fs.readFileSync(path.join(dir, "project.json"), "utf8")); } catch { return null; }
+}
+
+/** Append to the brain's audit trail: logs/<name>.log */
+function appendLog(dir, name, msg) {
+  try {
+    const ldir = path.join(dir, "logs");
+    fs.mkdirSync(ldir, { recursive: true });
+    fs.appendFileSync(path.join(ldir, `${name}.log`), `[${new Date().toISOString()}] INFO  scriptonia.${name} — ${msg}\n`);
+  } catch { /* audit trail is best-effort */ }
 }
 
 function buildRepoMd(scan) {
@@ -844,13 +1082,6 @@ function renderContextFile(c) {
   return L.join("\n");
 }
 
-function renderDecisions(decs) {
-  if (!decs?.length) return "# Decisions\n\n(none on record)\n";
-  const L = ["# Decisions", "", "*The contradiction corpus — plans are checked against these.*", ""];
-  for (const d of decs) L.push(`## ${d.title}${d.ref ? ` (${d.ref})` : ""}`, "", d.body, "");
-  return L.join("\n");
-}
-
 // ── AGENTS.md injection (every agent reads this) ──────────────
 function injectAgentsMd(cwd) {
   const file = path.join(cwd, "AGENTS.md");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scriptonia",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Turn customer signal into executable plans your coding agent runs. Issue in, PLAN.md out.",
   "type": "module",
   "bin": {