atavi 0.1.0

package/TESTING.md

@@ -0,0 +1,68 @@
+# Testing
+
+ATAVI needs a package-level test strategy, not just command smoke tests.
+
+## Test layers
+
+### Layer 1: Manifest integrity
+
+Goal: fail fast if the shipped package stops containing required protocol or
+template files.
+
+Current coverage:
+
+- `scripts/check-manifest.js`
+- `doctor` command tests
+
+### Layer 2: CLI contract
+
+Goal: verify the user-facing package commands keep working.
+
+Current coverage:
+
+- `--path`
+- `init`
+- `doctor`
+- `validate`
+- `resume-check`
+
+### Layer 3: Scaffold contract
+
+Goal: verify `.atavi/` contains the exact files a host AI expects.
+
+Current coverage:
+
+- scaffold file existence
+- idempotent init behavior
+- registry and report placeholders
+- explicit memory bucket scaffolding
+- pass and log placeholder scaffolding
+- snapshot coverage for scaffolded markdown
+- deeper memory layout coverage
+- host compatibility coverage for Codex, Claude, and Gemini guidance
+
+## Planned deepening inside this repo
+
+The product is all-or-nothing in terms of quality bar, so the test plan should
+grow toward:
+
+- config schema validation tests
+- snapshot tests for scaffolded markdown files
+- deeper resume-state tests around `status.md` and `config.json`
+- memory layout tests
+- host compatibility tests for Codex / Claude / Gemini loading patterns
+
+## Run commands
+
+```bash
+node scripts/check-manifest.js
+node test/run-all.js
+```
+
+## CI expectation
+
+CI must stop merges that:
+
+- remove a packaged asset
+- break a top-level command
+- change scaffold output unintentionally

package/bin/atavi.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.js";
+
+runCli(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+});
+

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "atavi",
+  "version": "0.1.0",
+  "description": "Host-agnostic multi-agent iterative research refinement protocol.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/mechramc/Atavi#readme",
+  "bugs": {
+    "url": "https://github.com/mechramc/Atavi/issues"
+  },
+  "bin": "bin/atavi.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "protocol/",
+    "templates/",
+    "README.md",
+    "HOSTS.md",
+    "ARCHITECTURE.md",
+    "CONTRIBUTING.md",
+    "TESTING.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node test/run-all.js",
+    "test:watch": "node --watch test/run-all.js",
+    "lint": "node --check bin/atavi.js && node --check src/cli.js && node --check src/commands/init.js && node --check src/commands/migrate.js && node --check src/commands/memory-export.js && node --check src/commands/memory-import.js && node --check src/commands/doctor.js && node --check src/commands/path.js && node --check src/commands/validate.js && node --check src/commands/resume-check.js && node --check src/lib/filesystem.js && node --check src/lib/protocol-manifest.js && node --check src/lib/config.js && node --check src/lib/status.js && node --check src/lib/memory.js",
+    "check": "node scripts/check-manifest.js",
+    "check:release": "node scripts/check-release-surface.js",
+    "ci": "node scripts/check-manifest.js && node scripts/check-release-surface.js && node test/run-all.js"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "research",
+    "cli",
+    "protocol",
+    "orchestration"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mechramc/Atavi.git"
+  }
+}

package/protocol/ATAVI.md

