| name | freeze |
| description | Use when a pipeline stage or the human meets facts that live outside the repo — a service, database, queue, third party, or live logs — and the work depends on their current state. Repo-local work skips it. |
Freeze the moving cross-boundary state a system depends on into one immutable snapshot. Consumer: the agent stages (intent / shape / delegate / execute) — grounding, not narration.
Contract
- INPUT — a system to ground + the work order (intent). Doubly scoped: only the slice of the world this work order touches, never a general map.
- GATE — "Is the snapshot factual and complete — every required fact observed, or an explicit gap?" Agent audits, user locks.
- OUTPUT — a snapshot VALUE, emitted in conversation. Stateless: nothing persisted; re-run to refresh.
Observed-or-gap, never inference
A fact's value is OBSERVED or it is a GAP. No third path.
- Inference builds the source map only — WHICH facts matter. It never produces a fact's value.
- Observed = a read-only acquisition agent sees it live, or the human retrieves it by hand. A fact with no
observed-by is a GAP by construction — that field is what separates the two.
- An unreachable fact becomes an OPEN gap with retrieval instructions, never a fabricated value.
Snapshot shape
- OBSERVED facts — each
{ source, claim, where-it-lives, as-of, observed-by }.
- OPEN gaps — each
{ required-fact, why-needed, where-to-look, how-to-retrieve }.
- Any map/belief over the facts is a VIEW, marked derived, never mixed into the observed set.
Work loop
- Scope — from system + intent, infer the source map: the external facts this work order depends on. The only place inference runs.
- Acquire — fan out read-only acquisition agents in parallel, one observation per fact, live (rules below).
- Fold — each return → an OBSERVED fact; anything unobserved → an OPEN gap with retrieval instructions.
- Gap-fill — surface gaps for the human to hand-retrieve; re-fold; recheck. Human-gated, no metric, no unsupervised run — does NOT pass through target. Ends when gaps close or the human stops; a snapshot with named open gaps is a valid lock.
- Gate — audit below.
Acquisition agents
Spawn acquisition agents and fold their returns — never read external systems yourself.
- READ-ONLY hard guard — observe, never mutate. No write, no state-changing POST, no migration, no toggle. An agent that would mutate → stop; make it a gap for the human.
- Independent facts go out as parallel agent calls in one message.
- Each prompt self-contained: the one fact, where it lives, the read-only constraint.
Decision prompts
Closing unknowns — three modes, one boundary:
- EXPLORE the accessible surface: any answer retrievable with certainty (repo reads, docs, web, parallel subagents) is retrieved, never asked. Return with decisions, not raw findings.
- ELICIT the user: only judgment calls no accessible surface can settle (their goal, taste, a tie between viable paths). Each AskUserQuestion carries as many concrete candidate answers as the decision genuinely has, plus a uniform "Gather facts" escape hatch as a first-class option (never hidden behind Other). Everything needed to answer lives inside the question UI — question text, descriptions, previews — never in prose before the tool call (the dialog hides it).
- INTERVIEWING is the anti-pattern: serial quizzing, generic checklists, asking what exploration could answer.
Re-entry after a detour: if the detour made the answer obvious, state the decision and proceed; otherwise re-ask the same question with the new evidence inside the prompt.
The gate
- Factual pass — every OBSERVED fact traces to an observation (agent return or human hand-retrieval). An inferred value is a defect: demote to OPEN gap or re-acquire.
- Completeness pass — every source-map fact is OBSERVED or an OPEN gap. A silently absent required fact is the failure mode; name it as a gap.
- Verdict-FIRST via AskUserQuestion: PASSES or FAILS, then observed count and open gaps — proof both passes ran.
- On FAIL: name exactly which facts are inferred or missing. Never fabricate a value to close a gap.
Boundaries
- On-demand, not mandatory — any stage invokes freeze on outside-the-repo facts; repo-local work skips it.
- freeze vs over — freeze is world→pipeline grounding (acquire external facts, feed the agent stages); over is output→human handoff. Complements, never folded together.
