Intent and approval

Why intent is separate

Contract Graph Dev Kit needs to know what a repository is for before its boundaries can guide delivery. After cg init, run /cg-warmup for both a new project and an existing codebase. Warmup does not run as part of init. Init creates .agents/cg/project-context.md beside the root contract.yaml and preserves it on later runs. Its location does not follow the docs root.

Warmup copies the intent expressed in existing vision, overview, and specifications into a concise project context for owner review, with links to its sources. It incorporates approved decisions that materially shape the project. It records purpose and audience, boundaries, permitted variation, an acceptance example, open questions, and binding sources. A canonical vision can remain authoritative: name its repository-relative path in Binding sources. Modules usually refine project intent through their contract responsibilities, without another mandatory intent page.

Confirmed intent is separate from conformance. If existing code violates an accepted requirement, preserve that requirement and record corrective work and the enforcement gap. Do not rewrite intent, contracts or valid test expectations merely to make the implementation appear consistent.

Project and module intent

Project context is a self-contained copy of current accepted meaning, with references to its sources. It is not only an index of other documents. It should answer who the product serves, what it owns, what stays outside it, which variations are allowed, and what a successful example looks like. Keep it from turning into a long questionnaire, and keep a useful canonical vision in place. Distinguish an inferred interpretation from an accepted requirement and surface material conflicts for review.

A module normally expresses its narrower intent in its contract’s purpose, responsibility and surface. Add separate module context only when it helps readers; the current approval mechanism is repository-wide, not a hierarchy of independent module approvals. For Contract Graph itself, Vision remains the canonical product-intent statement. This guide explains adoption of intent in repositories; it is not a competing statement of the framework’s mission.

In a greenfield repository, warmup confirms intent and establishes root context without inventing modules. In brownfield and reseed, it compares existing code with accepted meaning and records discrepancies. An empty product-rule catalog or a green graph check alone establishes neither missing intent nor completed adoption.

Keep context current

Project context evolves as approved decisions materially change project direction. Update it and the affected canonical documentation together. Capture changes to purpose, audience, boundaries, supported variation, enduring constraints, and significant tradeoffs, with their rationale. One direction-setting decision can warrant an update. Routine implementation choices, task sequencing, and superseded alternatives do not need permanent entries. Keep current meaning concise.

Every sign-off consolidates relevant approved decisions within the completed scope. Lasting direction goes into .agents/cg/project-context.md. Structural promises go into the owning contract.yaml. Qualifying policy goes into the appropriate architecture, engineering, or product YAML catalog. Context prose does not create a machine-enforced rule. Consumed decision-log entries and obsolete scope-owned decision documents are cleared after the necessary meaning, approval evidence, and links are preserved. Pending decisions, active dependencies, and records that still serve a continuing reader or retention need remain, with that reason stated.

A change to approved context or a binding source requires approval that covers the resulting content. An already-recorded answer can supply that authority only when it covers that content. Approval of one decision does not approve an expanded rewrite.

Review and record

The agent handles the commands and the temporary JSON. The owner reviews the meaning and answers in ordinary language.

1. Complete the page from evidence and resolve material questions. Use None under Open questions when settled. Binding sources is None or a list of repository-relative paths such as docs/vision.md.
2. The agent presents the exact page and binding sources covered by the review snapshot.
3. After actual approval, the retained record is .agents/cg/intent.json.
4. cg intent verify exits nonzero for missing, incomplete, unapproved or changed intent. cg intent status --json explains the state without making approval.

The snapshot covers the full page and explicitly listed sources. Any byte change in those inputs requires renewed review; unlisted linked documents are not transitively included. A meaningful interpretation still needs human judgment; structural validation cannot decide whether a paragraph adequately expresses a product’s purpose.

Installed repositories gate plan, prototype, produce and sign-off admission until intent is ready. Inspection, drafting and clarification remain available while approval is pending.

What the evidence means

The local record attributes a response and detects changed content. It does not authenticate an owner, prove product satisfaction, or independently prevent an agent from editing approval data. For owner-controlled CI, a trusted evidence path can sit outside the proposed checkout. Protect that evidence and CI configuration outside the proposed change if independent approval assurance is required. The framework does not install remote branch protection.

cg verify keeps its existing graph-check exit semantics. It checks the authored graph and registered structural rules; declared product checks are not automatically executed. A passing graph check, fresh intent approval and passing behavioral tests answer different questions. Delivery still needs relevant behavioral evidence and actual acceptance of the agreed result.

Full-file freshness is deliberately conservative: even editorial changes need review because a semantic comparison cannot reliably decide whether product meaning changed. See delivery records for how intent relates to delivery.