Skip to content

FE-1402: Define and rehearse the elicitation completion contract #9320

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lunelson merged 1 commit into from
Aug 26, 2026
Merged

FE-1402: Define and rehearse the elicitation completion contract #9320

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions libs/@hashintel/brunch-agent/docs/INDEX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,9 @@ control loop is [`docs/agents/steering.md`](agents/steering.md).
| [notes/deep-read-fe-1389](evidence/proofs/audits/deep-read-fe-1389.md) | active | FE-1401 / findings in FE-1420 | Deep-read of the walking skeleton: builder's account, spec-discharge table (issues 10/13 capabilities discharged; markdown floor contradicted in the UI), 12 findings; source of PR #10's backfilled record |
| [notes/deep-read-fe-1390](evidence/proofs/audits/deep-read-fe-1390.md) | active | FE-1401 / probes on FE-1419 | Deep-read of the capture store: spec-discharge table, write-time tiering assessment (penciled item 7), the FE-1405 status-arity answer, and live-probed confirmation of FE-1419's capture-store claims plus one new aliasing hole; source of PR #11's backfilled record |
| [plugin-contract-spec](specs/plugin-contract.md) | active | FE-1431 (spec issue); decided on FE-1405; amended by FE-1480 | Provisional spec: a plugin is two schemas and two tables over the three-register IR; code-bearing projections add a deterministic scaffold, typed obligation sidecar, and loss report before downstream realization; strains 4–7 and envelope pressure #2 remain open |
| [elicitation-completion](specs/elicitation-completion.md) | active | FE-1402 | Normative provisional read-time contract: version-bound presence/slot demand algebra, universal active-objective support, evidence-bearing boolean report, conservative divergence diagnostic, and pure deferral licensing over existing authoritative surfaces |
| [elicitation-completion-rehearsal](evidence/proofs/design/elicitation-completion-rehearsal.md) | active | FE-1402; inputs FE-1403/FE-1404/FE-1431 | Manual clause-level replay over all 44 FE-1361 prefixes using a versioned provisional CPS DemandTable, separate failure-occurrence/repair clauses, evidence-proxy deltas with carry-forward, C1-E09 no progress, C2 ramp scrap, and successor evidence |
| [elicitation-completion-plain](evidence/proofs/design/elicitation-completion-plain.md) | active | FE-1402 legibility snapshot | Reviewer-facing plain-language rendering of version-bound completion, presence versus slot checks, conservative divergence, stopping/delivery boundaries, and read-time deferral licensing without new persistence |

## Control, architecture reference, and migration archive

Expand Down
2 changes: 1 addition & 1 deletion libs/@hashintel/brunch-agent/docs/control/SPEC-LEDGER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ states.
| Per-session state = evidence log, swept high-water mark, pending-affordance slot | §9.2 | **discharged** | pending slot (FE-1389), durable session-log archive (FE-1391), and FE-1392's parse-validated high-water/last-judged bookkeeping under one `sweepHighWater` state slot |
| Re-entry briefing; user-visible insertion notice | §9.3 | **pending** | signal carrier proved; no briefing; the one injected signal is filtered out of the UI. Owned by FE-1396 |
| Only the true user's side is evidence; injected entries structurally non-user | §9.4 | **partial** | FE-1391 verifies role/purpose against the public projection, refuses signal/advisory text, and classifies affordance replies only from the harness-owned reply-binding signal. The kickoff remains a machine-authored `user` entry until FE-1420/FE-1385 move it to `useInitialData`; FE-1396 still owns briefing-never-evidence |
| Completion derived, never a gate | §9.5 | **pending** | — |
| Completion derived, never a gate | §9.5 | **pending** | FE-1402 defines completion as a version-bound, read-time derivation over demand clauses and active-objective evidence in [`elicitation-completion.md`](../specs/elicitation-completion.md), then manually replays every prefix of both FE-1361 transcripts in [`elicitation-completion-rehearsal.md`](../evidence/proofs/design/elicitation-completion-rehearsal.md). No progress, stopping, durable delivery, and deferral licensing remain distinct from completion; runtime implementation and mounted proof remain open. |
| Storage port: harness-defined, binding-implemented, plugin-blind (C1) | §9.6 | **discharged for the local target** | core owns capture/archive/anchoring semantics; `binding-flue` owns the file implementation; plugins cannot import the binding (FE-1390 + FE-1391) |
| Port scope includes the session-log archive | §9.6 | **discharged** | FE-1391 provisions a versioned target-document record containing capture state and session logs, migrates the legacy capture-only shape on mutation, parses both halves on read, identity-versions evolving messages, and retrieves every cited ordinal independently of Flue |
| Compaction vs. durable log | §9.7 | **partial — source-settled, behavioral pin open** | Flue 2.0.3's append-only stream contract and implementation show compaction appends a canonical record, rewrites only model context, preserves the public message projection, and leaves `state_write` reduction untouched. The source-read record reshapes FE-1386 to one upgrade pin; `test/open-gaps.ts` remains until behavioral proof lands |
Expand Down
141 changes: 141 additions & 0 deletions ...hintel/brunch-agent/docs/evidence/proofs/design/elicitation-completion-plain.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
# Completion without pretending the conversation is finished

