atavi 0.1.0

package/src/commands/migrate.js

@@ -0,0 +1,68 @@
+import path from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import { ensureDirectory, pathExists, writeFileIfMissing } from "../lib/filesystem.js";
+import { parseConfigFile } from "../lib/config.js";
+import { CURRENT_WORKSPACE_SCHEMA_VERSION, scaffoldFiles } from "../lib/protocol-manifest.js";
+
+async function readOptionalConfig(configPath) {
+  if (!(await pathExists(configPath))) {
+    return null;
+  }
+
+  return readFile(configPath, "utf8");
+}
+
+export async function commandMigrate(args, io) {
+  const targetArg = args.find((arg) => !arg.startsWith("-")) ?? ".";
+  const targetDir = path.resolve(process.cwd(), targetArg);
+  const workspaceDir = path.join(targetDir, ".atavi");
+  const configPath = path.join(workspaceDir, "config.json");
+
+  if (!(await pathExists(workspaceDir))) {
+    io.stdout.write("ATAVI migrate: FAIL\n");
+    io.stdout.write(`missing workspace ${workspaceDir}\n`);
+    throw new Error("ATAVI workspace was not found.");
+  }
+
+  await ensureDirectory(workspaceDir);
+
+  const existingConfigContents = await readOptionalConfig(configPath);
+  let existingConfig = null;
+
+  if (existingConfigContents !== null) {
+    try {
+      existingConfig = parseConfigFile(existingConfigContents);
+    } catch (error) {
+      io.stdout.write("ATAVI migrate: FAIL\n");
+      io.stdout.write(`invalid JSON ${configPath}\n`);
+      throw new Error("ATAVI workspace config is not valid JSON.", { cause: error });
+    }
+  }
+
+  let created = 0;
+  for (const file of scaffoldFiles()) {
+    const destination = path.join(workspaceDir, file.relativePath);
+    const didCreate = await writeFileIfMissing(destination, file.contents);
+    if (didCreate) {
+      created += 1;
+    }
+  }
+
+  let migratedConfig = false;
+  if (existingConfig !== null && typeof existingConfig === "object" && existingConfig !== null) {
+    if (existingConfig.schemaVersion !== CURRENT_WORKSPACE_SCHEMA_VERSION) {
+      const updatedConfig = {
+        ...existingConfig,
+        schemaVersion: CURRENT_WORKSPACE_SCHEMA_VERSION
+      };
+      await writeFile(configPath, `${JSON.stringify(updatedConfig, null, 2)}\n`, "utf8");
+      migratedConfig = true;
+    }
+  }
+
+  io.stdout.write("ATAVI migrate: OK\n");
+  io.stdout.write(`workspace: ${workspaceDir}\n`);
+  io.stdout.write(`created ${created} missing file(s)\n`);
+  io.stdout.write(`schema version: ${CURRENT_WORKSPACE_SCHEMA_VERSION}\n`);
+  io.stdout.write(`config updated: ${migratedConfig ? "yes" : "no"}\n`);
+}

package/src/commands/path.js

@@ -0,0 +1,6 @@
+import { protocolRoot } from "../lib/protocol-manifest.js";
+
+export async function commandPath(io) {
+  io.stdout.write(`${protocolRoot()}\n`);
+}
+

