atavi 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,167 @@
+# Architecture
+
+This document explains why ATAVI is shaped as a thin package plus a strict file
+contract rather than a heavy orchestration runtime.
+
+## The core idea
+
+ATAVI is not the orchestrator. The host AI is.
+
+That decision is deliberate:
+
+- it keeps ATAVI host-agnostic
+- it avoids duplicating auth, model routing, and search capabilities
+- it lets the protocol evolve without shipping a long-running service
+
+ATAVI therefore has two responsibilities:
+
+1. package the protocol surface cleanly
+2. make host execution inspectable and resumable through a local workspace
+
+## System model
+
+```text
+Researcher / Product Builder
+            |
+            v
+      Host AI Environment
+  (Codex / Claude / Gemini)
+            |
+            | reads packaged protocol + templates
+            v
+           ATAVI
+  ----------------------------------
+  protocol/ATAVI.md
+  protocol/agents/*
+  templates/*
+  bin/atavi
+  src/scaffold + doctor helpers
+  ----------------------------------
+            |
+            | writes state
+            v
+        Project .atavi/
+  ----------------------------------
+  brief.md
+  config.json
+  status.md
+  conflicts.md
+  kill-log.md
+  run-log.md
+  pass-N/
+  registries/
+  memory/
+  ATAVI-REPORT.md
+  ----------------------------------
+```
+
+## Why the CLI stays thin
+
+The spec explicitly says ATAVI is a protocol, not an application runtime.
+The CLI should help the host find and scaffold the protocol, but should not
+attempt to run multi-agent orchestration itself.
+
+That means:
+
+- `--path` exists so the host can load the packaged assets
+- `init` exists so the host has a known workspace layout
+- `doctor` exists so failures are obvious before a run starts
+
+What the CLI should not do:
+
+- call model APIs directly
+- maintain its own orchestration daemon
+- embed search credentials
+- silently mutate the host environment
+
+## File-first state
+
+ATAVI uses files as the contract between the host AI, the user, and future runs.
+That is why `.atavi/` matters so much.
+
+The benefits:
+
+- every pass is inspectable
+- interrupted runs are resumable
+- memory can persist across runs
+- humans can audit why an experiment survived or died
+
+## Canonical registries
+
+The host AI owns three canonical registries inside `.atavi/registries/`:
+
+- Claim Registry
+- Experiment Ledger
+- Prior Art Registry
+
+Agents do not edit them directly. Agents propose changes in PODs and CPRs.
+The host AI applies accepted changes during synthesis.
+
+This is the key guardrail against drift and hidden state.
+
+The root workspace also carries shared process artifacts such as `conflicts.md`,
+`kill-log.md`, and `run-log.md` so synthesis and final reporting have stable
+canonical locations.
+
+Per-pass host artifacts live under `pass-N/`, where agent PODs, CPRs,
+`synthesis.md`, and `decision.md` make each refinement cycle inspectable.
+
+Reusable memory exports belong in the scoped bucket directories under
+`.atavi/memory/`.
+
+## Memory architecture
+
+ATAVI needs cross-run memory because the same researcher will often run related
+projects over time. The architecture is intentionally explicit:
+
+- prior art cache
+- kill archive
+- claim patterns
+- convergence history
+- strategy insights
+
+The scaffold reflects those buckets directly under `.atavi/memory/` so the
+host can persist artifacts without inventing ad hoc subdirectories.
+
+Memory needs governance or it turns into an echo chamber. The package docs
+therefore treat expiration, contradiction handling, weighting, and scoping as
+first-class design constraints, not implementation polish.
+
+Those constraints are expressed directly in the scaffolded memory bucket
+READMEs so hosts have a canonical file format for durable memory exports.
+
+## Why committed assets matter
+
+ATAVI should clone cleanly. A user should not need an invisible generator to
+understand what the product is shipping. That is why the protocol markdown,
+agent role files, and templates are committed as real files in git.
+
+This mirrors one of the strongest repo patterns in `gstack`: serious artifacts
+live in the repo, not behind a hidden build step.
+
+## Testing philosophy
+
+There are three categories of failure this repo must catch:
+
+1. package drift
+2. scaffold drift
+3. behavioral drift
+
+Package drift means a required protocol file disappeared or stopped shipping.
+Scaffold drift means `init` no longer creates what the host expects.
+Behavioral drift means commands like `--path` or `doctor` stop honoring the
+contract.
+
+The current test suite is designed around those three risks.
+
+## Future extension points
+
+The current source tree leaves room for:
+
+- richer config validation
+- host-specific setup commands
+- report rendering helpers
+- memory import/export
+- migration tooling for `.atavi/` schema changes
+
+Those can be added without changing the core product model above.

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0
+
+- initialize ATAVI as a real package repository
+- add thin CLI with `--path`, `init`, and `doctor`
+- add protocol markdown, agent role files, and report templates
+- add architecture, contribution, and testing docs
+- add package-manifest verification and node test scaffolding
+- add CI to enforce package and scaffold integrity
+- expand `.atavi` scaffolding with explicit memory bucket directories
+- add `validate` command for `.atavi/config.json` contract checks
+- add pass and log placeholders to the `.atavi` scaffold contract
+- add `resume-check` command for `.atavi/status.md` and resume validation
+- add explicit per-pass synthesis and decision placeholders
+- define canonical memory entry formats and governance fields
+- add host loading and resume guidance for Codex, Claude, and Gemini
+- add `migrate` command for safe workspace schema upgrades
+- add memory import/export helpers for `.atavi/memory`
+- add release-surface verification and npm-based CI coverage