This is the plain-language rendering of the provisional
[target-document completion contract](../../../specs/elicitation-completion.md). The specification
is the required-behavior authority. This rendering is a legibility check: it explains the same
rules without the declaration notation and records where that translation strained.

## The short version

Brunch does not decide that a model is complete because the interview went well, the user left, a
turn limit fired, or an artifact was delivered. It decides by looking at the model it has derived
from durable evidence and asking whether that model can answer the user's active objectives to the
depth the plugin requires.

The answer is recalculated from one target-document revision and one immutable plugin/demand-table
version. It is a boolean plus an explanation. The target-document stays editable either way; a
changed document or changed demand version requires a new calculation.

## What gets checked

Every plugin declares a small permanent floor. The provisional process-model replay uses separate
existence/count checks for objectives, entities, activities, and a process path, then checks the
path's sequence at the required grade. Existence is not faked by asking a slot-only rule to select
something.

The plugin also declares what different objectives need. A breakdown-reshuffle question needs line
capabilities, calendars, failure occurrence, repair duration, and the rules used when resources
conflict.
An idle-versus-washdown question needs release rules, changeover behavior, lateness consequences,
and the scrap caused by changing family. A split-run question also needs minimum run sizes and the
extra changeover and scrap paid by every split.

There are two requirement forms. A presence rule says how many model nodes a scope must select. A
slot rule says four important things:

1. which model slots it applies to;
2. how specific the answer must be;
3. which kinds of evidence are allowed to support it; and
4. whether any explicit kind of absence counts as a legitimate answer.

The check fails if a slot rule finds no applicable slot. Separately, every active objective must
match at least one demand row. This matters because neither an empty search nor an unknown
objective may look like perfect coverage.

## What counts as an answer

A stated value counts only if it is specific enough, is supported by active evidence, and has an
allowed evidence status. A guess does not become user evidence because it is precise. Confidence
does not substitute for specificity.

An explicit absence can count only when the plugin says that exact absence answers the question.
“Not applicable” may be a complete answer for some slots. “We will find out tomorrow” normally is
not. A fact that was never mentioned cannot be turned into an absence after the fact.

An unresolved conflict does not count. The current `diverged` shorthand for prescribed versus
practiced behavior does not expose each side's grade and support, so a demanded diverged slot also
fails conservatively as unevaluable. FE-1431 must first make both constituents inspectable before a
plugin can choose a later “both sides” or “either side” rule. The explanation names every selected
coordinate, capture, issue, and reason behind the result.

## What happens when the user must leave

The user can always stop a session. That does not make the model complete and it does not make the
stop a failure.