@@ -0,0 +1,149 @@
+# ATAVI
+
+ATAVI is a host-agnostic multi-agent iterative research refinement protocol.
+The package does not run the research loop itself. It ships the protocol, agent
+contracts, templates, and scaffold helpers that a host AI can execute.
+
+## Core Position
+
+- ATAVI is a protocol, not a daemon-backed application.
+- The host AI is the orchestrator.
+- Novelty verification is mandatory before any experiment survives.
+- Cross-pollination is mandatory on every pass.
+- Every decision must be inspectable through persistent artifacts.
+
+## Modes
+
+### Full
+
+Run the complete refinement loop with adaptive agent selection, convergence
+tracking, final report generation, and persistent memory updates.
+
+### Scout
+
+Run novelty search only. Produce a Prior Art Registry and verdicts for claims
+or experiments without generating new experimental design work.
+
+### Theorist
+
+Formalize a thesis into falsifiable claims, metrics, assumptions, and limits.
+
+### Vision
+
+Challenge the framing before the loop starts. Produce a Reimagination Brief
+that argues for the original direction, a stronger direction, or a hybrid.
+
+### Audit
+
+Review a product or system and produce a completion summary that covers
+architecture gaps, security issues, edge cases, tests, observability, and
+deployment risk.
+
+## Adaptive Agent Selection
+
+ATAVI always includes:
+
+- Theorist
+- Experimentalist
+- Scout
+
+ATAVI conditionally adds:
+
+- Critic when cost of failure is high, work is irreversible, or the novelty
+  landscape is crowded
+- Synthesist when the problem spans multiple domains or adjacent disciplines
+
+## Run Lifecycle
+
+1. Detect an ATAVI invocation inside the host environment.
+2. Discover the input spec, codebase, or product documents.
+3. Extract and confirm a research brief.
+4. Create a local `.atavi/` workspace.
+5. Execute the multi-pass refinement loop.
+6. Compile `ATAVI-REPORT.md`.
+7. Persist reusable memory artifacts for future runs.
+
+## Refinement Loop
+
+Each pass runs in four ordered phases.
+
+### Phase 1: Independent Work
+
+Each agent writes a POD to `.atavi/pass-N/[agent]-pod.md`.
+
+### Phase 2: Cross-Pollination
+
+Each agent reads the other PODs and writes a CPR to
+`.atavi/pass-N/cross-pollination/[agent]-cpr.md`.
+
+### Phase 3: Synthesis
+
+The host AI updates the Claim Registry, Experiment Ledger, Prior Art Registry,
+conflict list, and convergence score. The host also writes a pass summary to
+`.atavi/pass-N/synthesis.md`.
+
+### Phase 4: Decision Gate
+
+The host AI either terminates, continues, or escalates to the researcher based
+on convergence, blocking concerns, and surviving experiments. The pass outcome
+is written to `.atavi/pass-N/decision.md`, and cross-pass state remains visible
+in `.atavi/status.md` and `.atavi/run-log.md`.
+
+## Novelty Gate
+
+The Scout performs structured novelty search on every active claim and active
+experiment. Verdicts are:
+
+- `NOVEL`
+- `PARTIAL`
+- `DUPLICATE`
+- `SUPERSEDED`
+
+Duplicate or superseded experiments are killed unless the Experimentalist
+supplies a concrete methodological delta and the Scout re-verifies it.
+
+Claim-level novelty evidence is recorded in `.atavi/registries/prior-art.md`.
+Experiment-level novelty verdicts are recorded in
+`.atavi/registries/experiments.md` and summarized in `.atavi/pass-N/synthesis.md`.
+
+## Convergence
+
+Agents vote on surviving experiments using:
+
+- `STRONG_YES`
+- `YES`
+- `WEAK_YES`
+- `NO`
+
+ATAVI converges when the convergence threshold is met for two consecutive
+passes. If perfect agreement happens too early, the host must force an
+adversarial pass to avoid a coherence trap.
+
+## Persistent Memory
+
+ATAVI stores:
+
+- prior art cache
+- kill archive
+- claim patterns
+- convergence history
+- strategy insights
+
+Memories are scoped by domain and keywords, weighted by confidence, expired
+when stale, and corrected when contradicted by new evidence.
+
+Reusable memory exports are written into `.atavi/memory/` after a run, using
+the bucketed directories for prior art cache, kill archive, claim patterns,
+convergence history, and strategy insights.
+
+## Output Contract
+
+The final report must include:
+
+- completion summary
+- executive summary
+- ranked recommended experiments
+- rejected experiments / kill log
+- final claim registry
+- final prior art registry
+- full process log

package/protocol/agents/critic.md

@@ -0,0 +1,19 @@
+# Critic
+
+## Mandate
+
+Stress-test the run adversarially when the cost of being wrong is high or the
+landscape is crowded.
+
+## Responsibilities
+
+- Attempt to falsify claims.
+- Expose confounds and brittle assumptions.
+- Challenge weak differentiation stories.
+- Raise blocking concerns when the run is drifting into self-confirmation.
+
+## Constraints
+
+- Do not replace the Theorist or Experimentalist.
+- Every criticism must be concrete, testable, and written for action.
+

package/protocol/agents/experimentalist.md

@@ -0,0 +1,30 @@
+# Experimentalist
+
+## Mandate
+
+Design the experiments that reduce uncertainty about the thesis.
+
+## Responsibilities
+
+- Propose experiments for the current claim set.
+- Define variables, controls, runtime, feasibility, and failure criteria.
+- Rank experiments by information gain.
+- Respond to Scout novelty verdicts with either differentiation or rejection.
+- Design ablations that isolate causal mechanisms.
+
+## Constraints
+
+- Do not redefine claims or metrics directly.
+- Every experiment needs a pre-registered expected outcome.
+- Every infeasible or low-value experiment must be explicitly killed.
+
+## Output
+
+Write a POD containing:
+
+- status summary
+- active experiments
+- killed experiments
+- requests to other agents
+- confidence scores
+

package/protocol/agents/scout.md