package/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+## Working rules
+
+- Keep ATAVI host-agnostic.
+- Do not turn the package into a proprietary orchestration runtime.
+- Prefer committed protocol assets over generated hidden state.
+- Preserve the file contract in `.atavi/`.
+- Treat novelty gating and inspectability as non-negotiable.
+
+## Repo workflow
+
+1. Update docs first when the product contract changes.
+2. Update protocol files and templates when agent behavior changes.
+3. Update CLI code when scaffold or package behavior changes.
+4. Add or update tests for every contract-level change.
+5. Run `node scripts/check-manifest.js`.
+6. Run `node test/run-all.js`.
+
+## What changes require extra care
+
+- renaming protocol or template files
+- changing `.atavi/` scaffold output
+- changing registry field names
+- changing CLI output consumed by hosts
+
+These are package contracts, not incidental implementation details.
+
+## Style
+
+- Use plain Node APIs unless there is a strong reason not to.
+- Keep commands small and composable.
+- Prefer explicit file paths over hidden conventions.
+- Document product-level reasoning in `ARCHITECTURE.md`, not scattered comments.
+
+## Pull request checklist
+
+- README still matches the shipped commands.
+- ARCHITECTURE still matches the product shape.
+- protocol assets exist and are referenced correctly.
+- tests cover the changed behavior.
+- CI can run without hidden local dependencies.

package/HOSTS.md

