Core Concepts

DAMS models a project as a git-versioned Markdown wiki plus a local SQLite ledger. The wiki is the single source of truth; the compiler turns it into a compact steering file.

Context Wiki (`.dams/context/`)

A directory of structured Markdown files — decisions, contracts, traps, tasks, and sessions — that is Obsidian-compatible and git-versioned. Key subfolders:

decisions/ — architecture decision records (ADRs).
contracts/ — safety contracts enforced by the Safety Gate.
traps/ — regression traps auto-extracted from fix: commits.
tasks/ — atomized task tree + _registry.yaml.
active/ — broken.md, next.md, codeResearch.md scratchpad.
sessions/ — auto-generated session logs.
skills/ — reusable SKILL.md workflows.

Context Compiler (3-layer token budget)

The compiler reads the wiki and produces a freshness-scored steering file (default DAMS.md) targeting an 8K token budget:

Layer	Content	Included when
L1 — Never Drop	Active issues, safety-critical contracts, immediate priorities	Always
L2 — High Priority	Last 5 decisions, critical traps, pending PRD deps	>2K tokens remaining
L3 — Fill	Completed decisions (summarized), conventions, old logs	>5K tokens remaining

Freshness score (0.0–1.0) = 0.5·Recency + 0.3·Drift + 0.2·Age. Below 0.8 the agent is told to recompile; below 0.5 context is treated as potentially stale. Token counting uses tiktoken (cl100k_base).

Safety Gate (`dams check`)

String-level — keyword scan against each contract.
GritQL structural — AST-level enforcement via .dams/patterns/*.grit.
Modes — block (reject), warn, off.
Auto-healing — --fix invokes GritQL to rewrite violations in place.

Drift Detection (`dams doctor`)

Detection	Severity
Wiki references a deleted file	warning
Task marked done but tests fail	warning
Stale issue (>30 days)	info
Contradictory contracts	error
Decision superseded but still referenced	info

CodeGraph & Graphify

Graphify (preferred) is a multi-modal knowledge graph (Tree-sitter AST + optional LLM semantic extraction) with Leiden community clustering. It identifies high-degree "god nodes" and surprising cross-file connections. CodeGraph is the fast tree-sitter fallback call graph for ripple detection when Graphify is unavailable. Both feed AGENTS.md in ~200 tokens versus ~123k reading every file.

Code Research (Chunkhound)

Chunkhound's orchestrated BFS sub-agent explores code relationships dynamically at query time — virtual Graph RAG without precomputed graph storage. It uses cAST chunking (structure-aware, 4.3pt retrieval gain), hybrid semantic+regex search, and a local Ollama reranker. Results land in the codeResearch.md scratchpad.

Atomized Tasks

A single granular unit of work (e.g., "create users table"), auto-generated from the PRD by pure LLM reasoning; the AI implicitly designs the schema and task hierarchy together. Tasks carry frontmatter with status, priority, dependencies, files, and linked commits.