Brunch should give the user the best useful result it can produce now. It should show the gaps,
save the evidence and open work through the authorities that already own them, and stop asking
questions. If work will continue later, the session controller computes a licensing report. It
checks the exact capture-store revision and located issues or absences; the archived session log,
swept high-water mark, and unswept tail; the existing pending-affordance slot; and a durable
projection reference. Each blocker must point either to an existing model coordinate or, when no
node was selected, to the unresolved clause and scope. Missing or stale facts make licensing fail.
The report binds everything it inspected but is not itself stored as target-document truth.

No current authoritative record can promise an undelivered result with a durable reason, owner,
and next action. For now Brunch can license deferral only after it has actually emitted the best
current projection durably. A future undelivered-delivery obligation needs an approved durability
owner; it cannot be smuggled into an issue or a new completion record.

The order is concrete: settle and sweep what can be settled, archive the session and any bounded
tail, recompute completion, locate every blocker, deliver durably, validate the re-entry and pending
affordance facts, compute the report, and only then quiet. Re-entry reloads those same authorities
and recomputes instead of consuming a new deposit record.

Delivery is separate too. Brunch may deliver an incomplete model with visible loss. It may also
compute that the evidence is complete before the requested artifact has been delivered. The
controller should react to those facts, but it cannot use one to manufacture the other.

## How the two baseline runs fail

Condition 1 confirmed useful scheduling-policy evidence at E06. E07 and E08 then added no demanded
material, and at E09 a time-pressure cue was followed by interviewer-initiated stopping. The
rehearsal's third-prefix rule therefore raises no-progress at E09, before the eleven interviewer
turns E10-E20 spent saying goodbye, parking the thread, and exchanging acknowledgements. It should
have forced a choice: deliver the caveated model, ask a materially different question, save and
defer, or stop. It should not have declared completion. When forced wrap finally demanded the
model, the model appeared immediately, exposing a delivery stall rather than proving an absence of
generative capability.

Condition 2 did better interviewing and produced a polished final specification. It still never
asked about ramp scrap. Ramp scrap matters to the idle-versus-washdown and split-run objectives, so
the plugin's demand exposes the hole even though the interviewer never listed it. The artifact's
claims that it is complete and runnable do not participate in the calculation.

Both runs proposed future work. On the real architecture, multiple sessions are valid. In these
baseline runs, however, the best current projection had not been durably delivered before quieting,
and the required archive/high-water/blocker/pending-affordance facts were not available as one
validated read. The deferrals were therefore unlicensed, not because planning a later session is
inherently wrong.

## Failure boundaries a reviewer can inspect

- A stop, a delivery, a quiet request, a budget limit, and a no-progress signal each leave the
completion boolean untouched.
- Every active objective must have a plugin demand row.
- Presence clauses must meet their cardinality; slot clauses must select at least one real slot.
- Required slots must meet both evidence-status and grade rules.
- Never-asked ramp scrap keeps condition 2 incomplete.
- The rehearsal-only no-progress advisory begins at C1-E09 and never fires in condition 2; it
requests adjudication and never supplies a positive completion verdict.
- Deferral is licensed only when existing authoritative state supports recoverable re-entry and
the best current projection has already been durably delivered.

## Strain found while rendering

1. **“Required grade” was too easy to read as evidence quality.** The contract now states that
grade narrows a value's interpretation space, while epistemic status says where it came from;
demands must declare both independently.
2. **“Every demanded slot passes” hid existence and empty selection.** The contract now separates
presence/cardinality from slot quality, and a slot rule with an empty selection fails.
3. **“Objective-relative” could leave unknown objectives unchecked.** The contract now fails an
active objective that matches no plugin row.
4. **“Deferred with gaps” sounded like a conversation promise.** The contract now projects a
reproducible answer from existing authorities and refuses to license undelivered work; it adds
no persistence shape or delivery-obligation lifecycle.
5. **The simple `diverged` shorthand hides evidence on each side.** The current computation now
fails it conservatively; evaluable constituents and the intended later all/either rule remain
successor work.

The rendering found no need for a new public lifecycle-status enum. A boolean completion answer,
an evidence-bearing explanation, and separate observed events are sufficient for this rehearsal.
Loading
Loading