Skip to content

INTENT.md

Latest commit

 

History

History
51 lines (38 loc) · 5.27 KB

INTENT.md

File metadata and controls

51 lines (38 loc) · 5.27 KB

⏺ Statement of Intent

Problem

When an LLM produces correct implementation instructions, a second LLM pass during execution corrupts them by injecting its own ideas — adding
unrequested abstractions, renaming things for "clarity," editing outside scope. The good plan gets destroyed by helpful creativity at apply time.

Solution

Separate reasoning from mutation with a review gate between them. The architecture is three phases:

  1. Contract generation — An LLM explores the codebase freely, using fff's MCP tools (grep, find_files, multi_grep, get_workspace_context) to
    understand what exists. It produces a single, frozen contract: exact files, exact edit targets as anchored patterns, atomic implementation steps, validation checks, and a fallback rule if context was insufficient. WorkspaceContextBuilder (crates/fff-core/src/context.rs:114-212) provides the
    initial signal — frecent files, git-dirty files, recently modified files — so exploration starts from what matters, not from scratch.
  2. Human review — The contract is the review artifact. Every file touched, every edit specified, every validation step listed. Nothing hidden. If the contract is wrong, it gets rejected before any code is mutated.
  3. Mechanical execution — A dumb executor applies the contract. No LLM. It parses the contract schema, matches anchors in files (using the same pattern-matching infrastructure as fff-core's grep engine in crates/fff-grep/), applies replacements, runs the listed validation steps, and reports pass/fail. If an anchor doesn't match, it fails — it does not improvise.

What this replaces

This does not replace edit. It replaces the LLM deciding what to read and edit during the run. edit becomes the executor of the contract, not an
autonomous agent.

Why this codebase supports it

  • ContextSnapshot (context.rs:19-27) already resolves "what matters in this workspace" to a concrete set of ranked files with git status and
    modification times — the input signal for contract generation.
  • The MCP server (crates/fff-mcp/src/server.rs) already exposes structured search tools over stdio — the contract-generating LLM uses these as a
    client during phase 1.
  • The fff-core / fff-mcp split keeps workspace logic separate from transport — a Contract struct belongs in fff-core alongside ContextSnapshot, exposed through fff-mcp as a tool.
  • The grep engine (crates/fff-grep/) provides the anchor-matching capability the dumb executor needs to locate edit targets without LLM assistance.
  • The file watcher (crates/fff-core/src/background_watcher.rs) and git-dirty tracking enable a pre-execution staleness check: has any contract
    target file changed since the contract was generated?

The contract must include

  1. Exact files involved
  2. Exact edit targets (anchored patterns, not line numbers)
  3. Atomic implementation units
  4. Tool-use instructions for the executor
  5. Validation steps
  6. Fallback/expansion rule if context is insufficient
  7. Rejection of edits outside the contract's declared scope

gitnexus? claude-rs?