package/src/commands/resume-check.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { parseConfigFile, validateConfig } from "../lib/config.js";
+import { parseStatusFile, validateStatus } from "../lib/status.js";
+
+async function readRequiredFile(filePath, label, io) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    io.stdout.write("ATAVI resume-check: FAIL\n");
+    io.stdout.write(`missing ${label} ${filePath}\n`);
+    throw new Error(`ATAVI workspace ${label} was not found.`, { cause: error });
+  }
+}
+
+export async function commandResumeCheck(args, io) {
+  const targetArg = args.find((arg) => !arg.startsWith("-")) ?? ".";
+  const targetDir = path.resolve(process.cwd(), targetArg);
+  const configPath = path.join(targetDir, ".atavi", "config.json");
+  const statusPath = path.join(targetDir, ".atavi", "status.md");
+
+  const [configContents, statusContents] = await Promise.all([
+    readRequiredFile(configPath, "config", io),
+    readRequiredFile(statusPath, "status", io)
+  ]);
+
+  let config;
+  try {
+    config = parseConfigFile(configContents);
+  } catch (error) {
+    io.stdout.write("ATAVI resume-check: FAIL\n");
+    io.stdout.write(`invalid JSON ${configPath}\n`);
+    throw new Error("ATAVI workspace config is not valid JSON.", { cause: error });
+  }
+
+  const configErrors = validateConfig(config);
+  const statusFields = parseStatusFile(statusContents);
+  const statusErrors = validateStatus(statusFields);
+  const errors = [
+    ...configErrors.map((error) => `config: ${error}`),
+    ...statusErrors.map((error) => `status: ${error}`)
+  ];
+
+  if (errors.length > 0) {
+    io.stdout.write("ATAVI resume-check: FAIL\n");
+    for (const error of errors) {
+      io.stdout.write(`${error}\n`);
+    }
+    throw new Error("ATAVI workspace failed resume-state validation.");
+  }
+
+  io.stdout.write("ATAVI resume-check: OK\n");
+  io.stdout.write(`config path: ${configPath}\n`);
+  io.stdout.write(`status path: ${statusPath}\n`);
+  io.stdout.write(`current_pass: ${statusFields.current_pass}\n`);
+  io.stdout.write(`current_phase: ${statusFields.current_phase}\n`);
+}

package/src/commands/validate.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { parseConfigFile, validateConfig } from "../lib/config.js";
+
+export async function commandValidate(args, io) {
+  const targetArg = args.find((arg) => !arg.startsWith("-")) ?? ".";
+  const targetDir = path.resolve(process.cwd(), targetArg);
+  const configPath = path.join(targetDir, ".atavi", "config.json");
+
+  let contents;
+  try {
+    contents = await readFile(configPath, "utf8");
+  } catch (error) {
+    io.stdout.write("ATAVI validate: FAIL\n");
+    io.stdout.write(`missing ${configPath}\n`);
+    throw new Error("ATAVI workspace config was not found.", { cause: error });
+  }
+
+  let config;
+  try {
+    config = parseConfigFile(contents);
+  } catch (error) {
+    io.stdout.write("ATAVI validate: FAIL\n");
+    io.stdout.write(`invalid JSON ${configPath}\n`);
+    throw new Error("ATAVI workspace config is not valid JSON.", { cause: error });
+  }
+
+  const errors = validateConfig(config);
+  if (errors.length > 0) {
+    io.stdout.write("ATAVI validate: FAIL\n");
+    for (const error of errors) {
+      io.stdout.write(`${error}\n`);
+    }
+    throw new Error("ATAVI workspace config failed validation.");
+  }
+
+  io.stdout.write("ATAVI validate: OK\n");
+  io.stdout.write(`config path: ${configPath}\n`);
+  io.stdout.write(`mode: ${config.mode}\n`);
+}

package/src/lib/config.js

