Intent Continuity

An agent sees its task prompt and the workflow’s prompt templates, but not the standing constraints and decisions that govern the project — “never bump the major version”, “always review an agent’s changes before merging”. Those live scattered across CLAUDE.md, design docs, old transcripts, and commit messages, and an agent that doesn’t rediscover them re-litigates settled decisions or violates them.

Intent continuity extracts those durable statements once into plain files under .cloche/intent/ and injects the ones relevant to a given step into the agent’s prompt automatically.

Concepts

Storage

Files are the source of truth — checked into git, reviewable in PRs, editable in any editor. The daemon parses them on demand.

.cloche/intent/
├── domains.yaml            # discovered domain map
├── requirements/
│   ├── req-a3f8.md         # one file per requirement
│   └── req-b91c.md
└── scan-state.yaml         # extraction cursors (last scanned commit, docs, runs)

A sibling .cloche/intent-index/ holds the embedding index — a derived, gitignored artifact that re-embeds any requirement whose content hash or model ID no longer matches.

Requirement file format

Markdown with YAML frontmatter: the body is what the agent reads, the frontmatter is what the machinery reads.

---
id: req-a3f8
status: active            # active | disabled | superseded
superseded_by: ""         # req id, when status == superseded
scope:
  level: domain           # project | domain
  domains: [versioning]
  paths: []               # optional narrowing globs
  languages: []           # optional, e.g. [go]
hints:                    # retrieval-only phrasings; embedded, never injected
  - "when to bump minor vs build number"
  - "is this change a breaking change"
confidence: high          # high | medium | low
user_edited: false        # true once a human touches statement/scope
provenance:
  kind: doc               # doc | transcript | prompt | commit | user
  ref: "CLAUDE.md#versioning"
  extracted_at: 2026-09-13T10:00:00Z
  extracted_by: intent-scan
created: 2026-09-13T10:00:00Z
updated: 2026-09-13T10:00:00Z
---

Never bump the major version unless explicitly told to. Minor bumps are for new major
features and backward-incompatible changes; everything else bumps the build number.

**Why:** Major releases are batched manually at the maintainer's direction.

IDs are req- plus four hex characters and never change, so each requirement keeps its own git log --follow history across rewordings.

Domain map format

# .cloche/intent/domains.yaml
version: 1
domains:
  - name: versioning
    description: Version string management, release process, changelog.
    paths: ["internal/version/**", "docs/plans/*release*"]

Edit it directly, through cloche intent, or in the web console. A scan proposes additions but never removes or rewrites a domain marked user_edited: true.

Extraction: cloche intent scan

Extraction is an agent job, run through Cloche itself. intent-scan is a built-in host workflow compiled into the cloched/cloche binaries, so it works in any project with no setup. cloche intent scan (an alias for cloche run intent-scan) dispatches its six steps:

1. discover-domains — surveys the repo layout and proposes or updates domains.yaml.
2. collect-sources — deterministic, no LLM. Gathers what changed since the last scan: docs (CLAUDE.md, README*, docs/**/*.md, .cloche/prompts/**), unmined run transcripts and task prompts, and new commits. Emits none when nothing is new, so a quiet re-scan is a no-op.
3. extract — writes candidate requirements: statement, rationale, scope, confidence, provenance, and 2–5 retrieval hints each. Only durable, prescriptive intent qualifies — not task-specific instructions or facts derivable from the code.
4. reconcile — decides per candidate: create (novel), merge (already tracked), supersede (contradicts an active requirement with newer evidence; a new file is created and the old one flipped to superseded), or drop.
5. apply-reconcile — writes those decisions and enforces three hard rules regardless of what the agent proposed:
   • A disabled requirement is never re-enabled or superseded away.
   • A user_edited requirement’s statement and scope are never rewritten in place — only supersede may touch it, and only its status.
   • Nothing is ever deleted; superseded is the terminal state.
6. commit — commits .cloche/intent/ and only that path (never git add -A), so a scan never leaves the worktree dirty. No-ops when nothing changed.

cloche intent scan            # incremental: only material since the last scan
cloche intent scan --full     # force a full domain re-survey

A project can override the built-in by defining its own intent-scan workflow in a .cloche/*.cloche file (to swap the agent or tune timeouts) — project-defined workflows always win over built-ins of the same name.

Incremental scans on task completion. With intent.scan_after_tasks = true (the default), an incremental scan is enqueued after each completed main orchestration run, covering just that task’s prompt, transcript, and commits. These are cheap, and a project is never scanned twice in parallel.

Injection

When assembling a prompt for an agent step, the daemon selects requirements in three stages:

1. Status — only active requirements are visible.
2. Deterministic scope match — level: project requirements are always included. level: domain requirements are included when the domain matches the step’s context: domains whose paths overlap the workflow’s declared repos, or an explicit domains = [...] step/workflow config key.
3. Semantic retrieval — the task description and step prompt are embedded and scored by cosine similarity against every active requirement (statement + rationale + hints). Anything above a per-model similarity floor joins the selection, whether or not deterministic scoping caught it — so a relevant requirement surfaces even with no keyword overlap.

Selected requirements are ordered project-level first, then by similarity score (deterministic-only matches rank by confidence, then recency), and rendered as:

## Standing project requirements

These are established constraints and decisions for this project. Follow them unless
the task explicitly overrides one. Requirement IDs like [req-a3f8] are for reference;
one you believe is wrong or outdated should be flagged in your output, not silently
ignored.

- [req-a3f8] Never bump the major version unless explicitly told to. ...
- [req-b91c] (container-runtime) Containers must be seeded from a clean per-run ...

A token budget (intent.token_budget, default ~2000 tokens) truncates from the bottom of the ranked list with a (N more requirements omitted; run cloche intent list) marker.

Where the block goes

• If the step’s resolved prompt contains {{ $intent }}, the block is rendered there.
• Otherwise (the default) it is auto-prepended to the prompt.

Both host and container agent steps receive the block. For container steps, the daemon seeds it into the run’s KV store as intent before dispatch, so uncommitted edits to .cloche/intent/ apply even though the container is seeded from a clean git snapshot. Injected requirement IDs are recorded per step in the run KV as <workflow>:<step>:intent, so a run’s detail view can show exactly what an agent was told.

Opting out

Set intent_tracking = false at the workflow or step level:

workflow "develop" {
  intent_tracking = false
  ...
}

step implement {
  prompt          = file(".cloche/prompts/implement.md")
  intent_tracking = false
  results         = [success, fail]
}

An opted-out step or workflow also has its logs excluded from collect-sources’ transcript mining, so sensitive output never seeds requirements. To disable injection project-wide, set inject = "off" in the [intent] table of config.toml.

Embedding backends

Semantic retrieval runs entirely locally and daemon-side — no tokens and no network calls at injection time. Adapters resolve in this order (first available wins):

intent.embedder in config.toml pins resolution to one adapter; unset uses the chain above. When no embedder is available, selection degrades gracefully to status + deterministic scoping + keyword retrieval, with a one-time warning in the daemon log. The feature never blocks a run on embedding availability. Only cloched links an embedder; cloche, clo, and cloche-agent stay pure Go.

CLI: cloche intent

All mutations are plain file edits under .cloche/intent/, visible in git diff; only scan talks to the daemon. preview is the first thing to reach for when selection surprises you. See the CLI reference for full flag detail.

Web console

Press i or click the Intent header button in the web console to open the Intent view over the current project: the requirements table with an edit drawer, the domain editor, and a Scan now button that shows the dispatched run’s id and live state, with a link to that run in the stack.

The Ledger overlay (l) has a Requirements section cross-referencing requirements with the tasks whose steps ran with them injected, and the reverse index from task to requirement IDs.

Configuration

The [intent] table in config.toml (see the configuration reference):

Adopting on an existing project

cloche init never creates .cloche/intent/. With scan_after_tasks at its default, the first completed main task bootstraps it automatically. To adopt by hand instead:

cloche intent scan --full
cloche intent list

Review what was extracted (cloche intent show <id>), edit or disable anything wrong, and commit .cloche/intent/. From then on injection is automatic and incremental scans keep it current.