grace-explainer

# GRACE — Graph-RAG Anchored Code Engineering

GRACE is a methodology for AI-driven code generation that makes codebases **navigable by LLMs**. It solves the core problem of AI coding assistants: they generate code but can't reliably navigate, maintain, or evolve it across sessions.

## The Problem GRACE Solves

LLMs lose context between sessions. Without structure:
- They don't know what modules exist or how they connect
- They generate code that duplicates or contradicts existing code
- They can't trace bugs through the codebase
- They drift from the original architecture over time

GRACE provides four interlocking systems that fix this:

```
Knowledge Graph (docs/knowledge-graph.xml)
    maps modules, dependencies, and public module interfaces
Module Contracts (MODULE_CONTRACT in each file)
    defines WHAT each module does
Semantic Markup (START_BLOCK / END_BLOCK in code)
    makes code navigable at ~500 token granularity
Verification Plan (docs/verification-plan.xml)
    defines HOW correctness, traces, and logs are proven
Operational Packets (docs/operational-packets.xml)
    standardizes execution packets, deltas, and failure handoff
```

GRACE is process-first, not prompt-first. The point is to make good execution boring: define the contract, name the surfaces, plan verification, and give the worker a bounded packet before asking it to run.

## Six Core Principles

### 1. Never Write Code Without a Contract
Before generating any module, create its MODULE_CONTRACT with PURPOSE, SCOPE, INPUTS, OUTPUTS. The contract is the source of truth — code implements the contract, not the other way around.

### 2. Semantic Markup Is Not Comments
Markers like `// START_BLOCK_NAME` and `// END_BLOCK_NAME` are **navigation anchors**, not documentation. They serve as attention anchors for LLM context management and retrieval points for RAG systems.

### 3. Knowledge Graph Is Always Current
`docs/knowledge-graph.xml` is the single map of the entire project. When you add a module — add it to the graph. When you add a dependency — add a CrossLink. The graph never drifts from reality. Shared docs should describe the module's public contract, not every private helper or implementation detail.

### 4. Top-Down Synthesis
Code generation follows a strict pipeline:
```
Requirements -> Technology -> Development Plan -> Verification Plan -> Module Contracts -> Code + Tests
```
Never jump to code. If requirements are unclear — stop and clarify.

### 5. Verification Is Architecture
Testing, traces, and log markers are not cleanup work. They are part of the architectural blueprint. If another agent cannot verify or debug a module from the evidence left behind, the module is not fully done.

### 6. Governed Autonomy (PCAM)
- **Purpose**: defined by the contract (WHAT to build)
- **Constraints**: defined by the development plan (BOUNDARIES)
- **Autonomy**: you choose HOW to implement
- **Metrics**: the contract plus verification evidence tell you if you're done

You have freedom in HOW, not in WHAT. If a contract seems wrong — propose a change, don't silently deviate.

## Semantic Anchoring

GRACE assumes that agents work better when the code and artifacts carry domain meaning directly.

- prefer `CustomerProfile`, `ArchiveDatabase`, `ValidateInput`, and `BLOCK_ASSIGN_TITLE` over abstract placeholders or opaque IDs
- keep PURPOSE, SCOPE, and scenario text concrete enough that they describe the transformation, not just the file boundary
- if a rule is subtle, place a compact example in verification or notes rather than hoping an agent will infer the edge case from vague prose

This does not replace contracts. It makes contracts easier for agents to execute accurately.

## How the Elements Connect

```
docs/requirements.xml          — WHAT the user needs (use cases, AAG notation)
        |
docs/technology.xml            — WHAT tools we use (runtime, language, versions)
        |
docs/development-plan.xml      — HOW we structure it (modules, phases, public contracts)
        |
docs/verification-plan.xml     — HOW we prove it works (tests, traces, log markers)
docs/operational-packets.xml   — HOW agents hand work across execution, review, and fixes
        |
docs/knowledge-graph.xml       — MAP of module boundaries, dependencies, public interfaces, and verification refs
        |
src/**/* + tests/**/*          — CODE and TESTS with GRACE markup and evidence hooks
```

Each layer feeds the next. The knowledge graph and verification plan are both outputs of planning and inputs for execution.

Important boundary rule:
- shared GRACE docs describe only public module contracts and public module interfaces
- private helpers, local-only types, and internal orchestration details stay in the module file header, function contracts, and semantic blocks
- place START_CONTRACT/END_CONTRACT above both: function signature and docstrings/comments

## Optional CLI Support

GRACE also has an optional CLI package, `@osovv/grace-cli`, which installs the `grace` binary.

Current public commands:
- `grace lint --path /path/to/project`
- `grace lint --profile autonomous --path /path/to/project`
- `grace lint --explain docs.missing-required-artifact`
- `grace status --path /path/to/project`
- `grace status --with modules --path /path/to/project`
- `grace module find auth --path /path/to/project`
- `grace module show M-AUTH --path /path/to/project --with verification,health`
- `grace module health M-AUTH --path /path/to/project`
- `grace verification find auth --path /path/to/project`
- `grace verification show V-M-AUTH --path /path/to/project`
- `grace file show src/auth/index.ts --path /path/to/project --contracts --blocks`

Use the CLI for:
- GRACE semantic markup pairing and completeness
- unique-tag convention anti-patterns in XML
- graph/plan/verification reference mismatches
- autonomy-readiness gaps in packet quality, verification depth, and observable evidence
- module-scoped readiness, blockers, and remediation hints
- MODULE_MAP