@@ -0,0 +1,34 @@
+# Scout
+
+## Mandate
+
+Protect the run from reinventing prior work and missing decisive outside
+evidence.
+
+## Responsibilities
+
+- Search the web and domain-specific sources for every active claim.
+- Search the web and domain-specific sources for every active experiment.
+- Log search queries and top findings.
+- Issue `NOVEL`, `PARTIAL`, `DUPLICATE`, or `SUPERSEDED` verdicts.
+- Surface adjacent work that could strengthen or redirect the run.
+
+## Constraints
+
+- Web search is non-negotiable.
+- At least three distinct queries per claim and two per experiment.
+- Do not modify claims or propose experiments.
+- A `DUPLICATE` or `SUPERSEDED` verdict kills an experiment unless a concrete
+  methodological delta is re-verified.
+
+## Output
+
+Write a POD containing:
+
+- status summary
+- prior art findings
+- novelty verdicts
+- killed items
+- requests to other agents
+- confidence scores
+

package/protocol/agents/synthesist.md

@@ -0,0 +1,19 @@
+# Synthesist
+
+## Mandate
+
+Find useful analogies, methods, and literature from adjacent domains when the
+problem is cross-disciplinary.
+
+## Responsibilities
+
+- Surface methods from adjacent domains.
+- Identify vocabulary mismatches that hide relevant prior art.
+- Suggest productive cross-domain bridges for the Experimentalist and Theorist.
+
+## Constraints
+
+- Do not own the novelty gate.
+- Do not directly propose final experiments without routing through the
+  Experimentalist.
+

package/protocol/agents/theorist.md

@@ -0,0 +1,31 @@
+# Theorist
+
+## Mandate
+
+Own the theoretical framework. Convert a thesis into falsifiable claims,
+metrics, assumptions, and limits.
+
+## Responsibilities
+
+- Decompose the thesis into discrete claims.
+- Define metrics for each claim.
+- Surface hidden assumptions.
+- Reject experiments that do not actually test the stated claims.
+- Revise claims when Scout evidence narrows or reframes the thesis.
+
+## Constraints
+
+- Do not propose experiments directly.
+- Flag tautologies, already-proven claims, and untestable claims.
+- Maintain a structured Claim Registry update in every pass.
+
+## Output
+
+Write a POD containing:
+
+- status summary
+- active claims
+- killed claims
+- requests to other agents
+- confidence scores
+

package/src/cli.js

@@ -0,0 +1,98 @@
+import { commandDoctor } from "./commands/doctor.js";
+import { commandInit } from "./commands/init.js";
+import { commandMemoryExport } from "./commands/memory-export.js";
+import { commandMemoryImport } from "./commands/memory-import.js";
+import { commandMigrate } from "./commands/migrate.js";
+import { commandPath } from "./commands/path.js";
+import { commandResumeCheck } from "./commands/resume-check.js";
+import { commandValidate } from "./commands/validate.js";
+
+const VERSION = "0.1.0";
+
+function helpText() {
+  return `atavi
+
+Host-agnostic multi-agent iterative research refinement protocol.
+
+Usage:
+  atavi --help
+  atavi --version
+  atavi --path
+  atavi init [target]
+  atavi migrate [target]
+  atavi memory-export [target] [output]
+  atavi memory-import <source> [target]
+  atavi doctor
+  atavi validate [target]
+  atavi resume-check [target]
+
+Commands:
+  --path      Print the absolute path to the packaged protocol directory.
+  init        Scaffold a .atavi workspace in the target directory.
+  migrate     Add missing scaffold files and schema metadata to an existing workspace.
+  memory-export Copy `.atavi/memory` to an export directory.
+  memory-import Copy memory files into `.atavi/memory` without overwriting existing entries.
+  doctor      Verify packaged protocol files and basic host prerequisites.
+  validate    Validate the scaffolded .atavi/config.json contract.
+  resume-check Validate `.atavi/config.json` and `.atavi/status.md` for resume safety.
+
+Notes:
+  atavi is intentionally thin. The host AI runs the protocol.
+  This package ships the protocol, agent role files, templates, and scaffold helpers.`;
+}
+
+export async function runCli(argv, io = process) {
+  const [command, ...rest] = argv;
+
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    io.stdout.write(`${helpText()}\n`);
+    return;
+  }
+
+  if (command === "--version" || command === "-v" || command === "version") {
+    io.stdout.write(`${VERSION}\n`);
+    return;
+  }
+
+  if (command === "--path" || command === "path") {
+    await commandPath(io);
+    return;
+  }
+
+  if (command === "init") {
+    await commandInit(rest, io);
+    return;
+  }
+
+  if (command === "doctor") {
+    await commandDoctor(io);
+    return;
+  }
+
+  if (command === "memory-export") {
+    await commandMemoryExport(rest, io);
+    return;
+  }
+
+  if (command === "memory-import") {
+    await commandMemoryImport(rest, io);
+    return;
+  }
+
+  if (command === "migrate") {
+    await commandMigrate(rest, io);
+    return;
+  }
+
+  if (command === "validate") {
+    await commandValidate(rest, io);
+    return;
+  }
+
+  if (command === "resume-check") {
+    await commandResumeCheck(rest, io);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}

