# INTENT.md - Intent-Driven Engineering Contract (General)

**Authority:** binding (general methodology contract; not project-specific)
**Layer:** Constitution
**Binding:** Yes ⚠️
**Scope:** intent-first flow, choice protocol, proof doctrine, drift recovery
**Non-goals:** project-specific requirements, control-plane interfaces, subsystem registries, or document routing

⚠️ **THIS IS A BINDING CONSTITUTIONAL CONTRACT. AGENTS MUST COMPLY.** ⚠️

This file is a general-purpose contract for how an agent should behave when operating in an intent-driven codebase.

It is intentionally not project-specific. Project-specific truth belongs in the repo's own manifest/requirements and is enforced by its proof surface.

---

## 1. Intent Is the API

**⚠️ FUNDAMENTAL LAW: Intent is a versioned contract that states what must be true. Everything downstream is derived.**

```
Intent → Architecture → Implementation → Proof → Promotion
```

If reality disagrees with intent, do NOT hand-wave. Either:

1. Update intent explicitly (and then recompile downstream artifacts).
2. Enter explicit drift recovery mode (time-boxed), then reestablish one-way flow.

**FAILURE TO FOLLOW THIS FLOW = UNVERIFIED, UNSAFE WORK.**

---

## 2. Authority and Conflict Resolution

When artifacts conflict, authority resolves it. The **mandatory ladder** in an intent-driven repo:

```
1. BINDING INTENT CONTRACT (this spec describes how to treat it) ← HIGHEST AUTHORITY
2. Architecture (compiled from intent)
3. Proof surface (tests, validate commands, proof notes)
4. Agent entrypoints (AGENTS/CLAUDE/etc)
5. Human workflow docs
6. Philosophy/context (must be explicitly marked non-binding if present)
```

**AGENTS: If the repo defines its own authority ladder, follow it, but require it to be explicit and stable.**

---

## 3. What "Working With Intent" Means (Agent Protocol) ⚠️ REQUIRED ⚠️

When asked to do work that changes behavior, state, or interfaces:

1. **Name the intent** in one sentence (what must be true when you are done).
2. **Identify the smallest proof surface** that can falsify success.
3. **If a change would alter the contract**, propose the contract change BEFORE touching code.
4. **Produce traceability**: connect the change to a promise/invariant/requirement in writing.

For non-trivial changes, use the **explicit change protocol**:

1. Intent delta (if needed).
2. Architecture delta.
3. Implementation delta.
4. Proof delta.
5. Validation run and report.

---

## 4. Choice Protocol (No Silent Defaults)

If a choice materially impacts build/run/ops/security/data semantics, it MUST be explicit.

**Material choices include:**

- language and runtime
- data store and schema strategy
- concurrency and process model
- secrets handling
- interface contracts (CLI/HTTP/event formats)
- portability and platform assumptions

If you inherit a default, you MUST say that you are inheriting it, and from where.

**SILENT DEFAULTS = VIOLATION OF THIS CONTRACT.**

---

## 5. Proof Is the Price of Promotion

Promotion means any claim that work is "ready", "verified", "compliant", or safe to merge/deploy.

**RULES:**

- If there is a proof surface, **RUN IT**.
- If you cannot run it, say "unverified" and state exactly what blocks verification.
- If proofs are missing, **your job is to create the smallest proof step** that collapses the uncertainty.

**UNVERIFIED PROMOTION = VIOLATION OF THIS CONTRACT.**

---

## 6. Traceability (Stable IDs)

Intent-driven work requires stable identifiers so artifacts can link without drift.

**Minimum expectations:**

- promise IDs are stable (P1, P2, ...) and never renumbered
- architecture references those IDs
- proofs reference those IDs (directly or via a mapping table)

If a repo uses a different stable ID scheme, **keep it stable and linkable.**

---

## 7. Drift: Detection and Recovery

Drift is any mismatch between:

- intent vs code
- architecture vs code
- proofs vs reality
- docs claiming capabilities that do not exist

**Recovery is allowed, but it MUST be explicit:**

1. Label recovery mode.
2. Update contracts to match reality (or roll reality back to match contracts).
3. Re-run proofs.
4. Exit recovery mode.

**UNDETECTED DRIFT = SYSTEM INVALID.**

---

## 8. Layer Boundaries (Methodology vs Interface vs Router)

This contract defines methodology only.

Interface semantics for agent<->CLI sequencing live in `interfaces/CONTROL_PLANE.md`.
Routing/navigation semantics live in `core/DECAPOD.md`.

If this file starts specifying command envelopes, store wiring, subsystem indexing, or routing policy, that content belongs elsewhere.

---

## 9. Changelog

- v0.0.2: Clarified layer boundaries by extracting control-plane interface and routing content out of this methodology contract.
- v0.0.1: A general agent-facing methodology contract (not project-specific), restoring the original intent-driven engineering emphasis: authority, one-way flow, choice protocol, proof gating, and drift recovery.

## Links

### Core Router
- `core/DECAPOD.md` - **Router and navigation charter (START HERE)**

### Authority (Constitution Layer)
- `specs/SYSTEM.md` - System definition and authority doctrine
- `specs/SECURITY.md` - Security contract
- `specs/GIT.md` - Git etiquette contract
- `specs/AMENDMENTS.md` - Change control

### Registry (Core Indices)
- `core/PLUGINS.md` - Subsystem registry
- `core/INTERFACES.md` - Interface contracts index
- `core/METHODOLOGY.md` - Methodology guides index

### Contracts (Interfaces Layer)
- `interfaces/CONTROL_PLANE.md` - Sequencing patterns
- `interfaces/DOC_RULES.md` - Doc compilation rules
- `interfaces/STORE_MODEL.md` - Store semantics
- `interfaces/CLAIMS.md` - Promises ledger
- `interfaces/GLOSSARY.md` - Term definitions

### Practice (Methodology Layer)
- `methodology/ARCHITECTURE.md` - Architecture practice
- `methodology/SOUL.md` - Agent identity
- `methodology/KNOWLEDGE.md` - Knowledge curation
- `methodology/MEMORY.md` - Memory and learning

### Operations (Plugins Layer)
- `plugins/TODO.md` - Work tracking
- `plugins/VERIFY.md` - Validation subsystem

---

## Project Override Context

Project intent emphasis:
- Build an assistant that is secure-by-default and user-controlled.
- Prefer extensibility through clear interfaces over hardcoded integrations.
- Support multiple interaction channels while preserving consistent behavior.
- Treat autonomy as bounded by policy, proofs, and explicit human control points.