@@ -0,0 +1,62 @@
+const ALLOWED_MODES = new Set(["full", "scout", "theorist", "vision", "audit"]);
+const REQUIRED_FULL_MODE_AGENTS = ["theorist", "experimentalist", "scout"];
+const SUPPORTED_MEMORY_SCOPES = new Set(["project"]);
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function validatePositiveInteger(value, fieldName, errors) {
+  if (!Number.isInteger(value) || value <= 0) {
+    errors.push(`${fieldName} must be a positive integer`);
+  }
+}
+
+export function parseConfigFile(contents) {
+  return JSON.parse(contents);
+}
+
+export function validateConfig(config) {
+  const errors = [];
+
+  if (!isPlainObject(config)) {
+    return ["config must be a JSON object"];
+  }
+
+  if (!ALLOWED_MODES.has(config.mode)) {
+    errors.push(`mode must be one of: ${Array.from(ALLOWED_MODES).join(", ")}`);
+  }
+
+  validatePositiveInteger(config.maxPasses, "maxPasses", errors);
+  validatePositiveInteger(config.maxExperiments, "maxExperiments", errors);
+
+  if (typeof config.convergenceThreshold !== "number" || config.convergenceThreshold <= 0 || config.convergenceThreshold > 1) {
+    errors.push("convergenceThreshold must be a number greater than 0 and less than or equal to 1");
+  }
+
+  if (!Array.isArray(config.agents) || config.agents.length === 0 || config.agents.some((agent) => typeof agent !== "string" || agent.length === 0)) {
+    errors.push("agents must be a non-empty array of strings");
+  }
+
+  if (config.mode === "full" && Array.isArray(config.agents)) {
+    for (const agent of REQUIRED_FULL_MODE_AGENTS) {
+      if (!config.agents.includes(agent)) {
+        errors.push(`full mode must include agent: ${agent}`);
+      }
+    }
+  }
+
+  if (!isPlainObject(config.memory)) {
+    errors.push("memory must be an object");
+  } else {
+    if (typeof config.memory.enabled !== "boolean") {
+      errors.push("memory.enabled must be a boolean");
+    }
+
+    if (!SUPPORTED_MEMORY_SCOPES.has(config.memory.scope)) {
+      errors.push(`memory.scope must be one of: ${Array.from(SUPPORTED_MEMORY_SCOPES).join(", ")}`);
+    }
+  }
+
+  return errors;
+}

package/src/lib/filesystem.js

@@ -0,0 +1,27 @@
+import { mkdir, access, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+
+export async function ensureDirectory(directoryPath) {
+  await mkdir(directoryPath, { recursive: true });
+}
+
+export async function pathExists(filePath) {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function writeFileIfMissing(filePath, contents) {
+  if (await pathExists(filePath)) {
+    return false;
+  }
+
+  await ensureDirectory(path.dirname(filePath));
+  await writeFile(filePath, contents, "utf8");
+  return true;
+}
+

package/src/lib/memory.js

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { cp, mkdir, readdir } from "node:fs/promises";
+import { pathExists } from "./filesystem.js";
+
+async function walkFiles(rootDir, relativeDir = "") {
+  const currentDir = path.join(rootDir, relativeDir);
+  const entries = await readdir(currentDir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const entryRelativePath = path.join(relativeDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walkFiles(rootDir, entryRelativePath)));
+      continue;
+    }
+
+    files.push(entryRelativePath);
+  }
+
+  return files;
+}
+
+export async function resolveMemoryDirectory(inputPath) {
+  const directMemoryDir = path.resolve(inputPath);
+  if (await pathExists(directMemoryDir)) {
+    const maybeWorkspaceMemory = path.join(directMemoryDir, ".atavi", "memory");
+    if (await pathExists(maybeWorkspaceMemory)) {
+      return maybeWorkspaceMemory;
+    }
+  }
+
+  const workspaceMemoryDir = path.join(path.resolve(inputPath), ".atavi", "memory");
+  if (await pathExists(workspaceMemoryDir)) {
+    return workspaceMemoryDir;
+  }
+
+  if (await pathExists(directMemoryDir)) {
+    return directMemoryDir;
+  }
+
+  return null;
+}
+
+export async function exportMemory(sourceDir, outputDir) {
+  await mkdir(outputDir, { recursive: true });
+  await cp(sourceDir, outputDir, { recursive: true, force: true });
+  const files = await walkFiles(outputDir);
+  return {
+    exportedFiles: files.length
+  };
+}
+
+export async function importMemory(sourceDir, targetDir) {
+  const files = await walkFiles(sourceDir);
+  let importedFiles = 0;
+  let skippedFiles = 0;
+
+  for (const relativePath of files) {
+    const sourcePath = path.join(sourceDir, relativePath);
+    const destinationPath = path.join(targetDir, relativePath);
+    if (await pathExists(destinationPath)) {
+      skippedFiles += 1;
+      continue;
+    }
+
+    await mkdir(path.dirname(destinationPath), { recursive: true });
+    await cp(sourcePath, destinationPath, { force: false });
+    importedFiles += 1;
+  }
+
+  return {
+    importedFiles,
+    skippedFiles
+  };
+}