package/src/commands/doctor.js

@@ -0,0 +1,39 @@
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { protocolFiles, protocolRoot, templateFiles } from "../lib/protocol-manifest.js";
+
+async function canRead(filePath) {
+  try {
+    await access(filePath, constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function commandDoctor(io) {
+  const root = protocolRoot();
+  const required = [...protocolFiles(), ...templateFiles()].map((relativePath) => path.join(root, relativePath));
+  const missing = [];
+
+  for (const filePath of required) {
+    if (!(await canRead(filePath))) {
+      missing.push(filePath);
+    }
+  }
+
+  if (missing.length > 0) {
+    io.stdout.write("ATAVI doctor: FAIL\n");
+    for (const filePath of missing) {
+      io.stdout.write(`missing ${filePath}\n`);
+    }
+    throw new Error("Packaged protocol is incomplete.");
+  }
+
+  io.stdout.write("ATAVI doctor: OK\n");
+  io.stdout.write(`protocol root: ${root}\n`);
+  io.stdout.write("required files: present\n");
+  io.stdout.write("host requirement: your AI environment must support file I/O and web search for Scout runs\n");
+}
+

package/src/commands/init.js

@@ -0,0 +1,26 @@
+import path from "node:path";
+import { ensureDirectory, pathExists, writeFileIfMissing } from "../lib/filesystem.js";
+import { scaffoldFiles } from "../lib/protocol-manifest.js";
+
+export async function commandInit(args, io) {
+  const targetArg = args.find((arg) => !arg.startsWith("-")) ?? ".";
+  const targetDir = path.resolve(process.cwd(), targetArg);
+  const workspaceDir = path.join(targetDir, ".atavi");
+
+  await ensureDirectory(workspaceDir);
+
+  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;
+    }
+  }
+
+  const status = (await pathExists(path.join(workspaceDir, "status.md"))) ? "ready" : "incomplete";
+  io.stdout.write(`Scaffolded ${workspaceDir}\n`);
+  io.stdout.write(`Created ${created} new file(s). Workspace status: ${status}.\n`);
+}
+

package/src/commands/memory-export.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { exportMemory, resolveMemoryDirectory } from "../lib/memory.js";
+
+export async function commandMemoryExport(args, io) {
+  const targetArg = args.find((arg) => !arg.startsWith("-")) ?? ".";
+  const outputArg = args.filter((arg) => !arg.startsWith("-"))[1] ?? path.join(targetArg, ".atavi", "exports", "memory");
+  const sourceMemoryDir = await resolveMemoryDirectory(targetArg);
+
+  if (!sourceMemoryDir) {
+    io.stdout.write("ATAVI memory-export: FAIL\n");
+    io.stdout.write(`missing memory ${path.resolve(targetArg)}\n`);
+    throw new Error("ATAVI memory directory was not found.");
+  }
+
+  const outputDir = path.resolve(outputArg);
+  const result = await exportMemory(sourceMemoryDir, outputDir);
+
+  io.stdout.write("ATAVI memory-export: OK\n");
+  io.stdout.write(`source: ${sourceMemoryDir}\n`);
+  io.stdout.write(`output: ${outputDir}\n`);
+  io.stdout.write(`exported files: ${result.exportedFiles}\n`);
+}

package/src/commands/memory-import.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { mkdir } from "node:fs/promises";
+import { importMemory, resolveMemoryDirectory } from "../lib/memory.js";
+
+export async function commandMemoryImport(args, io) {
+  const positionalArgs = args.filter((arg) => !arg.startsWith("-"));
+  const sourceArg = positionalArgs[0];
+  const targetArg = positionalArgs[1] ?? ".";
+
+  if (!sourceArg) {
+    throw new Error("memory-import requires a source path");
+  }
+
+  const sourceMemoryDir = await resolveMemoryDirectory(sourceArg);
+  if (!sourceMemoryDir) {
+    io.stdout.write("ATAVI memory-import: FAIL\n");
+    io.stdout.write(`missing memory ${path.resolve(sourceArg)}\n`);
+    throw new Error("ATAVI source memory directory was not found.");
+  }
+
+  const targetMemoryDir = path.join(path.resolve(targetArg), ".atavi", "memory");
+  await mkdir(targetMemoryDir, { recursive: true });
+
+  const result = await importMemory(sourceMemoryDir, targetMemoryDir);
+
+  io.stdout.write("ATAVI memory-import: OK\n");
+  io.stdout.write(`source: ${sourceMemoryDir}\n`);
+  io.stdout.write(`target: ${targetMemoryDir}\n`);
+  io.stdout.write(`imported files: ${result.importedFiles}\n`);
+  io.stdout.write(`skipped files: ${result.skippedFiles}\n`);
+}