@@ -0,0 +1,177 @@
+# Host Guidance
+
+ATAVI is a protocol package, not an orchestration runtime. This document covers
+how a host should load the package, manage the `.atavi/` workspace, and resume
+interrupted runs without inventing hidden state.
+
+## Purpose And Non-Goals
+
+- ATAVI defines the file contract and protocol shape.
+- The host AI performs orchestration.
+- This guide explains load order, workspace usage, and artifact ownership.
+- This guide does not turn ATAVI into a daemon, API service, or hidden runtime.
+
+## Shared Host Contract
+
+Hosts should support:
+
+- file I/O
+- isolated agent contexts
+- web search for valid Scout runs
+
+Hosts should load:
+
+- `protocol/ATAVI.md`
+- relevant files under `protocol/agents/`
+- templates under `templates/`
+- `.atavi/brief.md`
+- `.atavi/config.json`
+- `.atavi/status.md`
+- canonical registries and logs
+
+## Invocation Detection
+
+Treat the run as ATAVI when the user explicitly asks for:
+
+- `ATAVI`
+- multi-agent research refinement
+- novelty-gated experiment selection
+- inspectable multi-pass research artifacts
+
+Do not silently infer ATAVI for ordinary coding or review tasks.
+
+## Workspace Bootstrap
+
+Recommended order:
+
+1. Run `atavi --path`.
+2. If `.atavi/` does not exist, run `atavi init .`.
+3. Run `atavi validate .` before starting a fresh loop.
+4. Run `atavi resume-check .` before resuming an interrupted loop.
+
+Use the existing workspace when `.atavi/` already exists and passes validation.
+
+## Research Brief Confirmation
+
+Before pass execution begins, confirm `.atavi/brief.md` contains:
+
+- source spec or source artifact
+- thesis or central question
+- domain
+- constraints
+- novelty sources
+- selected agents
+
+If these are incomplete or contradictory, stop and ask the researcher.
+
+## Agent Selection Rules
+
+Always include:
+
+- Theorist
+- Experimentalist
+- Scout
+
+Add Critic when:
+
+- the cost of failure is high
+- the work is irreversible
+- the novelty landscape is crowded
+
+Add Synthesist when:
+
+- the problem spans multiple domains
+- adjacent disciplines may contain useful methods
+
+## Pass Execution Contract
+
+Hosts should write:
+
+- PODs to `.atavi/pass-N/[agent]-pod.md`
+- CPRs to `.atavi/pass-N/cross-pollination/[agent]-cpr.md`
+- synthesis output to `.atavi/pass-N/synthesis.md`
+- decision output to `.atavi/pass-N/decision.md`
+
+Hosts should also maintain:
+
+- `.atavi/registries/claims.md`
+- `.atavi/registries/experiments.md`
+- `.atavi/registries/prior-art.md`
+- `.atavi/conflicts.md`
+- `.atavi/kill-log.md`
+- `.atavi/run-log.md`
+
+## Registry Ownership And Synthesis
+
+Agents propose changes in PODs and CPRs. The host applies accepted changes to
+the canonical registries and logs during synthesis. Registry state should not
+exist only in chat output.
+
+## Novelty And Memory Recording
+
+- Claim-level novelty evidence belongs in `.atavi/registries/prior-art.md`.
+- Experiment-level novelty verdicts belong in `.atavi/registries/experiments.md`.
+- Reusable memory exports belong in `.atavi/memory/` after the run.
+- Hosts may use `atavi memory-export` and `atavi memory-import` to move durable
+  memory artifacts between workspaces without changing their contents.
+
+## Resume Workflow
+
+When resuming:
+
+1. Run `atavi validate .`.
+2. Run `atavi resume-check .`.
+3. Read `.atavi/status.md`.
+4. Read `.atavi/run-log.md`.
+5. Inspect the latest `pass-N/` directory.
+6. Continue from the recorded phase instead of regenerating prior artifacts.
+
+`resume-check` guarantees structural resume safety for the current package
+contract. It does not decide the next research action for the host.
+
+## Codex
+
+Recommended load order:
+
+1. `atavi --path`
+2. `protocol/ATAVI.md`
+3. required role files under `protocol/agents/`
+4. `.atavi/brief.md`, `.atavi/config.json`, `.atavi/status.md`
+5. registries, logs, and latest `pass-N/` artifacts
+
+Codex should keep orchestration file-first and write durable artifacts into
+`.atavi/` rather than relying on hidden memory.
+
+## Claude
+
+Recommended load order:
+
+1. `atavi --path`
+2. `protocol/ATAVI.md`
+3. relevant role files and templates
+4. `.atavi/brief.md`, `.atavi/config.json`, `.atavi/status.md`
+5. registries, logs, and existing pass artifacts
+
+Claude should treat `.atavi/` as the source of truth for resumability and audit.
+
+## Gemini
+
+Recommended load order:
+
+1. `atavi --path`
+2. `protocol/ATAVI.md`
+3. relevant role files and templates
+4. `.atavi/brief.md`, `.atavi/config.json`, `.atavi/status.md`
+5. registries, logs, and existing pass artifacts
+
+Gemini should preserve the same file contract as every other host.
+
+## Failure Modes And Escalation
+
+Hosts should stop and ask the researcher when:
+
+- config validation fails
+- resume-state validation fails
+- Scout-valid web search is unavailable
+- the brief is contradictory or under-specified
+- early convergence appears suspicious and requires an adversarial pass

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,232 @@
+# ATAVI
+
+ATAVI is a host-agnostic multi-agent research refinement protocol. It gives a
+host AI a strict file-first workflow for:
+
+- formalizing claims
+- designing experiments
+- checking novelty
+- forcing cross-pollination between roles
+- converging on the smallest high-signal experiment slate
+- leaving an inspectable paper trail in `.atavi/`
+
+ATAVI is intentionally thin. The package does not run the research loop for
+you. It ships the protocol, role files, templates, and CLI helpers that a host
+AI can load and execute.
+
+## What You Get
+
+The package ships:
+
+- `protocol/ATAVI.md` as the canonical protocol
+- `protocol/agents/*` for Theorist, Experimentalist, Scout, Critic, and Synthesist
+- `templates/*` for briefs, PODs, CPRs, and final reports
+- `bin/atavi.js` as the CLI entrypoint
+- `HOSTS.md` for Codex, Claude, and Gemini loading guidance
+- scaffold, validation, migration, and memory-transfer helpers
+
+## Requirements
+
+- Node.js `>=20`
+- a host AI that can read and write files
+- web search capability for valid Scout runs
+
+Without web search, Scout mode and full novelty gating are not valid.
+
+## Install
+
+### Global install
+
+```bash
+npm install -g atavi
+```
+
+### Run with `npx`
+
+```bash
+npx atavi --help
+```
+
+### Run from a local checkout
+
+```bash
+git clone https://github.com/mechramc/Atavi.git
+cd Atavi
+npm install
+node bin/atavi.js --help
+```
+
+## Quick Start
+
+### 1. Create a workspace
+
+From the project you want to analyze:
+
+```bash
+atavi init .
+atavi validate .
+```
+
+This creates a `.atavi/` workspace with the brief, registries, pass folders,
+logs, report file, and memory buckets the host will use.
+
+### 2. Point your host at the protocol
+
+```bash
+atavi --path
+```
+
+The returned path contains:
+
+- `protocol/ATAVI.md`
+- `protocol/agents/*`
+- `templates/*`
+
+Your host should load those files plus `.atavi/brief.md`, `.atavi/config.json`,
+and `.atavi/status.md`.
+
+### 3. Run the protocol
+
+Typical flow:
+
+1. Put a spec, proposal, design doc, or codebase in front of your host AI.
+2. Run `atavi init .` in the project root.
+3. Tell the host AI to run ATAVI on the workspace.
+4. The host writes PODs, CPRs, synthesis records, decision records, registry updates, and memory artifacts into `.atavi/`.
+5. Review `.atavi/ATAVI-REPORT.md` when the run finishes.
+
+### 4. Resume or repair later
+
+```bash
+atavi resume-check .
+atavi migrate .
+```
+
+Use `resume-check` before resuming an interrupted run. Use `migrate` to add any
+missing scaffold files or schema metadata without overwriting user edits.
+
+## Command Reference
+
+### `atavi --help`
+
+Print CLI help.
+
+### `atavi --version`
+
+Print the package version.
+
+### `atavi --path`
+
+Print the absolute path to the packaged protocol root so a host can load the
+protocol, role files, and templates.
+
+### `atavi init [target]`
+
+Create a `.atavi/` workspace in `target` without overwriting existing files.
+
+The scaffold includes:
+
+- `brief.md`
+- `config.json`
+- `status.md`
+- `conflicts.md`
+- `kill-log.md`
+- `run-log.md`
+- `ATAVI-REPORT.md`
+- `pass-1/README.md`
+- `pass-1/synthesis.md`
+- `pass-1/decision.md`
+- `pass-1/cross-pollination/README.md`
+- `registries/claims.md`
+- `registries/experiments.md`
+- `registries/prior-art.md`
+- `memory/README.md`
+- `memory/prior-art-cache/README.md`
+- `memory/kill-archive/README.md`
+- `memory/claim-patterns/README.md`
+- `memory/convergence-history/README.md`
+- `memory/strategy-insights/README.md`
+
+### `atavi doctor`
+
+Verify that the packaged protocol and template assets exist.
+
+### `atavi validate [target]`
+
+Validate `.atavi/config.json` against the current package contract.
+
+### `atavi resume-check [target]`
+
+Validate `.atavi/config.json` and `.atavi/status.md` before a host resumes an
+interrupted run.
+
+### `atavi migrate [target]`
+
+Upgrade an existing `.atavi/` workspace to the current schema by adding missing
+files and schema metadata without overwriting user-edited files.
+
+### `atavi memory-export [target] [output]`
+
+Copy `.atavi/memory` to an export directory for reuse in another workspace.
+
+Example:
+
+```bash
+atavi memory-export . .atavi/exports/memory
+```
+
+### `atavi memory-import <source> [target]`
+
+Copy memory files into `.atavi/memory` without overwriting existing entries.
+
+Example:
+
+```bash
+atavi memory-import .atavi/exports/memory .
+```
+
+## Recommended Host Workflow
+
+Use this order:
+
+```bash
+atavi --path
+atavi init .
+atavi validate .
+atavi resume-check .
+```
+
+Then have the host:
+
+1. confirm or refine `.atavi/brief.md`
+2. load `protocol/ATAVI.md` and the relevant role files
+3. write pass artifacts into `.atavi/pass-N/`
+4. update registries and logs during synthesis
+5. export reusable memory into `.atavi/memory/`
+
+See [HOSTS.md](./HOSTS.md) for Codex, Claude, and Gemini-specific loading guidance.
+
+## Development
+
+From a repo checkout:
+
+```bash
+npm install
+npm test
+npm run ci
+```
+
+Equivalent raw Node commands:
+
+```bash
+node scripts/check-manifest.js
+node scripts/check-release-surface.js
+node test/run-all.js
+```
+
+## Related Docs
+
+- [HOSTS.md](./HOSTS.md)
+- [ARCHITECTURE.md](./ARCHITECTURE.md)
+- [TESTING.md](./TESTING.md)
+- [CONTRIBUTING.md](./CONTRIBUTING.md)