package/src/lib/protocol-manifest.js

@@ -0,0 +1,318 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, "..", "..");
+
+const PROTOCOL_FILES = [
+  "protocol/ATAVI.md",
+  "protocol/agents/theorist.md",
+  "protocol/agents/experimentalist.md",
+  "protocol/agents/scout.md",
+  "protocol/agents/critic.md",
+  "protocol/agents/synthesist.md"
+];
+
+const TEMPLATE_FILES = [
+  "templates/research-brief.md",
+  "templates/pod.md",
+  "templates/cpr.md",
+  "templates/output-report.md"
+];
+
+export const CURRENT_WORKSPACE_SCHEMA_VERSION = 1;
+
+export function protocolRoot() {
+  return ROOT;
+}
+
+export function protocolFiles() {
+  return [...PROTOCOL_FILES];
+}
+
+export function templateFiles() {
+  return [...TEMPLATE_FILES];
+}
+
+export function scaffoldFiles() {
+  return [
+    {
+      relativePath: "brief.md",
+      contents: `# ATAVI Research Brief
+
+Status: draft
+Mode: FULL
+Source spec:
+Thesis:
+Domain:
+Constraints:
+- 
+Novelty sources:
+- 
+Selected agents:
+- Theorist
+- Experimentalist
+- Scout
+`
+    },
+    {
+      relativePath: "config.json",
+      contents: `${JSON.stringify(
+        {
+          schemaVersion: CURRENT_WORKSPACE_SCHEMA_VERSION,
+          mode: "full",
+          maxPasses: 4,
+          maxExperiments: 5,
+          convergenceThreshold: 0.7,
+          agents: ["theorist", "experimentalist", "scout"],
+          memory: {
+            enabled: true,
+            scope: "project"
+          }
+        },
+        null,
+        2
+      )}\n`
+    },
+    {
+      relativePath: "status.md",
+      contents: `# ATAVI Status
+
+run_status: initialized
+current_pass: 0
+current_phase: not_started
+convergence_score: n/a
+blocking_concerns: none
+token_estimate: unknown
+last_updated: pending
+`
+    },
+    {
+      relativePath: "conflicts.md",
+      contents: `# ATAVI Conflict List
+
+The host AI records active conflicts, unresolved disagreements, and blocking
+tradeoffs here during synthesis.
+`
+    },
+    {
+      relativePath: "kill-log.md",
+      contents: `# ATAVI Kill Log
+
+Record rejected claims and experiments here with explicit reasons, evidence, and
+novelty verdicts when applicable.
+`
+    },
+    {
+      relativePath: "run-log.md",
+      contents: `# ATAVI Run Log
+
+Use this file for the pass-by-pass process log, including POD completion, CPR
+exchange, synthesis updates, convergence scores, and decision gates.
+`
+    },
+    {
+      relativePath: "ATAVI-REPORT.md",
+      contents: `# ATAVI Report
+
+This file is populated by the host AI after a run completes.
+`
+    },
+    {
+      relativePath: "pass-1/README.md",
+      contents: `# ATAVI Pass 1
+
+Place independent agent outputs in this directory as:
+
+- theorist-pod.md
+- experimentalist-pod.md
+- scout-pod.md
+- critic-pod.md
+- synthesist-pod.md
+
+The host AI also writes:
+
+- synthesis.md
+- decision.md
+`
+    },
+    {
+      relativePath: "pass-1/synthesis.md",
+      contents: `# ATAVI Pass 1 Synthesis
+
+Summarize accepted registry updates, active conflicts, novelty findings, and
+convergence movement for this pass.
+`
+    },
+    {
+      relativePath: "pass-1/decision.md",
+      contents: `# ATAVI Pass 1 Decision
+
+Record the decision gate outcome for this pass: terminate, continue, or
+escalate, with the rationale and any blocking concerns.
+`
+    },
+    {
+      relativePath: "pass-1/cross-pollination/README.md",
+      contents: `# ATAVI Cross-Pollination
+
+Place CPR outputs in this directory as:
+
+- theorist-cpr.md
+- experimentalist-cpr.md
+- scout-cpr.md
+- critic-cpr.md
+- synthesist-cpr.md
+`
+    },
+    {
+      relativePath: "registries/claims.md",
+      contents: `# Claim Registry
+
+| Claim ID | Status | Metric | Evidence For | Evidence Against |
+| --- | --- | --- | --- | --- |
+`
+    },
+    {
+      relativePath: "registries/experiments.md",
+      contents: `# Experiment Ledger
+
+| Experiment ID | Status | Claims Tested | Novelty Verdict | Information Gain |
+| --- | --- | --- | --- | --- |
+`
+    },
+    {
+      relativePath: "registries/prior-art.md",
+      contents: `# Prior Art Registry
+
+| Source | Type | Relevance Tags | Conceptual Overlap | Methodological Overlap | Empirical Overlap |
+| --- | --- | --- | --- | --- | --- |
+`
+    },
+    {
+      relativePath: "memory/README.md",
+      contents: `# ATAVI Memory
+
+This directory stores persistent prior art cache entries, kill archive records,
+claim patterns, convergence history, and strategy insights for related runs.
+
+Each memory entry should be written as a markdown file in the relevant bucket.
+Use these governance fields consistently:
+
+- Domain:
+- Keywords:
+- Confidence:
+- Expires:
+- Contradicts:
+
+The host AI writes reusable memory exports into these buckets after a run
+finishes. When new evidence contradicts an older memory, create the new entry
+and link the contradiction explicitly rather than mutating history silently.
+`
+    },
+    {
+      relativePath: "memory/prior-art-cache/README.md",
+      contents: `# Prior Art Cache
+
+Store reusable novelty-search findings, source summaries, and scoped retrieval
+metadata here for future ATAVI runs.
+
+Suggested entry format: one file per source or source cluster.
+
+- Source:
+- Retrieved:
+- Domain:
+- Keywords:
+- Confidence:
+- Expires:
+- Contradicts:
+- Summary:
+- Relevance:
+- Reuse Notes:
+`
+    },
+    {
+      relativePath: "memory/kill-archive/README.md",
+      contents: `# Kill Archive
+
+Record rejected claims and experiments here, including the evidence or novelty
+verdict that killed them.
+
+Suggested entry format: one file per rejected claim or experiment.
+
+- Killed Item:
+- Item Type:
+- Date:
+- Domain:
+- Keywords:
+- Confidence:
+- Contradicts:
+- Kill Reason:
+- Evidence:
+- Reversal Condition:
+`
+    },
+    {
+      relativePath: "memory/claim-patterns/README.md",
+      contents: `# Claim Patterns
+
+Capture recurring claim structures, failure modes, and useful formalization
+patterns that can accelerate future theorist passes.
+
+Suggested entry format: one file per reusable pattern.
+
+- Pattern Name:
+- Domain:
+- Keywords:
+- Confidence:
+- Expires:
+- Contradicts:
+- Pattern Description:
+- Common Failure Mode:
+- Reuse Guidance:
+`
+    },
+    {
+      relativePath: "memory/convergence-history/README.md",
+      contents: `# Convergence History
+
+Track prior run outcomes, convergence scores, and pass-level decision patterns
+so future runs can detect repetition and premature agreement.
+
+Suggested entry format: one file per completed run.
+
+- Run ID:
+- Domain:
+- Keywords:
+- Confidence:
+- Started:
+- Finished:
+- Final Convergence Score:
+- Contradicts:
+- Outcome Summary:
+- Repeated Failure Signals:
+`
+    },
+    {
+      relativePath: "memory/strategy-insights/README.md",
+      contents: `# Strategy Insights
+
+Store durable heuristics about search strategy, evaluation design, and
+cross-domain synthesis that proved useful across runs.
+
+Suggested entry format: one file per durable heuristic.
+
+- Insight Name:
+- Domain:
+- Keywords:
+- Confidence:
+- Expires:
+- Contradicts:
+- Insight:
+- Evidence:
+- Applicability:
+`
+    }
+  ];
+}