FE-1402: Define and rehearse the elicitation completion contract

[lunelson]

🌟 What is the purpose of this PR?

Brunch's interviewer needs a way to tell when the model it is eliciting is complete enough to stop asking, distinct from running out of budget or the expert leaving. This pull request lands the first draft of that completion contract and a manual replay of it over all 44 prefixes of the two baseline transcripts. The draft was written at the level of the coatings-plant domain (a table of twenty demand rows keyed to that plant); the strategy pivot later in this stack (S-007, ADR-0006) found that level wrong and reduced the contract to nineteen invariants on a single function, evaluateCompletion, over kind-level rows. This branch is the record of that draft and the replay; the reduction lands in the FE-1404 branch.

🔗 Related links

• FE-1402: Define and rehearse the elicitation completion contract (internal)
• Parent in this stack: FE-1407 / #9319
• Draft contract as authored here: docs/specs/elicitation-completion.md (rewritten in FE-1404; the version from this branch is preserved at docs/archive/specs/elicitation-completion-2026-08-25-full-draft.md there)
• Replay: docs/evidence/proofs/design/elicitation-completion-rehearsal.md; plain rendering: docs/evidence/proofs/design/elicitation-completion-plain.md

🚫 Blocked by

• FE-1407 / #9319 (stack parent only)

🔍 What does this change?

Adds the completion specification, a 44-prefix replay, and a plain-language rendering; amends plugin-contract.md and the SPEC-LEDGER (§9.5 stays pending until a runtime proof exists). Completion is defined as a version-bound, read-time property of the elicited model, kept separate from stopping, delivery, no progress, budget exhaustion, and licensed deferral. The replay records, prefix by prefix, which demand clauses each transcript satisfies and when.

🏗️ Agent notes

Stacked as #9311 → #9312 → #9313 → #9319 → this branch → #9321 → #9322.

Commit

• b39783ba46 docs(brunch-agent): rehearse elicitation completion

Status under S-007

Reclassified 2026-08-25 as test-bed material, not authority. The domain-keyed DemandTable, where-scoped clauses, and completion-anchor matching are retired by ADR-0006; the invariants they encoded survive in the rewritten elicitation-completion.md (FE-1404 branch) as tests to write against evaluateCompletion(model, mustKnowRows). The replay is a golden-fixture candidate once re-expressed at kind level. Verdict comment posted on FE-1402.

Verification at authoring

Lint, typecheck, 128 unit tests, build, docs-index 7/7, diff check; contract, replay, and legibility reviews passed. Re-verified at the stack tip: 182/182 core tests.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

Reviewed on its own, this branch's elicitation-completion.md and plugin-contract.md describe a contract the top of the stack supersedes; read them as the record of the draft, and the FE-1404 branch for the current text.

🐾 Next steps

FE-1497 (branch ln/fe-1497-controller-read-path, above this stack) implements evaluateCompletion with the nineteen invariants as tests.

🛡 What tests cover this?

• packages/core/test/architecture/docs-index.test.ts — index rows and relative links.
• packages/core/test/architecture/control-surfaces.test.ts — SPEC-LEDGER row grammar.

❓ How to test this?

1. Checkout the branch.
2. Read docs/evidence/proofs/design/elicitation-completion-rehearsal.md against the baseline transcripts under docs/evidence/evaluations/process-model-elicitation/baseline/transcripts/.
3. Run npx vitest run in packages/core.

📹 Demo

Documentation only.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 26, 2026 1:00pm
petrinaut	Ready	Preview	Aug 26, 2026 1:00pm
petrinaut-docs	Ready	Preview	Aug 26, 2026 1:00pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 26, 2026 1:00pm

[lunelson]

• FE-1506: Show captures and completion while a panel elicitation runs #9346 : 2 dependent PRs (#9347 , #9355 )
• FE-1504: Run the process-model elicitor from the Petrinaut panel on one owned document #9345
• FE-1431: Build the plugin authoring surface #9337
• FE-1406: Audit the harness-teaching lineage and propose the fixed-key plugin contract (ADR-0007) #9327
• FE-1497: Build the controller read path and the SDCPN plugin package #9325
• FE-1404: Run condition 3 as the walking skeleton #9322
• FE-1403: Assemble and test the CPS interview guidance #9321
• FE-1402: Define and rehearse the elicitation completion contract #9320 👈 (View in Graphite)
• FE-1407: Catalogue elicitor failures that published measures miss #9319
• FE-1480: Project and realize a CPS model as a Petrinaut SDCPN #9313
• FE-1495: Prevent Brunch TypeScript contracts from drifting #9312
• FE-1494: Keep Brunch strategy and control records coherent #9311
• FE-1437: Move brunch-agent into hashintel/hash with its history #9274
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Low Risk
Documentation-only specification and manual replay evidence; no runtime, auth, or data-path changes. Design may be superseded on later stack branches per PR notes.

Overview
Adds a provisional read-time completion contract for when a target document is “complete enough,” kept separate from stopping, delivery, budget limits, no-progress advisories, and licensed deferral.

New docs: elicitation-completion.md specifies version-bound evaluateCompletion inputs, presence vs slot demand algebra, universal active-anchor support, an evidence-bearing CompletionReport, conservative unevaluable-divergence for diverged slots, and read-time deferral licensing over existing capture/session/delivery authorities (no new persistence). elicitation-completion-rehearsal.md manually replays all 44 FE-1361 transcript prefixes with a versioned CPS demand table, clause ledgers, C1 no-progress at E09, and C2 never-asked ramp-scrap gaps. elicitation-completion-plain.md is the legibility pass.

Updates: plugin-contract.md gains plugin/demand-table versions, typed DemandClause / staticFloor, and pointers to the completion spec. INDEX.md indexes the three artifacts. SPEC-LEDGER.md §9.5 stays pending but records FE-1402 design evidence; runtime proof is still open.

^{Reviewed by Cursor Bugbot for commit 8a8e906. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Merge activity

• Aug 26, 12:53 PM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.