{"_id":"@anatomytool/spec","name":"@anatomytool/spec","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@anatomytool/spec","version":"1.0.0","description":"The Anatomy standard — schema, recommended-stacks reference, canonicalization rules, conformance fixtures.","type":"module","scripts":{"fix:hashes":"node scripts/fix-fixture-hashes.mjs","validate":"node scripts/validate-spec.mjs && node --test eval/scripts/tests/*.test.mjs","eval":"node eval/scripts/run-citation.mjs","eval:baseline":"node eval/scripts/run-citation.mjs --update-baseline","eval:test":"node --test eval/scripts/tests/*.test.mjs","test":"npm run validate"},"engines":{"node":">=22"},"license":"MIT","publishConfig":{"access":"public"},"devDependencies":{"@types/node":"^25.7.0","ajv":"^8.17.0","ajv-formats":"^3.0.0","js-yaml":"^4.1.0","promptfoo":"^0.78.0","smol-toml":"^1.3.0","typescript":"^6.0.3"},"gitHead":"d7704efab8bec9a3bbbba5d26b7aa01bd41ec56e","_id":"@anatomytool/spec@1.0.0","_nodeVersion":"22.17.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-71iaGRnker20EZZJy/7iVSRVctDlPAnqEa3lMOV4E/ZQRmG3nySLuWrfZqSTCx4UqhptPetyLV0PSd/e293qLg==","shasum":"10fc74d8d616b93261b9056f951388d57e70abb7","tarball":"https://registry.npmjs.org/@anatomytool/spec/-/spec-1.0.0.tgz","fileCount":210,"unpackedSize":544669,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDL+OmI4q+x3NgAQ7iUElvX6Y6WORbYHNm7X6XaLyDbjwIgOJepieN7NwzKiUWHFIUH7I/Yg5H1Z8xyH/vlzmpslfI="}]},"_npmUser":{"name":"0xhayd3n","email":"haydenseymour02@gmail.com"},"directories":{},"maintainers":[{"name":"0xhayd3n","email":"haydenseymour02@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/spec_1.0.0_1779025662381_0.6299633659438353"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-17T13:47:42.311Z","1.0.0":"2026-05-17T13:47:42.571Z","modified":"2026-05-17T13:47:42.804Z"},"maintainers":[{"name":"0xhayd3n","email":"haydenseymour02@gmail.com"}],"description":"The Anatomy standard — schema, recommended-stacks reference, canonicalization rules, conformance fixtures.","license":"MIT","readme":"# Anatomy\n\n> A TOML + memory format that lets AI coding agents cite repo-specific rules and decisions — and detect when that knowledge has gone stale.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%E2%89%A5%2022-brightgreen.svg)](package.json)\n\nAI coding agents have a recurring failure mode: they re-derive the same\nproject facts every session, miss system-level rules that don't grep cleanly,\nand trust documentation that has silently drifted from the code.\n\n**Anatomy** is a small, machine-readable corpus you commit to the repo so\nagents stop guessing. It has two files:\n\n- **`.anatomy`** — repository identity along four pillars (**Stack**,\n  **Form**, **Domain**, **Function**) plus the *uncapturable* knowledge an\n  agent can't infer from source: rules, flows, and decisions.\n- **`.anatomy-memory`** — an append-only log of lived experience (gotchas,\n  decisions, conventions, attempts) paired to the `.anatomy` by fingerprint.\n\nEvery read pins to a git commit, so consumers can tell when the knowledge no\nlonger matches `HEAD` instead of trusting it blindly.\n\n## Contents\n\n- [What it looks like](#what-it-looks-like)\n- [What it buys you](#what-it-buys-you)\n- [Install](#install)\n- [Quick start](#quick-start)\n- [Format](#format)\n- [Versions & status](#versions--status)\n- [Packages](#packages)\n- [Conformance fixtures](#conformance-fixtures)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [License](#license)\n\n## What it looks like\n\nThis repository describes *itself* with an `.anatomy` file. A trimmed excerpt:\n\n```toml\nanatomy_version = \"0.13\"\ntagline = \"TOML + memory format that lets AI agents cite repo-specific rules/decisions and detect their own staleness.\"\n\n[identity]\nstack       = \"javascript\"\nform        = \"monorepo\"\ndomain      = \"repo-metadata\"\nfunction    = \"ai-context-format\"\nfingerprint = \"jcevybzm4r897e6rhe11\"\n\n[[rules]]\nrule = \"Hand-roll TOML output when section order matters; do not use smol-toml.stringify\"\nwhy  = \"smol-toml does not preserve insertion order; section order is normative per spec section 5\"\n\n[[decisions]]\ntopic  = \"v0.3 is an ecosystem release, not a wire version\"\nreason = \"v0.3 added cascading discovery + merge semantics for multi-.anatomy repos but did not change the per-file format…\"\n\n[generated]\nat     = 2026-05-17T04:53:13.000Z\ncommit = \"948fe0b\"            # every read pins here; consumers detect drift vs HEAD\nby     = \"anatomy-cli@0.13.0\"\n```\n\nAn agent reading this can cite the exact rule and decision rather than\nre-deriving them — and knows to flag the file if `commit` has fallen behind\n`HEAD`.\n\n## What it buys you\n\nMeasured in a [cross-repo N=3 eval (2026-05-09)](docs/superpowers/specs/2026-05-09-anatomy-consumer-results-cross-repo-N3.md):\n\n- **Citation reliability.** Across 27 cross-repo treatment trials, agents\n  cited specific `.anatomy` rules / decisions / flows or `.anatomy-memory`\n  entries in 24/27 (89%); baseline was 0/27.\n- **Surfacing system-level facts.** Treatment caught a system-level rule that\n  doesn't grep cleanly (a TPM-preflight gate) in 2/3 reps; baseline missed it\n  in 3/3.\n- **Self-detected staleness.** Every read pins to a git commit, so consumers\n  see drift between `.anatomy.generated.commit` and `HEAD` and can react.\n\n> **Honest scope.** The measured win is *citation reliability* and\n> *self-detected staleness* — **not** faster lookups. On the same eval,\n> baseline beat or tied treatment on `tool_calls_to_first_evidence` for 8 of\n> 9 cross-repo cells, and the original single-repo headline of −36%\n> wall-clock did **not** replicate cross-repo. The honest pitch is\n> \"machine-readable docs that agents cite reliably and that detect their own\n> staleness,\" not \"agents are faster.\"\n\n## Install\n\nNot yet published to npm. Install the CLI from source:\n\n```bash\ngit clone https://github.com/0xHayd3n/anatomy\ncd anatomy/anatomy-cli\nnpm install        # @anatomy/validate auto-builds via its prepare hook\nnpm run build      # compile the CLI (tsc → dist/); required, the binary is dist/bin.js\nnpm link           # expose `anatomy` on your PATH (optional)\nanatomy --help\n```\n\nRequires **Node.js ≥ 22**.\n\nTo work on the spec and conformance fixtures instead, from the repo root:\n\n```bash\nnpm install\nnpm run validate   # full content-integrity check (see below)\n```\n\n## Quick start\n\n```bash\nanatomy generate          # Pass 1: starter .anatomy from manifest + README + dirs; also writes AGENTS.md\nanatomy generate --ai     # Pass 2: enrich the human-knowledge fields via an AI provider\nanatomy validate          # validate .anatomy (and a sibling .anatomy-memory if present)\nanatomy mcp               # serve it to agents over MCP  (or: anatomy hook)\n```\n\nA generated `.anatomy` is TOML you are expected to **hand-edit** — Pass 1\nfills what it can deterministically and leaves `# TODO` markers for the\nhuman-knowledge fields. The full command reference lives in\n[`anatomy-cli/README.md`](anatomy-cli/README.md), kept in sync with\n`anatomy --help` and intentionally not duplicated here.\n\n## Format\n\n`.anatomy` files are **TOML 1.0, UTF-8**. The top level is grouped:\n`[identity]` and `[generated]` are required; `[operation]` and `[substance]`\nare optional groups for AI-grade per-repo context.\n\n`.anatomy-memory` files are also TOML 1.0, UTF-8, with a two-line header\n(`anatomy_memory_version`, `repo_fingerprint`) followed by `[[entries]]`\nblocks. **Append-only by design** — entries are superseded, never rewritten.\n\n`npm run validate` runs the full content-integrity check: every schema is\nvalid JSON Schema; every recommended-stacks file validates against its\nmeta-schema; every `valid/*` fixture parses and validates with correct\ncanonical-form hashes; every `invalid/*` fixture fails with the expected\nerrors (or is a documented `schema_can_detect: false` boundary case);\n`valid-with-warnings/*` fixtures validate cleanly with their expected warning\nsurface; and canonicalization cases produce the documented strings and hashes.\n\n## Versions & status\n\nThe normative version index is [`spec/CURRENT.md`](spec/CURRENT.md). Current state:\n\n| Surface | Latest | Notes |\n|---|---|---|\n| `.anatomy` file format | **v1.0** | Stabilization of v0.15 — structurally identical; the 0→1 bump is a stability commitment, not a breaking change. v0.1–v0.15 remain valid, declared via `anatomy_version`. |\n| Ecosystem | **v0.3** | Cascading-aware multi-`.anatomy` repos. An ecosystem (validator + cascading) release — the per-file wire format is unchanged from v0.2. |\n| `.anatomy-memory` | **v0.2** | v0.1 still valid; v0.2 adds optional `last_verified_at` / `verified_by` for decay tracking. |\n| AGENTS.md emission | **v0.10** | Emits a derived [`AGENTS.md`](https://agents.md/) (read by Codex / Copilot / Cursor) alongside `.anatomy`. Token-budgeted; honors the optional `[generate]` config. |\n| Rule verification | **v0.12+** | Optional `verify` on each `[[rules]]` entry checks the rule against source. Two glob-based kinds (no dependency), one AST kind via optional `@ast-grep/napi`, and (v0.13+) `kind = \"semgrep\"` for pattern combinators and non-JS languages via an optional `semgrep` CLI. Surfaces drift between documented rules and actual code. |\n\n## Packages\n\n| Package | Version | What it is |\n|---|---|---|\n| [`@anatomy/spec`](package.json) | 1.0.0 | The standard — schema, recommended-stacks reference, canonicalization rules, conformance fixtures. (This repo root.) |\n| [`@anatomy/validate`](anatomy-validate/) | 1.0.0 | Version-routed JSON-schema validator; fingerprint / hash / path checks; cascading tree discovery. |\n| [`@anatomy/cli`](anatomy-cli/) | 1.0.0 | The `anatomy` command — generate, validate, render, migrate, manage the memory log, and serve agents via a Claude Code SessionStart hook or an MCP server. |\n\n## Conformance fixtures\n\n[`fixtures/`](fixtures/README.md) is the conformance test set consumed by\nvalidator implementations:\n\n- **Single-file:** 24 valid, 3 valid-with-warnings, 33 invalid (covering\n  versions 0.1 through 1.0).\n- **Cascading (multi-file):** 2 valid, 1 valid-with-warnings, 2 invalid.\n- **Canonicalization:** 16 cases (11 valid + 5 invalid) in\n  [`fixtures/canonicalization-cases.json`](fixtures/canonicalization-cases.json),\n  driving the ID → canonical-form transformation.\n\n## Documentation\n\n- **Normative reference:** [`spec/CURRENT.md`](spec/CURRENT.md) — maps each\n  format version to its schema, canonicalization, prompt, versioning policy,\n  and recommended-stacks docs.\n- **CLI reference:** [`anatomy-cli/README.md`](anatomy-cli/README.md).\n- **Design history:** per-version design rationale and implementation plans\n  live in [`docs/`](docs/).\n\n## Contributing\n\nIssues and pull requests welcome. Before opening a PR, run `npm run validate`\nfrom the repo root — it is the same content-integrity gate CI enforces, and a\ngreen run is required to merge. Commits follow the\n[Conventional Commits](https://www.conventionalcommits.org/) style used\nthroughout the history.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md","_rev":"1-7fcdf674d0d7f0a9ef051beb612910dc"}