From 0fdafa63d1f7c62a15f74578ca09a406ae846aad Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Tue, 25 Aug 2026 15:59:39 +0200 Subject: [PATCH 1/3] Audit the harness-teaching lineage and propose the move-heading contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The question of who teaches the interviewer how to interview — as distinct from what to notice in a formalism — has been written down fifteen times since 2026-08-06 under eight vocabularies and assigned to five layers, and kernel §11.5's rule that "guidance ownership follows vocabulary ownership" was affirmed at every station and designed at none. The audit (docs/evidence/proofs/audits/harness-teaching-lineage-audit.md) records each form, the words it used, the layer it chose, and its fate, from three full-read sweeps of the corpus plus the Linear record; its findings are that the moves were never enumerated in canon, that the SDCPN construct runbook is mostly harness craft filed in a plugin, and that sequence and selection were always both present and never separated. ADR-0007 (status: proposed, awaiting ratification) pulls the layers into one structure: the plugin splits by nature into schema-validated contract data, a per-job runbook under eight fixed harness-owned move headings, and a harness repertoire of defaults rendered before plugin cells. Headings are typed procedure / repertoire / anchor, which is Principle v2 applied heading by heading; the repertoire headings are where the interviewer selects against the posture kickoff produces. It amends ADR-0006 decisions 2 and 5, preserves ADR-0002 N2, Layer B's derived ordering, and completion rule 15, and restores FE-1406 to its original question. Both documents have INDEX rows; the docs-index and control-surface gates pass. Co-Authored-By: Claude Fable 5 --- libs/@hashintel/brunch-agent/docs/INDEX.md | 2 + ...s-plugin-content-at-fixed-move-headings.md | 148 ++++++++++ .../audits/harness-teaching-lineage-audit.md | 273 ++++++++++++++++++ 3 files changed, 423 insertions(+) create mode 100644 libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md create mode 100644 libs/@hashintel/brunch-agent/docs/evidence/proofs/audits/harness-teaching-lineage-audit.md diff --git a/libs/@hashintel/brunch-agent/docs/INDEX.md b/libs/@hashintel/brunch-agent/docs/INDEX.md index 99322d53cc7..cf236e58c43 100644 --- a/libs/@hashintel/brunch-agent/docs/INDEX.md +++ b/libs/@hashintel/brunch-agent/docs/INDEX.md @@ -67,6 +67,7 @@ control loop is [`docs/agents/steering.md`](agents/steering.md). | [ir-worked-examples](evidence/proofs/design/intermediate-representation-worked-examples.md) | active | gisted in FE-1397 | Layer-A validation across Gherkin/CPS/BPMN + assurance: property verdicts, amendments, sublimation findings | | [ir-design-plain](specs/intermediate-representation-plain.md) | active | strain findings on FE-1401; amended by FE-1480 | Plain-prose rendering of the IR design, including ADR-0005's split between deterministic scaffolding and model-assisted executable realization; notes that `plugin-sdcpn/plugin.md` is now the concrete rendering of Layer B | | [notes/research-patterns-audit](evidence/proofs/audits/research-patterns-audit.md) | active | FE-1401 / card inputs on FE-1403 | Plain-language audit of ~30 research imports in 7 families, evidence-graded, with an 8-point strain appendix | +| [notes/harness-teaching-lineage-audit](evidence/proofs/audits/harness-teaching-lineage-audit.md) | active | FE-1406 (owning issue); input to ADR-0007 | Audit of every prior form of "what the harness teaches" (2026-08-06 → 08-25): fifteen restatements, the vocabulary each used, the layer each chose, and what became of it; finds the §11.5 split rule affirmed at every station and designed at none, the moves never enumerated in canon, and the SDCPN construct runbook mostly harness craft; strain appendix | | [notes/penciled-directions-2026-08-14](archive/planning-inputs/penciled-directions-2026-08-14.md) | settled | FE-1401 | Penciled directions from the legibility session: 8 items with firming actions + editorial reflections | | [capture-store-plain](reference/architecture/capture-store.md) | active | strain findings on FE-1401 | STE-leaning rendering of the capture-store semantics (FE-1390/FE-1389) with a load-bearing not-guaranteed section; 8-point strain report incl. two command-reachable unclosable-conflict paths (confirms FE-1419 commits 7/8) and the FE-1405 status-arity answer | | [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 | @@ -116,6 +117,7 @@ contract requires the spec to carry the new operating truth, in explicitly dated | [0004-in-petrinaut-staging-and-the-monorepo-import](adr/0004-in-petrinaut-staging-and-the-monorepo-import.md) | accepted | FE-1433; amended by FE-1437; extended by FE-1480 | September demo stages inside demo.petrinaut.org; reusable libraries remain mutually unaware; ADR-0005 extends the application-owned artifact path from projection scaffold and obligations to an executable file through Petrinaut client tools | | [0005-model-assisted-sdcpn-realization](adr/0005-model-assisted-sdcpn-realization.md) | accepted | FE-1480 | A pure plugin projection emits an SDCPN scaffold, typed code-obligation sidecar, and loss report; the Brunch agent realizes executable TypeScript through Petrinaut client tools and deterministic compile/simulation gates | | [0006-plugins-per-target-formalism](adr/0006-plugins-per-target-formalism.md) | accepted | design-convergence review 2026-08-25 | Plugins are per target formalism, authored as sectioned Markdown with fixed contract headings and three machine-read tables; domain-neutral by rule; retires the declarative ScopeExpr/firesWhen/DemandTable contract | +| [0007-harness-teaching-meets-plugin-content-at-fixed-move-headings](adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md) | active | FE-1406; drafted 2026-08-25, awaiting ratification | Proposed: a plugin splits into schema-validated contract data, a per-job runbook under eight fixed harness-owned move headings typed procedure / repertoire / anchor, and a harness repertoire of defaults rendered before plugin cells; selection (repertoire, keyed to posture) separated from sequence; amends ADR-0006 decisions 2 and 5 | ## External canonical documents diff --git a/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md b/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md new file mode 100644 index 00000000000..98e9b6ad2d9 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md @@ -0,0 +1,148 @@ +# ADR-0007: Harness teaching meets plugin content at fixed move headings + +Date: 2026-08-25 +Status: proposed — drafted for Lu's ratification; nothing below governs until accepted +Amends: [ADR-0006](0006-plugins-per-target-formalism.md), decision 2 (the `Moves` section is no +longer plugin prose concatenated whole; the machine-read tables become schema-validated data) and +decision 5 (the "later lift" of harness-generic guidance is designed here, and it is not +pattern-shaped) +Preserves: [ADR-0002](0002-topology-and-placement-rules.md) N2 (harness-shipped guidance lives +in `core`), [ADR-0003](0003-three-register-ir.md) (three registers), IR Layer B's rule that +interview ordering is derived from completion rather than taught, and completion rule 15 (whether +a session may stop is session control, never guidance) +Decided on: the `ln/fe-1406-harness-teaching-adr` branch, from the +[lineage audit](../evidence/proofs/audits/harness-teaching-lineage-audit.md); owning issue FE-1406 +(gist: what the harness teaches) + +## Context + +Kernel spec §11.5 has said since 2026-08-11 that **guidance ownership follows vocabulary +ownership**: a plugin teaches what to notice in its formalism; the harness teaches how to work an +interview situation the shared envelope can name. The rule was reaffirmed by FE-1397, ADR-0002, +FE-1406, and ADR-0006's supersession map, and it has never been designed. The +[audit](../evidence/proofs/audits/harness-teaching-lineage-audit.md) finds fifteen restatements, +eight vocabularies, five layers, and no build. What ships today is eight protocol sentences in +`packages/core` followed by the plugin file's prose. + +ADR-0006 put the how-to under the plugin file's `Moves` heading as job runbooks, and by its +decision 2 the harness concatenates that section into the interviewer's instructions unread. The +consequence is visible in the one plugin that exists: of the SDCPN `construct` runbook's six +steps — open with objectives, slice, sweep, probe, keep the ledger, close honestly — five are +generic method that a `gherkin` plugin written to the same contract would have to repeat. The +runbook is mostly harness craft filed in a plugin, because the contract gives the harness no place +to put its own. + +The audit also finds that the idea has always carried two dimensions the record never separated. +One is **sequence**: open before structure, slice before sweep, close by summarising and offering +one correction. The other is **selection**: which probe to use on this answer, whether to slice or +sweep right now, how much to batch, how to phrase the next question for this expert's appetite. +The 2026-08-19 design of FE-1406 stated the selection half precisely — strategy varies with an +interaction posture inferred at kickoff — and the 2026-08-25 rescope dropped it, along with the +one named form of anti-guidance (`rabbit_holes`, 2026-08-14: where _not_ to dig) that survives only +as negations inside steps. + +Meanwhile the read path landed (FE-1497): the plugin-file parser and the proposal-schema +narrowing that hangs off it are 378 lines of hand-written Markdown table reading, with the floor +read by regex over prose and the completion anchor found by naming convention — the size finding +on `STEERING.md` asks whether the machine-read part of the file should be data. + +## Decision + +1. **A plugin has three parts, split by their nature, not by file.** The **contract** is data: + kinds, `Must know` rows, the floor, the anchor, and `Patterns` rows — validated by a schema, + never interpreted by prose rules. The **runbook** is prose under fixed move headings, one per + job. The **harness repertoire** is prose under the same headings, shipped from `core` + (ADR-0002 N2), rendered before every plugin's cells. Guidance ownership follows vocabulary + ownership at the level of the heading: the harness owns every heading and its default; a plugin + owns the cells that name its kinds. + +2. **The move headings are fixed, small, and typed.** Eight headings, in this order, identical + for every plugin and every job. Adding one is an amendment to this record; the generality test + of ADR-0006 extends to them — a second formalism or a third job adds zero headings. + + | Heading | Type | Required | The harness default teaches | A plugin cell may add | + | --- | --- | --- | --- | --- | + | `Kickoff` | procedure | yes | What to establish before structure: objective, why, boundaries, and the expert's **posture** (time, intended use, required confidence, tolerance for proposed assumptions). Never an opening battery (FM-12). | What "no model exists" or "a model exists" means for this job; the kind the objective is captured as; for review, orientation and scope. | + | `Slice moves` | repertoire | no | Walk one concrete case end to end before anything systematic; the bounded opener (three to six steps); the shape comes from the slice. | What one case is in this formalism ("one instance from arriving to leaving"; one scenario). | + | `Sweep moves` | repertoire | no | Make one property hold across one stratum. The completion report is the map of what is unknown, never the order to ask in. End each stratum by asking for absences and for the unwritten rules. | Kind order; which slots go together; what a stratum is here. | + | `Probes` | repertoire | no | Question forms that deepen one answer: the vague quantifier, the story instead of the generalisation, the tension between two answers, the smallest delta to the demanded precision, the "don't know" routed to a source, the universal follow-up ("how would you know that?"). | Formalism-specific forms (the quantile protocol for a spread). | + | `Postures` | repertoire | no | How selection varies with the posture from kickoff: explore openly; synthesise and invite correction; propose low-risk structure and question only high-impact uncertainty. Batch breadth (two to four), sequence depth. A proposal stays a suggestion until confirmed (FM-15). | Usually blank. | + | `Rabbit-holes` | anchor | no | Where not to dig and what looks like progress and is not: asking the expert what you failed to ask; restating the whole model; stating a value the expert did not give; taking a schedule or a document for the practised rule; taking fluency for completeness. | Formalism-specific holes (a continuous quantity that triggers nothing). | + | `Checks` | anchor | no | What the harness enforces so the interviewer need not police it: completion, the sweep list, the assumption ledger, the affected slice. | Job-specific checks the harness owns (for review: trace, scope, projection identity). | + | `Close` | procedure | yes | Completion is computed, not felt; a smooth interview, a busy expert, a delivered document, an exhausted budget, and a complete model are five different things. If the expert must stop, stop. Summarise per kind, state what is missing or assumed, offer one correction. Whether one _may_ stop is session control (rule 15). | The job's named stopping outcomes; the deliverable's shape. | + +3. **Three heading types, and the words for them.** A **procedure** heading holds ordered steps + with checkable completion; it is followed. A **repertoire** heading holds options — each a + when / what it gets / how — from which the interviewer **selects** at the moment, against the + situation and the posture; nothing under it is a sequence. An **anchor** heading holds leading + words for judgment; it is kept in mind. This is Principle v2 — _procedure for mechanism, + anchors for judgment, shapes for output_ — applied heading by heading. "Repertoire" is the word + for the selection dimension and for the harness's document; "quiver" retires as its synonym. + "Runbook" remains the word for one job's `Moves`, whether the harness's default or a plugin's. + "Posture" is the selection input kickoff produces. + +4. **Jobs are harness vocabulary.** `construct` (no model exists) and `review and revise` (a model + exists) are situations the harness can name without any plugin. The harness repertoire carries + one default runbook per job; a plugin declares which jobs it supports and supplies cells under + their headings. A third job is an amendment to this record. + +5. **Rendering interleaves; the harness surfaces and never selects.** For each job the binding + renders, heading by heading in contract order: the heading, the harness default, then the + plugin's cell if it is not blank. Cells add; they do not override a default — a default that a + plugin needs to contradict is a finding about the repertoire. The rule already stated for + patterns ("the harness surfaces; the interviewer decides") governs every repertoire heading: + the completion cue may say what is unsatisfied and which patterns match; it never says "sweep + now." + +6. **`Patterns` stay in the contract, kind-indexed, formalism-owned.** A pattern is a + machine-matchable trigger on node state plus a question; that is what lets the harness surface + it. Guidance whose trigger is conversational — a vague answer, an expert who does not know, the + end of a topic — is not pattern-shaped and belongs under a move heading. FE-1406's five + candidates sort accordingly: P06, P10, and P12 are `Probes` defaults; P09 and P11 are + `Sweep moves` defaults; their ids retire with the rows. + +7. **Admission to the harness repertoire is by evidence.** A default is admitted where FE-1403's + verdict rule holds — it fires where the bare model demonstrably failed, not where instinct + already succeeds — and FE-1407's technique-owned failures are the first three obligations: + `Kickoff` against opening overload (FM-12), `Probes` against unresolved-ambiguity bypass + (FM-14), `Postures` against unlicensed influence (FM-15). Everything else waits for a run. + +8. **Serialisation is not decided here.** This record fixes the split, the headings, their types, + and the meeting rule. That the contract is schema-validated data recommends YAML with a JSON + schema (strict, commentable, plainly readable); that runbook cells are prose the model reads + recommends sectioned Markdown or YAML block scalars under the fixed headings. The + plugin-contract spec records the choice when the implementing issue makes it; the parser reads + headings either way. + +## Condition + +Revisit if a second formalism or a third job needs a ninth heading; if a plugin cell must +contradict a harness default rather than add to it; or if any mechanism needs the harness to +_select_ a move rather than surface the facts a selection is made from. Each is a finding about +the abstraction, decided by amending this record — never by adding a heading to one plugin, a +per-domain cell, or a stored posture field. + +## Consequences + +- **FE-1406 is restored to its original question** — what the harness teaches — with this record + as its design; the 2026-08-25 five-row scope is replaced by decision 6. This is a proposed Linear + edit, not one made here. +- **The SDCPN `construct` runbook shrinks.** Its slice, sweep, probe, ledger, and close steps + become harness defaults; the plugin keeps what one case is, its kind order, and its stopping + outcomes. The `review and revise` runbook keeps its orientation, scope, and checks cells. A + `gherkin` plugin inherits every default and writes cells only; FE-1393's zero-new-headings test + covers move headings. +- **The parser shrinks to a schema and a heading splitter.** The table reading, the floor regex, + and the anchor convention become a schema; the anchor and floor become declared fields. The binding's instruction assembly interleaves per decision 5 instead of + appending the file. +- **The glossary changes on acceptance** (`CONTEXT.md`, per `docs/agents/domain.md`): Runbook is + redefined as the eight typed headings for one job; Pattern gains "machine-matchable trigger on + node state"; the retired Kernel card entry stops asserting that the quiver "becomes + harness-generic patterns"; ElicitationPack's prose sections are the runbook; new entries for + Repertoire, Posture, and Move heading. `SPEC-LEDGER.md` §11.5 moves from pending to designed + by this record. +- **The v0 prompt is recoverable as the first draft of the defaults.** Its seven headings map + onto `Kickoff`, `Slice moves`, `Sweep moves`, `Probes`, `Postures`, `Checks`, and `Close`; the + prompt itself stays sealed as condition-2 input. +- **Anti-guidance gets a home.** `Rabbit-holes` is where the negations now scattered through + steps go, so the steps can be stated positively. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/proofs/audits/harness-teaching-lineage-audit.md b/libs/@hashintel/brunch-agent/docs/evidence/proofs/audits/harness-teaching-lineage-audit.md new file mode 100644 index 00000000000..7e4746d9e88 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/proofs/audits/harness-teaching-lineage-audit.md @@ -0,0 +1,273 @@ +# Where the interviewer's craft was supposed to live + +> An audit of every form one idea has taken in this context: that some of what the interviewer +> is taught — how to open, when to walk one case and when to sweep, how to probe, how to vary +> with the expert's appetite, where not to dig, how to close — belongs to the harness and not to +> any one plugin. Produced 2026-08-25 from three full-read sweeps (specs, ADRs, and control +> surfaces; archive and reference; evidence, evaluations, inbox, agent protocols, and source +> prose) plus the Linear record of FE-1360, FE-1364, FE-1397, FE-1403, FE-1406, and FE-1407. It +> feeds [ADR-0007](../../../adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md) +> and is evidence, not authority: where it quotes a document, that document governs. Counts are +> case-insensitive occurrence counts over the named trees at the audit date. + +## The question + +Brunch has always had a clear answer for _what to notice_: that is the plugin's job, keyed to the +kinds of its target formalism. It has never had a settled answer for _how to interview_. The idea +that the how-to is generic — owned by the harness, the same for `gherkin` and `sdcpn` — has been +written down at least fifteen times since 2026-08-06, under eight vocabularies, assigned to five +different layers, and designed zero times. Each restatement shrank the obligation without +answering it. The most recent (2026-08-25) reduced it to moving five table rows. + +## The forms it took + +Each entry: when, where, what the idea was called, which layer it was put in, what moves it +enumerated, and what became of it. + +**2026-08-06 — the two intake documents.** The agentic-elicitation challenges and criteria +papers (`docs/reference/agentic-elicitation-*.md`) call the craft _lenses_ plus a +_DialoguePolicy_: "the agentic part is primarily deciding which lenses are relevant, what to ask +next, and when to stop." Plugins "contribute domain knowledge without independently taking over +the conversation"; the runtime decides "whether this matters" and "how to phrase the question." +Layer: plugin content, runtime arbitration. Enumerated: eight lenses; a policy with issue +prioritisation, question budget, confirmation thresholds, stop conditions. Fate: lenses became +"agent-native observe"; the question budget was rejected the next day. + +**2026-08-06/07 — kernel issues 04, 05, 07.** The craft becomes _kernel cards_ (Detects / Goal / +contrastive Questions / Artifacts) inside the plugin's ElicitationPack, with the principle that +"agents do better with behavioural guidance than procedural" — refined into **Principle v2**: +_procedure for mechanism, anchors for judgment, shapes for output_, designed against sprawl, +negation-steering, no-ops, and judgment-as-procedure. Issue 05 refuses to mechanise economy: +"economical interviewing is implemented through strategy and judgment guidance in pack kernel +cards." Layer: plugin owns the cards; the harness owns card activation and pack loading. Fate: +the card is retired (ADR-0006); Principle v2 survives as the authoring standard for prose. + +**2026-08-10 — kernel spec §11.1, §11.2, §11.4.** Pack = cards + annotated shapes + completion +contract + _clarification hints_. §11.4 adds brunch-inherited _pattern guidance_: hash-pinned, +ablatable prompt directives ("a load-bearing prompt paragraph as a versioned, testable +artifact") and a private scratchpad that is "not harness session state." Layer: plugin, with an +operator-prompt register for §11.4. Fate: §11.1 superseded → partial; §11.2 superseded → +pending; §11.4 never built, never retracted. + +**2026-08-11 — kernel spec §11.5, added on review.** The split rule is coined: **"guidance +ownership follows vocabulary ownership."** Cards that teach what to notice in a domain are plugin +content; cards that teach "how to work an interview situation the envelope can name" (conflicts, +alternatives, ambiguity, weak or missing evidence, absence clusters) "may ship with the harness as +a **generic strategy quiver**, composed by plugins at authoring time." Explicitly "named, not +designed: milestone one ships all guidance in plugin packs." Reference shapes: brunch's +`ln-grill`, `ln-disambiguate`, and the `elicitation_style: interrogate | disambiguate | propose` +trichotomy. Layer: harness, by rule; plugin, by deployment. Fate: never retracted, never +designed. `SPEC-LEDGER.md` still carries it as "**pending** — was orphaned … now FE-1406." + +**2026-08-11 — the expert meeting.** No in-house interviewing practice existed to harvest ("we +didn't actually do any pattern elicitation"). Dora's requirement — "can we build an architecture +whereby we can update the way the elicitor asks these questions easily" — is recorded as direct +validation of a swappable guidance layer. Fate: activated the literature fallback (FE-1360). + +**~2026-08-12 — the v0 prompt, condition 2.** Self-described as "the degenerate plugin: the +smallest possible pack content, with no machinery behind it." It is the first and still the +clearest enumeration of the moves, as headings: **Objectives first · Slice, then sweep · Probe; +don't settle for the first answer · Ask for absences explicitly · Batch breadth, sequence depth · +Keep an assumption ledger · End properly.** Layer: operator prompt standing in for the plugin. +Fate: merged nearly verbatim into the SDCPN plugin file's `Moves` on 2026-08-25; the prompt +itself is sealed evaluation input. + +**2026-08-12 — grilling inputs.** The first explicit inversion toward the harness. _Facets_ +(declarative, plugin-filled) are separated from _motions_ (procedural, "harness-generic"): +**slice motions** ("one case end-to-end first … slice before sweep") and **sweep motions** ("make +one property hold across one stratum — every activity a duration, every contention point a +policy") and _impact/leverage order_. "Most interviewing-strategy value is generic +(harness / strategy-quiver layer); the CPS plugin is a comparatively thin domain shell." The note +observes that "the motion vocabulary appears original — no KA/RE/conceptual-modelling equivalent +found." Layer: harness. Fate: archived as a planning input, never ticketed. + +**~2026-08-12 — the FE-1360 literature deposit.** Some thirty imports, each filed under the +recurring heading "pack-content candidates" and written as cards (opening-five, mean-or-tail +router, knowledge-audit sweep, premortem, exception sweep, definition-of-done, an explicit +anti-card "do not synthesise from the catalogue", probe-depth policy, anti-batching guard, +vagueness guard). Two rules bear on layering: "build a small quiver with variant selectors, not a +long menu," and one universal follow-up ("how would you know that?") that "upgrades every other +card." Four cognitive stopping rules, with the warning that representational stability — stop +when the model stops changing — is the one an LLM will implement by default and one of the two +associated with premature stopping. Layer: pack, with the generic inversion implicit. Fate: +active reference; most cards later dispositioned out at the desk. + +**2026-08-13 — IR Layer B and the baseline readout.** Two decisions cut in opposite directions. +The IR keeps the _motif quiver_ "in the ElicitationPack as question guidance only — scaffold yes, +generator no," and makes interview **ordering a derived consequence of question-relative +completion rather than a taught sequence**, replacing PRO-98's fixed category order. FE-1397's +routing verdicts formalise §11.5: "routes only the _technique_ to the generic quiver … the _kind_ +stays in each plugin's catalog," and "a kind migrating to the harness is a finding, not a +failure." The same day the readout concludes that "everything both conditions still get wrong … +is a thing a prompt cannot fix and the harness/plugin design claims to." Layer: technique to +harness, kind to plugin, adjudication to machinery. Fate: the ordering decision became ADR-0006 +decision 3 and completion rule 5; the quiver routing was never acted on. + +**2026-08-14 — penciled directions.** The richest single form. A plugin manifest with twelve +keys — `licenses`, `techniques`, `movements (slice_moves, sweep_moves)`, `scopes_and_motifs`, +`rabbit_holes`, `failure_modes`, `smells`, `lenses`, `checks`, `tools`, `ontology`, `schema` — and +an **ownership sort per key**: "generic licenses and failure modes are quiver/harness-side; domain +instances are plugin-side … 'you may press a busy expert' is an envelope-vocabulary license +(quiver-side) while 'press on tint-qualification claims' is the same key plugin-side." Three +prompt mechanisms (license, technique, attention). Two core modes — objectives capture with a +slice-and-trace bias and systematic extraction with a sweep bias — that "must present as +postures, not a state machine." An incorporation rubric whose hardest axis is _trigger accuracy_: +"a card that can't say when it fires is sprawl." And the observation that "`rabbit_holes` is +quietly the most novel key: anti-guidance — where _not_ to dig — which nothing in the imported +literature covers." Layer: split per key. Fate: the `firesWhen` and `technique` hook points +landed in the declarative contract and were retired with it; `rabbit_holes` appears nowhere else +in the corpus. + +**2026-08-17 — the Flue cheatsheet and ADR-0002 N2.** The delivery mechanism is decided: "Flue +skills _are_ the card-delivery mechanism … do not invent a card loader inside the harness." +Topology rule N2: plugin content ships from plugin packages; "quiver (FE-1406) content is +harness-shipped: same rule, exported from core (or a `packages/quiver`)"; never per-agent +`skills/` directories in the app, and the boundary gates enforce it. Layer: binding delivers, +harness ships. Fate: active and gated; the content it would deliver was never written. + +**2026-08-18 — ADR-0003.** The plugin contract becomes purely declarative — model schema, +proposal catalog, fold table, demand table. This version has no guidance surface at all. + +**2026-08-19/20 — FE-1406 scope settled; FE-1403 and FE-1407 framed.** FE-1406's body is the +sharpest statement of the harness half. Kickoff "is a form the agent fills implicitly": objective, +why, boundaries, and "the interaction posture inferred from available time, intended use, +required confidence, and tolerance for agent-proposed assumptions." **"Strategy varies with the +inferred posture: explore openly when appetite is high; synthesise and invite correction when it +is constrained; propose low-risk structure and question only high-impact uncertainty in mixed +cases."** The shared capability set is ask, propose, contrast, expose assumptions and gaps, +capture corrections, stop with visible gaps; "the quiver says how to combine those capabilities … +the agent chooses among applicable strategies." FE-1403 tags cards `envelope-generic` "so they can +graduate to the harness quiver instead of being lost in the CPS pack," with the admission test +"does it fire at a moment where the baseline demonstrably failed, or where the bare model already +succeeded?" FE-1407's catalogue assigns every failure an accountable layer — disposition, +technique, or machinery — and finds twelve of fifteen are machinery; technique owns **FM-12 +opening overload, FM-14 unresolved-ambiguity bypass, FM-15 unlicensed influence**. Layer: +harness for the quiver, with graduation staged through the plugin. Fate: the FE-1406 text was +moved under a "Superseded" banner on 2026-08-25. + +**2026-08-24 — S-005 and the completion rehearsal.** The teaching is split three ways as queue +items: FE-1403 domain guidance, FE-1406 quiver, FE-1404 instrument with an activation matrix. The +rehearsal fixes the machinery side: "completion, delivery, stopping, deferral, and no-progress +remain separate computed or observed facts. Guidance owns none of their adjudication." + +**2026-08-25 — FE-1403's desk replay, then ADR-0006 and S-007.** Of the card candidates, six +survive and eleven are rejected as redundant-with-instinct, untestable-at-desk, or superseded by +machinery; the one generic survivor (GEN-Q02, bound a question batch) is "a candidate for FE-1406, +not already-graduated harness strategy." The same day ADR-0006 collapses everything into one +sectioned file per target formalism: cards become `Patterns` rows; clarification hints become +`Moves` steps; `Moves` are job runbooks — "kickoff, trajectory, checks, and stopping" — and +"harness-generic patterns may later lift into a harness repertoire (FE-1406, gist: strategy +quiver)." The `domain` tag is ruled a mis-tag. FE-1406 is rescoped to moving P06, P09, P10, P11, +P12 into "a harness-level repertoire document." Completion rules 15–19 move stopping into session +control. In the production path, harness-owned teaching is the ask, settlement, and completion +instruction fragments in `packages/core` — about eight sentences — followed by the plugin file's +prose, concatenated. + +## The words + +The same concept under different names, in order of appearance. Counts are across the +documentation and source trees at the audit date. + +| Concept | Names it has carried | Where it stands | +| --- | --- | --- | +| The unit of guidance | kernel card (27 in archive/reference, 11 in canon) → interview card → attention / technique / license card → pattern row (`Patterns`, ~190) | Card retired; pattern row is the unit, kind-indexed, "surfaced, never mandated" | +| The harness-generic half | DialoguePolicy → generic strategy quiver (5) → motions, "harness-generic" (9) → quiver-side manifest keys → harness repertoire (2) | Named in §11.5; ledger "pending"; FE-1406 reduced to five rows | +| The ordered part | clarification hints (6) → `Moves` steps → runbook (kickoff · trajectory · checks · stopping; 5) | Container defined; contents plugin-authored | +| Slice and sweep | "Slice, then sweep" (v0) → slice motions / sweep motions → `movements (slice_moves, sweep_moves)` → `Moves` steps 2 and 3 | Never in canon; only in the v0 prompt, two archived planning notes, and the plugin file. `sweep` collides with the harness capture operation (~280 mechanism hits against ~50 for the move) | +| Where not to dig | `rabbit_holes` (2, one line pair) → "redundant-with-instinct" dispositions → negations inside `Moves` steps ("do not sweep before it", "Do not ask the expert what you have failed to ask") | Named once as a key; survives only as negation-steering | +| The listener | question budget (rejected) → appetite / interaction posture → `elicitation_style` trichotomy → "postures, not a state machine" → "batch two to four" | Settled in FE-1406 on 08-19; superseded 08-25 | +| Stopping | End properly → Close honestly → `HINT-RESPECTFUL-CLOSE` → completion rule 15 | Whether one _may_ stop is session control; how to close well is prose | +| The trigger | Detects (21) → `firesWhen` (11, retired) → `when` column | Hardest slot to fill (penciled rubric); conversational triggers have no machine form | +| Zero hits | `runbook` before 08-25 · `rabbit-hole` outside the penciled note · `fixed heading` before ADR-0006 · `trick` · `tangent` · `interviewing craft` · `operator prompt` | — | + +## Where the layer was put, by date + +| Date | Source | Layer for the how-to | +| --- | --- | --- | +| 08-06 | intake papers | plugin content, runtime-arbitrated | +| 08-06/07 | kernel issues 04, 05 | plugin cards; harness activates | +| 08-10 | kernel §11.1–11.4 | plugin; §11.4 operator-prompt register | +| 08-11 | kernel §11.5 | **harness by rule** (envelope vocabulary), plugin by deployment | +| 08-12 | v0 prompt | operator prompt ("degenerate plugin") | +| 08-12 | grilling inputs | **harness** (motions), plugin (facets) | +| 08-13 | IR Layer B, FE-1397, readout | technique → harness; kind → plugin; adjudication → machinery; ordering derived, not taught | +| 08-14 | penciled manifest | split per key by ownership sort | +| 08-17 | ADR-0002 N2, cheatsheet | binding delivers; **harness ships quiver content** | +| 08-18 | ADR-0003 | no guidance surface | +| 08-19/20 | FE-1406, FE-1403, FE-1407 | **harness** (posture-varied strategy); plugin stages generics for graduation; machinery owns 12/15 failures | +| 08-24 | S-005 | three queue items: domain spec, harness quiver, evaluation instrument | +| 08-25 | ADR-0006, S-007 | **plugin file** under fixed headings; harness repertoire "later"; FE-1406 → five rows | +| 08-25 | completion rules 15–19 | stopping → session control | + +The trajectory: plugin (08-06 → 08-11) → harness by rule (08-11 → 08-20, four independent +restatements) → machinery absorbs adjudication (08-13, 08-20, 08-24) → plugin file absorbs the +prose (08-25). The harness half was affirmed at every station and built at none. + +## What never found a home + +1. **The split rule is canon and was never designed.** §11.5's "guidance ownership follows + vocabulary ownership" (08-11) was reaffirmed by FE-1397 (08-13), ADR-0002 N2 (08-17), FE-1406 + (08-19), and the kernel supersession map (08-25: "unchanged in principle"). It has an owning + issue and a ledger row. Each rescoping shrank the deliverable — from a designed quiver, to + graduated cards, to five relocated rows — while the rule itself stood. + +2. **The moves were never enumerated in canon.** Specs, ADRs, and control surfaces name the + container (`Moves`, runbook, kickoff/trajectory/checks/stopping) but never the moves. The four + documents that do — the v0 prompt, the grilling inputs, the penciled manifest, and the SDCPN + plugin file — are respectively sealed evaluation input, archived, archived, and one plugin. + +3. **The SDCPN construct runbook is mostly harness craft filed in a plugin.** Of its six steps, + Open with objectives is generic in method (the `objective` kind is the only formalism-specific + word); Slice is generic; Sweep is the generic move over the plugin's kinds; Probe is generic; + Keep the ledger and Close honestly restate harness rules. A `gherkin` plugin written to the + same contract would repeat five of six steps — the exact outcome FE-1403's tagging was meant to + prevent. + +4. **Two dimensions were always present and never separated.** One is _sequence_: open, then + slice, then sweep, then close — Principle v2's "procedure for mechanism." The other is + _selection_: which probe to use, whether to slice or sweep now, how to phrase the next question + for this expert's appetite — "the agent chooses among applicable strategies," "postures, not a + state machine." The v0 prompt listed both kinds as sibling headings; the manifest sorted keys by + owner but not by this axis; the runbook glossary names only the sequence. + +5. **Anti-guidance was named once and lost.** `rabbit_holes` (08-14) — "where _not_ to dig" — is + the one key the literature does not cover and the baseline's budget-burning argues is real. + It survives only as negations inside steps, which is the negation-steering Principle v2 warns + against when a warning has no place of its own. + +6. **The delivery mechanism is decided; the content was never written.** ADR-0002 N2 fixes where + harness-shipped guidance lives and gates it mechanically. What ships today is eight protocol + sentences. + +7. **Selection needs an input, and kickoff was designed to produce it.** FE-1406's 08-19 text + made posture a kickoff output that strategy varies with. The 08-25 rescope dropped both + halves. + +8. **The failure catalogue already says which failures are the harness's to teach against.** + FM-12 (opening overload), FM-14 (ambiguity bypass), and FM-15 (unlicensed influence) are the + three technique-owned failures; they correspond to how to open, how to probe, and what one is + licensed to do — not to any kind or slot. + +## Strain + +Places the record disagreed with itself or resisted a single reading during this audit. + +- **`sweep` means two things.** The harness capture operation and the interview move share one + word at roughly six to one. Any heading that names the move must say which it is. +- **`card` means two things.** The guidance unit and the UI question affordance + (`product-description.md`). +- **Three sizes of one obligation.** FE-1406's title today ("Lift harness-generic patterns into a + strategy repertoire"), the ledger row ("§11.5 pending"), and the supersession map ("any + harness-generic guidance would take the same `Patterns`/`Moves` shape") describe the same + obligation at three sizes and prejudge its shape. +- **ADR-0006 decision 2 makes `Moves` plugin-owned by mechanism.** "Every other section + concatenates into the interviewer's instructions" leaves no place where a harness cell and a + plugin cell could meet; decision 5's "may later lift" has no mechanism to lift into. +- **Repertoire content is not pattern-shaped.** FE-1406's rescoped done-when has the parser + reading the five rows with stable ids under the surfacing rule, but P06 (a vague quantifier) + and P10 (an expert who does not know) trigger on conversation, not node state; the harness + cannot match them. They are probe forms, not patterns. +- **The glossary asserts the shape before the design.** `CONTEXT.md`'s retired Kernel card entry + says the quiver "becomes harness-generic patterns lifted out of plugin files." +- **The most explicit teaching text is sealed evaluation input.** The v0 and condition-3 prompts + carry the fullest prose; the production path carries the least. From 9db538b85c09af40c14937e07883f3967fa8eae1 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Tue, 25 Aug 2026 16:22:50 +0200 Subject: [PATCH 2/3] Fix the harness-teaching layer as keys and steer toward building it ADR-0007 v2: every plugin key follows one principle (the harness defines and teaches the concept and its default; the plugin specialises in harness terms; the rendered text interleaves key, default, cell). Sixteen fixed keys in four groups replace the eight move headings of v1; the repertoire becomes packages/repertoire. S-008 records the decision to build the layer as topology and STEERING gains the fifth epicentre, the authoring lane, the ratification gate, and the anti-rescope trigger. Co-Authored-By: Claude Fable 5 --- libs/@hashintel/brunch-agent/docs/INDEX.md | 2 +- ...hing-meets-plugin-content-at-fixed-keys.md | 188 ++++++++++++++++++ ...s-plugin-content-at-fixed-move-headings.md | 148 -------------- .../brunch-agent/docs/control/STEERING.md | 29 ++- .../brunch-agent/docs/control/STRATEGY-LOG.md | 53 +++++ .../audits/harness-teaching-lineage-audit.md | 2 +- 6 files changed, 263 insertions(+), 159 deletions(-) create mode 100644 libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md delete mode 100644 libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md diff --git a/libs/@hashintel/brunch-agent/docs/INDEX.md b/libs/@hashintel/brunch-agent/docs/INDEX.md index cf236e58c43..e7d5d4ace76 100644 --- a/libs/@hashintel/brunch-agent/docs/INDEX.md +++ b/libs/@hashintel/brunch-agent/docs/INDEX.md @@ -117,7 +117,7 @@ contract requires the spec to carry the new operating truth, in explicitly dated | [0004-in-petrinaut-staging-and-the-monorepo-import](adr/0004-in-petrinaut-staging-and-the-monorepo-import.md) | accepted | FE-1433; amended by FE-1437; extended by FE-1480 | September demo stages inside demo.petrinaut.org; reusable libraries remain mutually unaware; ADR-0005 extends the application-owned artifact path from projection scaffold and obligations to an executable file through Petrinaut client tools | | [0005-model-assisted-sdcpn-realization](adr/0005-model-assisted-sdcpn-realization.md) | accepted | FE-1480 | A pure plugin projection emits an SDCPN scaffold, typed code-obligation sidecar, and loss report; the Brunch agent realizes executable TypeScript through Petrinaut client tools and deterministic compile/simulation gates | | [0006-plugins-per-target-formalism](adr/0006-plugins-per-target-formalism.md) | accepted | design-convergence review 2026-08-25 | Plugins are per target formalism, authored as sectioned Markdown with fixed contract headings and three machine-read tables; domain-neutral by rule; retires the declarative ScopeExpr/firesWhen/DemandTable contract | -| [0007-harness-teaching-meets-plugin-content-at-fixed-move-headings](adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md) | active | FE-1406; drafted 2026-08-25, awaiting ratification | Proposed: a plugin splits into schema-validated contract data, a per-job runbook under eight fixed harness-owned move headings typed procedure / repertoire / anchor, and a harness repertoire of defaults rendered before plugin cells; selection (repertoire, keyed to posture) separated from sequence; amends ADR-0006 decisions 2 and 5 | +| [0007-harness-teaching-meets-plugin-content-at-fixed-keys](adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md) | active | FE-1406 (owner), FE-1431, FE-1393; drafted 2026-08-25, awaiting ratification | Proposed: plugin authoring is a fixed set of harness-owned keys in four groups — contract data (`ontology`, `schema`, `patterns`), guidance typed by mechanism (`lenses`, `techniques`, `movements`, `licenses`, `motifs`, `smells`, `rabbit_holes`, `failure_modes`), per-job runbooks (`kickoff`, `trajectory`, `close`), machinery (`checks`, `tools`) — each rendered key → harness default → plugin cell; the repertoire is `packages/repertoire`; amends ADR-0006 decisions 2 and 5 | ## External canonical documents diff --git a/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md b/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md new file mode 100644 index 00000000000..2d41d3866ff --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md @@ -0,0 +1,188 @@ +# ADR-0007: Harness teaching meets plugin content at fixed keys + +Date: 2026-08-25 +Status: proposed — drafted for Lu's ratification; nothing below governs until accepted +Amends: [ADR-0006](0006-plugins-per-target-formalism.md), decision 2 (a plugin is no longer one +Markdown file whose prose is concatenated whole; the machine-read tables become schema-validated +data and the prose becomes cells under harness-owned keys) and decision 5 (the "later lift" of +harness-generic guidance is designed here, and it is not pattern-shaped) +Preserves: [ADR-0002](0002-topology-and-placement-rules.md) N2 (harness-shipped guidance lives in +a harness package, never in app `skills/` directories), [ADR-0003](0003-three-register-ir.md) +(three registers), [ADR-0005](0005-model-assisted-sdcpn-realization.md) (`project` / `validate` +as code), IR Layer B's rule that interview ordering is derived from completion rather than +taught, and completion rule 15 (whether a session may stop is session control, never guidance) +Decided on: the `ln/fe-1406-harness-teaching-adr` branch, from the +[lineage audit](../evidence/proofs/audits/harness-teaching-lineage-audit.md) and the +[penciled directions of 2026-08-14](../archive/planning-inputs/penciled-directions-2026-08-14.md); +owning issue FE-1406 (gist: what the harness teaches) + +## Context + +Kernel spec §11.5 has said since 2026-08-11 that **guidance ownership follows vocabulary +ownership**: a plugin teaches what to notice in its formalism; the harness teaches how to work an +interview situation the shared envelope can name. The rule was reaffirmed by FE-1397, ADR-0002, +FE-1406, and ADR-0006's supersession map, and it has never been designed. The +[audit](../evidence/proofs/audits/harness-teaching-lineage-audit.md) finds fifteen restatements, +eight vocabularies, five layers, and no build; each rescoping shrank the deliverable — a designed +quiver, then graduated cards, then five relocated rows — while the rule stood. What ships today is +eight protocol sentences in `packages/core` followed by the plugin file's prose. + +The richest prior form is the plugin manifest penciled on 2026-08-14: `licenses / techniques / +movements (slice_moves, sweep_moves) / scopes_and_motifs / rabbit_holes / failure_modes / smells / +lenses / checks / tools / ontology / schema`, with an ownership sort per key — "you may press a +busy expert" is harness-side, "press on tint-qualification claims" is the same key plugin-side — +and the observation that `rabbit_holes` (where _not_ to dig) is the one key the literature does +not cover. Its own gap note says completion and the anchor were missing. Every key on that list +follows one principle: an author supplies direction specific to a formalism, **in terms of +concepts the harness defines and teaches**. + +ADR-0006 put the how-to under the plugin file's `Moves` heading as job runbooks, and by its +decision 2 the harness concatenates that section into the interviewer's instructions unread. The +consequence is visible in the one plugin that exists: of the SDCPN `construct` runbook's six steps +— open with objectives, slice, sweep, probe, keep the ledger, close honestly — five are generic +method a `gherkin` plugin would have to repeat. The runbook is mostly harness craft filed in a +plugin because the contract gives the harness no place to put its own. + +The audit also finds that the idea has always carried two dimensions the record never separated. +One is **sequence**: open before structure, slice before sweep, close by summarising and offering +one correction. The other is **selection**: which probe to use on this answer, whether to slice or +sweep now, how much to batch, how to phrase the next question for this expert's appetite. +FE-1406's 2026-08-19 design stated the selection half — strategy varies with a posture inferred at +kickoff — and the 2026-08-25 rescope dropped it. Most of the penciled keys are selection and +anchor content that applies in every job; only kickoff, trajectory, and close are per-job +procedure. + +Meanwhile the read path landed (FE-1497): the plugin-file parser and the proposal-schema narrowing +that hangs off it are 378 lines of hand-written Markdown table reading, with the floor read by +regex over prose and the completion anchor found by naming convention — the size finding on +`STEERING.md` asks whether the machine-read part of the file should be data. + +## Decision + +1. **One principle for every key: the harness defines and teaches the concept; the plugin + specialises it in the harness's terms.** Plugin authoring is a fixed set of **keys**. The + harness owns every key, its meaning, and its default text; a plugin fills cells under those keys + with content that names its kinds and never a domain. Rendering interleaves, key by key: the + key, the harness default, then the plugin's cell if it is not blank. Cells add; they never + override a default — a default a plugin needs to contradict is a finding about the harness. + Adding a key is an amendment to this record; the generality test of ADR-0006 extends to keys — + a second formalism or a third job adds zero. + +2. **The keys, in four groups.** Groups are by nature — data, guidance, procedure, code — not by + file. + + **Contract keys** (data, validated by a schema, never read by prose rules): + + | Key | Holds | + | --- | --- | + | `ontology` | The `Kinds` table: kind, slots, projects-to. | + | `schema` | The `Must know` rows with precision and accepted absence; the static floor as counts; the anchor kind and its dependency slot, declared, not found by convention; the proposal payload shapes. | + | `patterns` | Kind-indexed, machine-matchable triggers on node state with the question that resolves them (P01–P05, P07, P08, P13 today). Matched by the harness at read time; surfaced, never mandated. | + + **Guidance keys** (prose; harness default plus plugin cell; each typed by the mechanism it + works through): + + | Key | Mechanism | The harness teaches | A plugin cell adds | + | --- | --- | --- | --- | + | `lenses` | attention | The interview situations the envelope can name: conflict, competing alternatives, ambiguity, weak or missing evidence, absence clusters, choice-point pressure (§11.5's six) — what each looks like and what to do when it appears. | Where the formalism's kinds hide in ordinary talk. | + | `techniques` | technique | Question forms that deepen one answer: the vague quantifier, the story instead of the generalisation, the tension between two answers, the smallest delta to the demanded precision, "don't know" routed to a source, the universal follow-up ("how would you know that?"). | Formalism-specific methods (the quantile protocol for a spread). | + | `movements` | technique | `slice`: walk one concrete case end to end before anything systematic; the bounded opener; the shape comes from the slice. `sweep`: make one property hold across one stratum; the completion report is the map of what is unknown, never the order to ask in; close each stratum by asking for absences and unwritten rules. | What one case is in this formalism; kind order; what a stratum is. | + | `licenses` | license | Moves a cooperative model suppresses and may make: press a busy expert; batch two to four questions for breadth, one thread for depth; decline to sweep; propose structure, keeping a proposal a suggestion until confirmed (FM-15); stop when the expert must stop. | Formalism-specific permissions; usually blank. | + | `motifs` | attention | Motifs scaffold questions and never generate structure; the interviewer asks which pattern is present with what parameters, never assembles free-form structure from a catalogue. | The formalism's recurring shapes (queue, batch, rework loop, shared resource) as question scaffolds — Layer B's motif quiver, homed. | + | `smells` | attention | Signs in the interviewer's own output that something has gone wrong: schema-shaped questioning, null collapse, silent hardening, correction-as-duplication, fluency taken for completeness. | Formalism smells (a quantity given for one type and no other; a continuous quantity that triggers nothing). | + | `rabbit_holes` | anchor | Where not to dig and what looks like progress and is not: asking the expert what you failed to ask; restating the whole model; stating a value the expert did not give; taking a schedule or a document for the practised rule; reopening a settled stratum without new evidence. | Formalism holes. | + | `failure_modes` | anchor | FE-1407's technique-owned failures with their detection signatures — opening overload (FM-12), unresolved-ambiguity bypass (FM-14), unlicensed influence (FM-15) — as the failures this guidance exists to prevent. | Formalism failure modes (a dead net; an unsupported objective). | + + **Runbook keys** (procedure; one runbook per job; harness default runbook plus plugin cells): + + | Key | The harness teaches | A plugin cell adds | + | --- | --- | --- | + | `kickoff` | What to establish before structure: the objective, why, boundaries, and the expert's **posture** (time, intended use, required confidence, tolerance for proposed assumptions). Never an opening battery. | What "no model exists" or "a model exists" means for this job; the kind the objective is captured as; for review, orientation on the artifact and scope. | + | `trajectory` | Which movements in which bias, varied by posture: slice-and-trace first, sweep second, re-entering slice inside a new sub-area; explore openly when appetite is high, synthesise and invite correction when constrained, propose low-risk structure and question only high-impact uncertainty in mixed cases. Presented as postures, never as a state machine. | Job-specific order among the plugin's kinds; for review, the affected-slice discipline. | + | `close` | Completion is computed, not felt; a smooth interview, a busy expert, a delivered document, an exhausted budget, and a complete model are five different things. If the expert must stop, stop. Summarise per kind, state what is missing or assumed, offer one correction. Whether one _may_ stop is session control (rule 15). | The job's named stopping outcomes; the deliverable's shape. | + + **Machinery keys** (code, ADR-0005's seam): + + | Key | Holds | + | --- | --- | + | `checks` | Validators: proposal payload validators, reconcile checks, `validate`. What the harness enforces — completion, the sweep list, the assumption ledger, the affected slice — is harness code and is stated to the interviewer in a fixed harness preamble, not a plugin cell. | + | `tools` | `project`, and the client tools a job needs. | + +3. **The words.** A **mechanism type** says how a guidance key works: **license** permits a + suppressed move; **technique** supplies a method the model does not reliably apply; + **attention** points native ability at a target; **anchor** holds leading words for judgment. + **Procedure** belongs only to runbook keys. This is Principle v2 — _procedure for mechanism, + anchors for judgment, shapes for output_ — applied key by key. The harness-shipped guidance is + the **repertoire**; "quiver" retires as its synonym. **Selection** is choosing among repertoire + cells at the moment; **sequence** is a runbook. **Posture** is the selection input kickoff + produces; it is inferred continuously and never a stored field. + +4. **Jobs are harness vocabulary.** `construct` (no model exists) and `review and revise` (a model + exists) are situations the harness names without any plugin. The repertoire carries one default + runbook per job; a plugin declares which jobs it supports and fills their cells. A third job is + an amendment to this record. + +5. **The harness surfaces and never selects.** The rule already stated for patterns ("the harness + surfaces; the interviewer decides") governs every guidance key: the completion cue may say what + is unsatisfied and which patterns match; it never says "sweep now." No mechanism selects a move + for the interviewer. + +6. **Conversational triggers are guidance, not patterns.** A pattern needs a trigger the harness + can match against node state. Guidance whose trigger is conversational — a vague answer, an + expert who does not know, the end of a topic — belongs under a guidance key. FE-1406's five + candidates sort accordingly: P06, P10, and P12 into `techniques`; P09 and P11 into + `movements.sweep`; their ids retire with the rows. + +7. **Admission to the repertoire is by evidence.** A default is admitted where FE-1403's verdict + rule holds — it fires where the bare model demonstrably failed, not where instinct already + succeeds. The first admissions are the ones the record already evidences: the three + technique-owned failures of FE-1407, the v0 prompt's seven headings (condition 2 beat condition + 1 on them), and GEN-Q02's batching license from the FE-1403 desk replay. Everything else waits + for a run. + +8. **The layers are topology.** The repertoire is a package, `packages/repertoire`, that depends + only on `packages/core`; bindings depend on it to render; plugins never import it — a plugin + composes with the repertoire by filling cells and omitting what the repertoire already teaches. + A plugin package is: `plugin.yaml` (contract keys and the guidance and runbook cells, validated + against a JSON schema published by `core`; cells may point at sibling Markdown files when they + are long), plus `src/` for the machinery keys. The parser becomes the schema and a key reader. + Gates: the schema rejects an unknown key; the repertoire must fill every guidance key and every + runbook key; a plugin may leave any cell blank and may add no key; the binding renders by + interleaving. Every layer ships with its intent — a package README saying what the layer is for, + pointing here. + +## Condition + +Revisit if a second formalism or a third job needs a new key; if a plugin cell must contradict a +harness default rather than add to it; if any mechanism needs the harness to _select_ a move +rather than surface the facts a selection is made from; or if posture needs to be stored. Each is +a finding about the abstraction, decided by amending this record — never by adding a key to one +plugin, a per-domain cell, or a hidden field. Any rescoping of the repertoire must cite run +evidence; the audit records three rescopings that cited none. + +## Consequences + +- **FE-1406 is restored to its original question** — what the harness teaches — with this record + as its design and `packages/repertoire` as its deliverable; the 2026-08-25 five-row scope is + replaced by decision 6. **FE-1431** (declarative plugin authoring) becomes the plugin side of + decision 8: the schema, `plugin.yaml`, the key reader, and the SDCPN plugin's migration. + **FE-1393** keeps its role: the gherkin plugin fills cells only and adds zero keys. These are + proposed Linear edits, not ones made here. +- **The SDCPN `construct` runbook shrinks.** Slice, sweep, probe, ledger, and close move to the + repertoire; the plugin keeps what one case is, its kind order, and its stopping outcomes. The + `review and revise` runbook keeps orientation, scope, and its job checks. `Patterns` P06, P09, + P10, P11, P12 leave the plugin. +- **The parser shrinks to a schema and a key reader.** Table reading, the floor regex, and the + anchor convention become declared fields; the binding's instruction assembly interleaves per + decision 1 instead of appending a file. +- **The glossary changes on acceptance** (`CONTEXT.md`, per `docs/agents/domain.md`): Plugin is + redefined by keys; Runbook as the three runbook keys for one job; Pattern gains "machine-matchable + trigger on node state"; the retired Kernel card entry stops asserting the quiver "becomes + harness-generic patterns"; ElicitationPack is retired in favour of the guidance keys; new + entries for Repertoire, Key, Mechanism type, Posture. `SPEC-LEDGER.md` §11.5 moves from + pending to designed by this record; §11.1 and §11.2 point here. +- **Anti-guidance gets a home.** `rabbit_holes` is where the negations now scattered through steps + go, so the steps can be stated positively. +- **The evaluation prompts become recoverable defaults.** The v0 prompt's seven headings and the + condition-3 hint fragments are the first drafts of repertoire text; the prompts themselves stay + sealed as condition inputs. diff --git a/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md b/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md deleted file mode 100644 index 98e9b6ad2d9..00000000000 --- a/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md +++ /dev/null @@ -1,148 +0,0 @@ -# ADR-0007: Harness teaching meets plugin content at fixed move headings - -Date: 2026-08-25 -Status: proposed — drafted for Lu's ratification; nothing below governs until accepted -Amends: [ADR-0006](0006-plugins-per-target-formalism.md), decision 2 (the `Moves` section is no -longer plugin prose concatenated whole; the machine-read tables become schema-validated data) and -decision 5 (the "later lift" of harness-generic guidance is designed here, and it is not -pattern-shaped) -Preserves: [ADR-0002](0002-topology-and-placement-rules.md) N2 (harness-shipped guidance lives -in `core`), [ADR-0003](0003-three-register-ir.md) (three registers), IR Layer B's rule that -interview ordering is derived from completion rather than taught, and completion rule 15 (whether -a session may stop is session control, never guidance) -Decided on: the `ln/fe-1406-harness-teaching-adr` branch, from the -[lineage audit](../evidence/proofs/audits/harness-teaching-lineage-audit.md); owning issue FE-1406 -(gist: what the harness teaches) - -## Context - -Kernel spec §11.5 has said since 2026-08-11 that **guidance ownership follows vocabulary -ownership**: a plugin teaches what to notice in its formalism; the harness teaches how to work an -interview situation the shared envelope can name. The rule was reaffirmed by FE-1397, ADR-0002, -FE-1406, and ADR-0006's supersession map, and it has never been designed. The -[audit](../evidence/proofs/audits/harness-teaching-lineage-audit.md) finds fifteen restatements, -eight vocabularies, five layers, and no build. What ships today is eight protocol sentences in -`packages/core` followed by the plugin file's prose. - -ADR-0006 put the how-to under the plugin file's `Moves` heading as job runbooks, and by its -decision 2 the harness concatenates that section into the interviewer's instructions unread. The -consequence is visible in the one plugin that exists: of the SDCPN `construct` runbook's six -steps — open with objectives, slice, sweep, probe, keep the ledger, close honestly — five are -generic method that a `gherkin` plugin written to the same contract would have to repeat. The -runbook is mostly harness craft filed in a plugin, because the contract gives the harness no place -to put its own. - -The audit also finds that the idea has always carried two dimensions the record never separated. -One is **sequence**: open before structure, slice before sweep, close by summarising and offering -one correction. The other is **selection**: which probe to use on this answer, whether to slice or -sweep right now, how much to batch, how to phrase the next question for this expert's appetite. -The 2026-08-19 design of FE-1406 stated the selection half precisely — strategy varies with an -interaction posture inferred at kickoff — and the 2026-08-25 rescope dropped it, along with the -one named form of anti-guidance (`rabbit_holes`, 2026-08-14: where _not_ to dig) that survives only -as negations inside steps. - -Meanwhile the read path landed (FE-1497): the plugin-file parser and the proposal-schema -narrowing that hangs off it are 378 lines of hand-written Markdown table reading, with the floor -read by regex over prose and the completion anchor found by naming convention — the size finding -on `STEERING.md` asks whether the machine-read part of the file should be data. - -## Decision - -1. **A plugin has three parts, split by their nature, not by file.** The **contract** is data: - kinds, `Must know` rows, the floor, the anchor, and `Patterns` rows — validated by a schema, - never interpreted by prose rules. The **runbook** is prose under fixed move headings, one per - job. The **harness repertoire** is prose under the same headings, shipped from `core` - (ADR-0002 N2), rendered before every plugin's cells. Guidance ownership follows vocabulary - ownership at the level of the heading: the harness owns every heading and its default; a plugin - owns the cells that name its kinds. - -2. **The move headings are fixed, small, and typed.** Eight headings, in this order, identical - for every plugin and every job. Adding one is an amendment to this record; the generality test - of ADR-0006 extends to them — a second formalism or a third job adds zero headings. - - | Heading | Type | Required | The harness default teaches | A plugin cell may add | - | --- | --- | --- | --- | --- | - | `Kickoff` | procedure | yes | What to establish before structure: objective, why, boundaries, and the expert's **posture** (time, intended use, required confidence, tolerance for proposed assumptions). Never an opening battery (FM-12). | What "no model exists" or "a model exists" means for this job; the kind the objective is captured as; for review, orientation and scope. | - | `Slice moves` | repertoire | no | Walk one concrete case end to end before anything systematic; the bounded opener (three to six steps); the shape comes from the slice. | What one case is in this formalism ("one instance from arriving to leaving"; one scenario). | - | `Sweep moves` | repertoire | no | Make one property hold across one stratum. The completion report is the map of what is unknown, never the order to ask in. End each stratum by asking for absences and for the unwritten rules. | Kind order; which slots go together; what a stratum is here. | - | `Probes` | repertoire | no | Question forms that deepen one answer: the vague quantifier, the story instead of the generalisation, the tension between two answers, the smallest delta to the demanded precision, the "don't know" routed to a source, the universal follow-up ("how would you know that?"). | Formalism-specific forms (the quantile protocol for a spread). | - | `Postures` | repertoire | no | How selection varies with the posture from kickoff: explore openly; synthesise and invite correction; propose low-risk structure and question only high-impact uncertainty. Batch breadth (two to four), sequence depth. A proposal stays a suggestion until confirmed (FM-15). | Usually blank. | - | `Rabbit-holes` | anchor | no | Where not to dig and what looks like progress and is not: asking the expert what you failed to ask; restating the whole model; stating a value the expert did not give; taking a schedule or a document for the practised rule; taking fluency for completeness. | Formalism-specific holes (a continuous quantity that triggers nothing). | - | `Checks` | anchor | no | What the harness enforces so the interviewer need not police it: completion, the sweep list, the assumption ledger, the affected slice. | Job-specific checks the harness owns (for review: trace, scope, projection identity). | - | `Close` | procedure | yes | Completion is computed, not felt; a smooth interview, a busy expert, a delivered document, an exhausted budget, and a complete model are five different things. If the expert must stop, stop. Summarise per kind, state what is missing or assumed, offer one correction. Whether one _may_ stop is session control (rule 15). | The job's named stopping outcomes; the deliverable's shape. | - -3. **Three heading types, and the words for them.** A **procedure** heading holds ordered steps - with checkable completion; it is followed. A **repertoire** heading holds options — each a - when / what it gets / how — from which the interviewer **selects** at the moment, against the - situation and the posture; nothing under it is a sequence. An **anchor** heading holds leading - words for judgment; it is kept in mind. This is Principle v2 — _procedure for mechanism, - anchors for judgment, shapes for output_ — applied heading by heading. "Repertoire" is the word - for the selection dimension and for the harness's document; "quiver" retires as its synonym. - "Runbook" remains the word for one job's `Moves`, whether the harness's default or a plugin's. - "Posture" is the selection input kickoff produces. - -4. **Jobs are harness vocabulary.** `construct` (no model exists) and `review and revise` (a model - exists) are situations the harness can name without any plugin. The harness repertoire carries - one default runbook per job; a plugin declares which jobs it supports and supplies cells under - their headings. A third job is an amendment to this record. - -5. **Rendering interleaves; the harness surfaces and never selects.** For each job the binding - renders, heading by heading in contract order: the heading, the harness default, then the - plugin's cell if it is not blank. Cells add; they do not override a default — a default that a - plugin needs to contradict is a finding about the repertoire. The rule already stated for - patterns ("the harness surfaces; the interviewer decides") governs every repertoire heading: - the completion cue may say what is unsatisfied and which patterns match; it never says "sweep - now." - -6. **`Patterns` stay in the contract, kind-indexed, formalism-owned.** A pattern is a - machine-matchable trigger on node state plus a question; that is what lets the harness surface - it. Guidance whose trigger is conversational — a vague answer, an expert who does not know, the - end of a topic — is not pattern-shaped and belongs under a move heading. FE-1406's five - candidates sort accordingly: P06, P10, and P12 are `Probes` defaults; P09 and P11 are - `Sweep moves` defaults; their ids retire with the rows. - -7. **Admission to the harness repertoire is by evidence.** A default is admitted where FE-1403's - verdict rule holds — it fires where the bare model demonstrably failed, not where instinct - already succeeds — and FE-1407's technique-owned failures are the first three obligations: - `Kickoff` against opening overload (FM-12), `Probes` against unresolved-ambiguity bypass - (FM-14), `Postures` against unlicensed influence (FM-15). Everything else waits for a run. - -8. **Serialisation is not decided here.** This record fixes the split, the headings, their types, - and the meeting rule. That the contract is schema-validated data recommends YAML with a JSON - schema (strict, commentable, plainly readable); that runbook cells are prose the model reads - recommends sectioned Markdown or YAML block scalars under the fixed headings. The - plugin-contract spec records the choice when the implementing issue makes it; the parser reads - headings either way. - -## Condition - -Revisit if a second formalism or a third job needs a ninth heading; if a plugin cell must -contradict a harness default rather than add to it; or if any mechanism needs the harness to -_select_ a move rather than surface the facts a selection is made from. Each is a finding about -the abstraction, decided by amending this record — never by adding a heading to one plugin, a -per-domain cell, or a stored posture field. - -## Consequences - -- **FE-1406 is restored to its original question** — what the harness teaches — with this record - as its design; the 2026-08-25 five-row scope is replaced by decision 6. This is a proposed Linear - edit, not one made here. -- **The SDCPN `construct` runbook shrinks.** Its slice, sweep, probe, ledger, and close steps - become harness defaults; the plugin keeps what one case is, its kind order, and its stopping - outcomes. The `review and revise` runbook keeps its orientation, scope, and checks cells. A - `gherkin` plugin inherits every default and writes cells only; FE-1393's zero-new-headings test - covers move headings. -- **The parser shrinks to a schema and a heading splitter.** The table reading, the floor regex, - and the anchor convention become a schema; the anchor and floor become declared fields. The binding's instruction assembly interleaves per decision 5 instead of - appending the file. -- **The glossary changes on acceptance** (`CONTEXT.md`, per `docs/agents/domain.md`): Runbook is - redefined as the eight typed headings for one job; Pattern gains "machine-matchable trigger on - node state"; the retired Kernel card entry stops asserting that the quiver "becomes - harness-generic patterns"; ElicitationPack's prose sections are the runbook; new entries for - Repertoire, Posture, and Move heading. `SPEC-LEDGER.md` §11.5 moves from pending to designed - by this record. -- **The v0 prompt is recoverable as the first draft of the defaults.** Its seven headings map - onto `Kickoff`, `Slice moves`, `Sweep moves`, `Probes`, `Postures`, `Checks`, and `Close`; the - prompt itself stays sealed as condition-2 input. -- **Anti-guidance gets a home.** `Rabbit-holes` is where the negations now scattered through - steps go, so the steps can be stated positively. diff --git a/libs/@hashintel/brunch-agent/docs/control/STEERING.md b/libs/@hashintel/brunch-agent/docs/control/STEERING.md index 64c91b4d84c..27128489f57 100644 --- a/libs/@hashintel/brunch-agent/docs/control/STEERING.md +++ b/libs/@hashintel/brunch-agent/docs/control/STEERING.md @@ -17,9 +17,10 @@ superseding capture while an unrelated region stays stable. Preserve runnable an evidence under [proof evidence](../evidence/proofs/). Governing strategic decisions: [S-001](STRATEGY-LOG.md#s-001), [S-004](STRATEGY-LOG.md#s-004), -and [S-007](STRATEGY-LOG.md#s-007). Governing architecture: +[S-007](STRATEGY-LOG.md#s-007), and [S-008](STRATEGY-LOG.md#s-008). Governing architecture: [ADR-0003](../adr/0003-three-register-ir.md), [ADR-0005](../adr/0005-model-assisted-sdcpn-realization.md), -[ADR-0006](../adr/0006-plugins-per-target-formalism.md). +[ADR-0006](../adr/0006-plugins-per-target-formalism.md); [ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md) +is proposed and governs the teaching layer on ratification (see gates). ## Selected frontier: the vertical slice, worked outward from its epicentres @@ -29,7 +30,7 @@ open is answered by what the slice forces, and answered in code. The design-conv closed: its outputs are test-bed material, and its one durable design result is the plugin file [`plugin-sdcpn/plugin.md`](../../packages/plugin-sdcpn/plugin.md) ratified by ADR-0006. -The slice has four epicentres, ordered by the size of the gap they close. Work starts at the +The slice has five epicentres, ordered by the size of the gap they close. Work starts at the centre of each and moves outward; edges (SDK generality, affordance catalogues, UI breadth, evaluation apparatus) are not worked until an epicentre needs them. @@ -39,6 +40,7 @@ evaluation apparatus) are not worked until an epicentre needs them. | **E2 — the SDCPN plugin in code** | The plugin file exists as a spec; nothing parses its three tables, folds captures onto its kinds, or projects from them. | FE-1482 (gist: CPS plugin, redefined as the skeleton epicentre) | | **E3 — targeted correction** | `supersedes` is unreachable from extraction; no affected-slice computation; no delta; the target-document is still identified with the conversation. | FE-1479 (targeted re-elicitation), FE-1478 (provenance read), FE-1439 (durable session / document boundary) | | **E4 — the real entry** | Client-tool results do not return to the elicitor; retry/abandonment semantics unproven; realization gated. | FE-1438, FE-1420, FE-1480 | +| **E5 — the teaching layer** | The harness teaches eight sentences; the plugin runbook carries five-sixths harness method that gherkin would repeat; the parser reads the floor and anchor from prose by convention. Opened by E1's landing ([S-008](STRATEGY-LOG.md#s-008)); designed by [ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md) (proposed). | FE-1431 (authoring surface: schema, `plugin.yaml`, key reader), FE-1406 (`packages/repertoire`), FE-1393 (zero new keys) | ```text skeleton (construct job; proves the loop, produces fixtures) @@ -49,15 +51,17 @@ reviewer lane (review-and-revise job; the acceptance proof) FE-1420 retry/abandonment safety -> FE-1438 client-tool return -> FE-1439 durable session FE-1478 provenance read -> FE-1480 scaffold/realization -> FE-1479 targeted correction join -after the skeleton runs -FE-1393 gherkin under the same six headings (generality check) -FE-1406 lift harness-generic patterns into a harness repertoire -FE-1431 residue: parser + heading contract +authoring lane (E5; alongside the skeleton run, joins it at a second run over the migrated plugin) +FE-1431 schema + plugin.yaml + key reader; SDCPN plugin migrated +-> FE-1406 packages/repertoire: every guidance and runbook key filled; binding renders key -> default -> cell +-> FE-1393 gherkin fills cells only, adds zero keys (generality check) ``` Arrows are strategic order. The skeleton lane and the reviewer lane run in parallel; they join at FE-1479, whose "affected slice", "re-evaluate", and "delta" moves consume E1's fold and completion. -No hard blocker chain remains from the retired design queue. +No hard blocker chain remains from the retired design queue. The authoring lane's sizing +(FE-1406 as a package, FE-1431 as the authoring surface) is [S-008](STRATEGY-LOG.md#s-008)'s and +waits on the ADR-0007 gate before Linear reflects it. ### Proof bundle for the selected frontier @@ -105,6 +109,7 @@ The read-only Linear graph supplies mechanical availability, never priority. | FE-1480 executable realization unavailable | FE-1438; [ADR-0005](../adr/0005-model-assisted-sdcpn-realization.md) | Client tools return code diagnostics to the elicitor. | 2026-08-25 | Scaffold work may proceed; no runnable FE-1480 proof until the gate opens. | | Final use case outstanding | Dora; FE-1476 / September Plan | Dora confirms or changes it. | 2026-08-25 | If creation is required, Proof 1 becomes acceptance-relevant rather than a harness proof; reconcile ADR-0004/proof. | | Deferral licensing (completion spec rules 17–19) unbuildable | [elicitation-completion](../specs/elicitation-completion.md) rules 17–19; FE-1480 / [ADR-0005](../adr/0005-model-assisted-sdcpn-realization.md) | A durable projection delivery exists for an evaluated revision. | 2026-08-25 | E1 supplies the report and revision (FE-1497, #9325); rule 18 makes licensing `false` without a delivered projection, so no issue is opened. When FE-1480 delivers, it is one read-time function beside `evaluateCompletion` plus a binding hook at settlement; no new persistence. | +| ADR-0007 awaiting ratification | Lu; [ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md), PR #9327 | Lu accepts, amends, or rejects the record. | 2026-08-25 | Until accepted, FE-1406, FE-1431, and FE-1393 keep their S-007 scope in Linear and E5 is design-only on its branch. On acceptance: the three Linear edits, the glossary and SPEC-LEDGER amendments, then FE-1431 starts. | | Truck-fleet dossier missing from the repository | FE-1382 is Done but its promised `docs/reference/research/` artifact is absent. | Artifact path/branch is supplied or a reviewed replacement is selected. | 2026-08-25 | The generality half of Proof 1 uses a fixture derived from the inbox truck SDCPN and Layer B's worked example; claim no dossier-backed domain provenance. | ## Decision-relevant beliefs and unknowns @@ -113,7 +118,8 @@ The read-only Linear graph supplies mechanical availability, never priority. | --- | --- | --- | | Kind-level rows express the coatings case. | Medium-high; the twenty domain-keyed rows of the FE-1402 rehearsal collapse onto eight kind rows on paper. | Proof 1's first half. | | The truck-fleet case adds zero headings and zero rows. | Medium; Layer B was validated against it, but never through this file. | Proof 1's second half. | -| The controller read path is small. | The tripwire fired: E1 landed on FE-1497 (#9325) at 1055 code lines (excluding comments) against the plugin file's 225 non-blank lines — 378 parse the file and narrow the proposal schema, 677 are the fold, completion, and cue. Rules 17–19 are deferred (see gates). | Look before E3: is the 378-line parser an argument for a stricter plugin-file format (YAML or front matter for the machine-read tables) so the parser shrinks to a schema? Watch whether FE-1479's affected-slice and delta moves fit inside the 677-line engine. | +| The controller read path is small. | The tripwire fired: E1 landed on FE-1497 (#9325) at 1055 code lines (excluding comments) against the plugin file's 225 non-blank lines — 378 parse the file and narrow the proposal schema, 677 are the fold, completion, and cue. Rules 17–19 are deferred (see gates). The parser question is answered: ADR-0007 decision 8 makes the contract schema-validated data (E5). | Watch whether FE-1479's affected-slice and delta moves fit inside the 677-line engine, and whether FE-1431's key reader lands well under 378 lines. | +| Harness teaching that has a package survives rescoping. | Low; the [lineage audit](../evidence/proofs/audits/harness-teaching-lineage-audit.md) shows four prose-only rescopings since 2026-08-11, none citing run evidence, and no test of the converse yet. | The first arc after `packages/repertoire` lands: does any rescoping of it cite a run? | | Field-local code obligations support localized realization and repair. | Low-medium; the corpus and Petrinaut diagnostics are field-addressed, but no Brunch run exists. | Realize one stochastic transition without rewriting an unrelated field. | | Five turns yield a scoped correction. | Low; unrehearsed. The review-and-revise runbook in the plugin file is the first concrete trajectory. | Run two bounded rehearsals against a fixture model. | | Ask carries durable client-tool results. | Medium-low; machine results refused today. | Run one correlated FE-1438 round trip. | @@ -133,6 +139,9 @@ The read-only Linear graph supplies mechanical availability, never priority. plugin freeze) before September. - Defer broad UI/ontology/gallery/affordances/voice/scenarios/telemetry until the loop closes. - Fixtures supply domain state, never product wiring; provenance and the real entrypoint are gates. +- The teaching layer is built as topology — a package, fixed keys, a schema, gates — with each layer + paired with the document that states its intent, never as spec prose alone; and it is not + rescoped without run evidence ([S-008](STRATEGY-LOG.md#s-008), [ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md)). ## Stop or replan @@ -147,6 +156,8 @@ The read-only Linear graph supplies mechanical availability, never priority. - Two rehearsals fail the five-turn correction. - FE-1438 loses correlation, durability, or evidence semantics. - Production remains undeployable after FE-1479; seek a demo-surface decision, not test wiring. +- The teaching layer is rescoped again without run evidence, or `packages/repertoire` grows larger + than the plugin it teaches. ## Exceptional roots diff --git a/libs/@hashintel/brunch-agent/docs/control/STRATEGY-LOG.md b/libs/@hashintel/brunch-agent/docs/control/STRATEGY-LOG.md index e8af617d6a4..954d80e94f3 100644 --- a/libs/@hashintel/brunch-agent/docs/control/STRATEGY-LOG.md +++ b/libs/@hashintel/brunch-agent/docs/control/STRATEGY-LOG.md @@ -217,3 +217,56 @@ heading the contract does not have (ADR-0006's condition). [baseline situation pack](../../evaluations/cases/process-model-elicitation/baseline/situation-pack.md), [condition-3 instrument](../../evaluations/protocols/process-model-elicitation/baseline/), FE-1402, FE-1403, FE-1404, FE-1406, FE-1431, FE-1482 + +### S-008 + +**Date:** 2026-08-25 + +**Trigger/evidence:** The controller read path landed (FE-1497, #9325) and the slice forced two +findings. First, the SDCPN `construct` runbook is five-sixths harness method — open with objectives, +slice, sweep, probe, keep the ledger, close honestly — that a `gherkin` plugin written to the same +contract would repeat; the plugin file carries it because the contract gives the harness no place +to put its own. Second, the plugin-file parser and the proposal-schema narrowing that hangs off it +are 378 lines against a 225-line file, reading the floor by regex over prose and the completion +anchor by naming convention. The [lineage audit](../evidence/proofs/audits/harness-teaching-lineage-audit.md) +then showed that the harness-teaching half of §11.5 — "guidance ownership follows vocabulary +ownership" — was affirmed at every design station since 2026-08-11 and rescoped down four times +(designed quiver → graduated cards → five relocated rows), each time as prose with no home and none +of the times citing run evidence. The penciled manifest of 2026-08-14 (licenses, techniques, +movements, motifs, rabbit_holes, failure_modes, smells, lenses, checks, tools, ontology, schema) +already stated the structure that fits: every key lets an author give formalism-specific direction +in concepts the harness defines and teaches. + +**Decision:** Complements S-007 (amending its sizing of FE-1406 and FE-1431; supersedes nothing). +Materialise the harness-teaching layer as topology, per +[ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md) (proposed; governs on +ratification): a fixed set of harness-owned keys in four groups — contract data, guidance typed by +mechanism, per-job runbooks, machinery — each rendered key → harness default → plugin cell; a +`packages/repertoire` package that depends only on `core` and that bindings render; a JSON schema +in `core` that rejects unknown keys; gates that require the repertoire to fill every key and forbid +a plugin from adding one. FE-1406 is restored to its original question with the package as its +deliverable; FE-1431 becomes the plugin authoring surface (schema, `plugin.yaml`, key reader, +SDCPN migration); FE-1393 stays the zero-new-keys check. This complements S-007 rather than +reversing it: the slice forced the layer, the layer is built as code and gates rather than spec, +and each layer ships paired with the document that states its intent. Sequencing: the authoring +lane (FE-1431 → FE-1406 → FE-1393) runs alongside the skeleton run (FE-1404) and joins it at a +second run over the migrated plugin. Rejected: holding FE-1406 at five rows, because it repeats the +recorded pattern; and a spec-first design of the repertoire, because that is the failure S-007 +corrected. + +**Consequences/cuts:** STEERING gains a fifth epicentre for the teaching layer, an authoring lane in +the frontier, an ADR-0007 ratification gate, an anti-rescope trigger, and an updated belief row: the +"is the parser an argument for data?" probe is answered yes by decision 8. Linear edits to FE-1406, +FE-1431, and FE-1393 remain a separately approved step. The domain-neutrality rule, the derived +ordering of IR Layer B, and completion rule 15 are unchanged. + +**Revisit when:** ADR-0007 is rejected or amended in a way that removes a group; the migrated SDCPN +plugin or the gherkin plugin needs a key the schema lacks; or `packages/repertoire` grows larger +than the plugin it teaches (the instrument-larger-than-the-thing heuristic, applied to guidance). + +**Supersedes:** none + +**Evidence links:** [ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md), +[lineage audit](../evidence/proofs/audits/harness-teaching-lineage-audit.md), +[penciled directions 2026-08-14](../archive/planning-inputs/penciled-directions-2026-08-14.md), +[SDCPN plugin file](../../packages/plugin-sdcpn/plugin.md), FE-1406, FE-1431, FE-1393, FE-1497 diff --git a/libs/@hashintel/brunch-agent/docs/evidence/proofs/audits/harness-teaching-lineage-audit.md b/libs/@hashintel/brunch-agent/docs/evidence/proofs/audits/harness-teaching-lineage-audit.md index 7e4746d9e88..4490b64b013 100644 --- a/libs/@hashintel/brunch-agent/docs/evidence/proofs/audits/harness-teaching-lineage-audit.md +++ b/libs/@hashintel/brunch-agent/docs/evidence/proofs/audits/harness-teaching-lineage-audit.md @@ -6,7 +6,7 @@ > any one plugin. Produced 2026-08-25 from three full-read sweeps (specs, ADRs, and control > surfaces; archive and reference; evidence, evaluations, inbox, agent protocols, and source > prose) plus the Linear record of FE-1360, FE-1364, FE-1397, FE-1403, FE-1406, and FE-1407. It -> feeds [ADR-0007](../../../adr/0007-harness-teaching-meets-plugin-content-at-fixed-move-headings.md) +> feeds [ADR-0007](../../../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md) > and is evidence, not authority: where it quotes a document, that document governs. Counts are > case-insensitive occurrence counts over the named trees at the audit date. From 144eeda49ec475bd226e90ddcee8b78432ca020b Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Tue, 25 Aug 2026 16:35:40 +0200 Subject: [PATCH 3/3] Accept ADR-0007 with the catalogue left converging Lu accepted the record with one caveat: fixing the key catalogue now would repeat the failure the record corrects. Decision 9 makes the set a working one that two plugins converge on in co-authoring cycles; S-009 records the method and STEERING's authoring lane becomes that cycle. The glossary, SPEC-LEDGER, and ADR-0006 carry the amendments acceptance triggers. Co-Authored-By: Claude Fable 5 --- libs/@hashintel/brunch-agent/CONTEXT.md | 27 ++++++++++--- libs/@hashintel/brunch-agent/docs/INDEX.md | 2 +- .../adr/0006-plugins-per-target-formalism.md | 3 ++ ...hing-meets-plugin-content-at-fixed-keys.md | 29 +++++++++++--- .../brunch-agent/docs/control/SPEC-LEDGER.md | 6 +-- .../brunch-agent/docs/control/STEERING.md | 24 +++++++----- .../brunch-agent/docs/control/STRATEGY-LOG.md | 38 +++++++++++++++++++ 7 files changed, 104 insertions(+), 25 deletions(-) diff --git a/libs/@hashintel/brunch-agent/CONTEXT.md b/libs/@hashintel/brunch-agent/CONTEXT.md index 86667e0bf5c..c06cebebc62 100644 --- a/libs/@hashintel/brunch-agent/CONTEXT.md +++ b/libs/@hashintel/brunch-agent/CONTEXT.md @@ -20,7 +20,7 @@ _Avoid_: kernel, core, elicitor (as a shell name — "elicitor" may name the who **Plugin**: -The innermost shell: target-defining policy, one per **target formalism** (`gherkin`, `sdcpn`) and never per domain — the domain is unknown when a conversation starts. Authored as one sectioned Markdown file under the fixed headings `Purpose · Kinds · Must know · Patterns · Moves · Deliverable`, plus the `project` / `validate` code operations (ADR-0006). Receives harness capabilities by injection; mechanism stays in the harness. +The innermost shell: target-defining policy, one per **target formalism** (`gherkin`, `sdcpn`) and never per domain — the domain is unknown when a conversation starts. Authored as cells under the harness-owned **keys** (ADR-0007): contract data (`ontology`, `schema`, `patterns`), guidance cells, runbook cells, and the `checks` / `tools` machinery, with `project` / `validate` as code (ADR-0005, ADR-0006). A plugin fills cells and adds no key; what it leaves blank, the **repertoire** supplies. Receives harness capabilities by injection; mechanism stays in the harness. _Avoid_: extension, pack (a pack is a unit _within_ a plugin), domain plugin, scenario plugin **Binding**: @@ -114,22 +114,37 @@ _Avoid_: advisory (a different thing, below) A computed, ephemeral, non-blocking fact the harness surfaces to the agent (unaccounted ask, unswept tail, world-moved delta). Never stored in the capture store; never gates anything. **Pack**: -A unit within a plugin: **ElicitationPack** (the plugin file's `Purpose`, `Must know`, `Patterns`, `Moves`, and `Deliverable` sections) or **ProjectionPack** (`project` + `validate`, optional `reconcile`, annotated shapes, typed loss reports). Packs are shapes-to-fill plus behavioral guidance, per Principle v2. +A unit within a plugin: **ElicitationPack** (retired as a name under ADR-0007 — the guidance and runbook cells replace it) or **ProjectionPack** (`project` + `validate`, optional `reconcile`, annotated shapes, typed loss reports). Packs are shapes-to-fill plus behavioral guidance, per Principle v2. **Demand row**: -One row of a plugin's `Must know` table: a slot on a kind, its required precision, whether "not applicable" is accepted, and why the model needs it. Kind-level only — every node of that kind discovered in conversation is checked against it (ADR-0006). +One row of a plugin's `schema` key (the `Must know` table under ADR-0006): a slot on a kind, its required precision, whether "not applicable" is accepted, and why the model needs it. Kind-level only — every node of that kind discovered in conversation is checked against it (ADR-0006). _Avoid_: demand clause, scope expression, objective row **Pattern**: -A discretionary, kind-indexed heuristic in a plugin's `Patterns` table: the model situation that triggers it and the question that resolves it. Surfaced by the harness when a node matches the trigger and the relevant slot is unsatisfied; the interviewer decides whether to use it. Never names a domain. +A discretionary, kind-indexed heuristic under a plugin's `patterns` key with a **machine-matchable trigger on node state**: the model situation that triggers it and the question that resolves it. A trigger the harness cannot match against node state (a vague quantifier, an expert who does not know) is guidance — a technique or a movement — not a pattern (ADR-0007). Surfaced by the harness when a node matches the trigger and the relevant slot is unsatisfied; the interviewer decides whether to use it. Never names a domain. _Avoid_: card, kernel card (retired — ADR-0006 replaced Detects/Goal/Questions/Artifacts cards with pattern rows), technique card **Runbook**: -The `Moves` for one **job** a plugin supports (`construct`, `review and revise`): kickoff, trajectory, checks, and stopping, over the plugin's one `Kinds` / `Must know` set. A plugin carries one runbook per job. +The three runbook keys — `kickoff`, `trajectory`, `close` — for one **job** (`construct`, `review and revise`), the harness default for each interleaved with the plugin's cell. The one place procedure is stated; `kickoff` produces a **posture**, `trajectory` names movements by bias, `close` is honest stopping and never the decision to stop (completion rule 15). Jobs are harness vocabulary; a plugin fills one set of runbook cells per job it supports (ADR-0007). _Avoid_: mandate (as the unit name), mode, workflow +**Key**: +One of the fixed, harness-owned headings of plugin authoring (ADR-0007): the harness defines the concept it names, teaches it, and ships a default; a plugin specialises it in a cell written in the harness's terms and never a domain's. Rendered key → harness default → plugin cell. Keys come in four groups — contract data, guidance, runbook, machinery — and the catalogue is a working set until a co-authoring cycle changes none (decision 9). +_Avoid_: heading (for the authoring unit), section, property (unqualified) + +**Repertoire**: +The harness's own filling of every guidance and runbook key — what it teaches every plugin about interviewing — shipped as `packages/repertoire`, rendered by bindings, never imported by a plugin. Admitted by evidence, not by plausibility; never rescoped without run evidence. +_Avoid_: quiver (retired name), strategy library, kernel + +**Mechanism type**: +How a guidance key works on the interviewer: a **license** permits what the model would otherwise hedge on; a **technique** is a form of question or move; an **attention** key names what to notice; an **anchor** is a stated judgment to check against. Each guidance key has exactly one (ADR-0007 decision 3). + +**Posture**: +The interaction stance `kickoff` produces from the expert's appetite, time, intended use, and tolerance for proposed assumptions — explore, synthesise-and-invite-correction, or propose-and-question-only-high-impact. Varies the trajectory; continuously re-read; never stored (ADR-0007). Not a state machine. +_Avoid_: mode (as a stored state), appetite (for the stance itself) + **Kernel card**: -Retired (ADR-0006). The pack-content unit of elicitation guidance — Detects / Goal / contrastive Questions / Artifacts, brunch `BEHAVIORAL_KERNELS.md` lineage — is replaced by **pattern** rows in the plugin file; the harness-shipped **generic strategy quiver** named in spec §11.5 becomes harness-generic patterns lifted out of plugin files (FE-1406), still not designed. +Retired (ADR-0006). The pack-content unit of elicitation guidance — Detects / Goal / contrastive Questions / Artifacts, brunch `BEHAVIORAL_KERNELS.md` lineage — is replaced by **pattern** rows and by guidance cells; the harness-shipped **generic strategy quiver** named in spec §11.5 is designed as the **repertoire** (ADR-0007), which is not pattern-shaped. _Avoid_: card, kernel card (in new writing) **PluginContext**: diff --git a/libs/@hashintel/brunch-agent/docs/INDEX.md b/libs/@hashintel/brunch-agent/docs/INDEX.md index e7d5d4ace76..19750651af5 100644 --- a/libs/@hashintel/brunch-agent/docs/INDEX.md +++ b/libs/@hashintel/brunch-agent/docs/INDEX.md @@ -117,7 +117,7 @@ contract requires the spec to carry the new operating truth, in explicitly dated | [0004-in-petrinaut-staging-and-the-monorepo-import](adr/0004-in-petrinaut-staging-and-the-monorepo-import.md) | accepted | FE-1433; amended by FE-1437; extended by FE-1480 | September demo stages inside demo.petrinaut.org; reusable libraries remain mutually unaware; ADR-0005 extends the application-owned artifact path from projection scaffold and obligations to an executable file through Petrinaut client tools | | [0005-model-assisted-sdcpn-realization](adr/0005-model-assisted-sdcpn-realization.md) | accepted | FE-1480 | A pure plugin projection emits an SDCPN scaffold, typed code-obligation sidecar, and loss report; the Brunch agent realizes executable TypeScript through Petrinaut client tools and deterministic compile/simulation gates | | [0006-plugins-per-target-formalism](adr/0006-plugins-per-target-formalism.md) | accepted | design-convergence review 2026-08-25 | Plugins are per target formalism, authored as sectioned Markdown with fixed contract headings and three machine-read tables; domain-neutral by rule; retires the declarative ScopeExpr/firesWhen/DemandTable contract | -| [0007-harness-teaching-meets-plugin-content-at-fixed-keys](adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md) | active | FE-1406 (owner), FE-1431, FE-1393; drafted 2026-08-25, awaiting ratification | Proposed: plugin authoring is a fixed set of harness-owned keys in four groups — contract data (`ontology`, `schema`, `patterns`), guidance typed by mechanism (`lenses`, `techniques`, `movements`, `licenses`, `motifs`, `smells`, `rabbit_holes`, `failure_modes`), per-job runbooks (`kickoff`, `trajectory`, `close`), machinery (`checks`, `tools`) — each rendered key → harness default → plugin cell; the repertoire is `packages/repertoire`; amends ADR-0006 decisions 2 and 5 | +| [0007-harness-teaching-meets-plugin-content-at-fixed-keys](adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md) | accepted | FE-1406 (owner), FE-1431, FE-1393; accepted 2026-08-25, key catalogue converging (decision 9) | Plugin authoring is a fixed set of harness-owned keys in four groups — contract data (`ontology`, `schema`, `patterns`), guidance typed by mechanism (`lenses`, `techniques`, `movements`, `licenses`, `motifs`, `smells`, `rabbit_holes`, `failure_modes`), per-job runbooks (`kickoff`, `trajectory`, `close`), machinery (`checks`, `tools`) — each rendered key → harness default → plugin cell; the repertoire is `packages/repertoire`; amends ADR-0006 decisions 2 and 5 | ## External canonical documents diff --git a/libs/@hashintel/brunch-agent/docs/adr/0006-plugins-per-target-formalism.md b/libs/@hashintel/brunch-agent/docs/adr/0006-plugins-per-target-formalism.md index 46122baff34..aaaeb205b12 100644 --- a/libs/@hashintel/brunch-agent/docs/adr/0006-plugins-per-target-formalism.md +++ b/libs/@hashintel/brunch-agent/docs/adr/0006-plugins-per-target-formalism.md @@ -2,6 +2,9 @@ Date: 2026-08-25 Status: accepted +Amended by: [ADR-0007](0007-harness-teaching-meets-plugin-content-at-fixed-keys.md) (2026-08-25), +decisions 2 and 5 — the machine-read tables become schema-validated data, the prose becomes cells +under harness-owned keys, and the harness-generic lift is designed there Amends: [ADR-0003](0003-three-register-ir.md), first consequence only — the plugin contract's _form_ (a sectioned Markdown file with three parsed tables replaces the typed model-schema / proposal-catalog / fold-table / demand-table declaration); the three registers are unchanged diff --git a/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md b/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md index 2d41d3866ff..d6aac0c31f3 100644 --- a/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md +++ b/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md @@ -1,7 +1,8 @@ # ADR-0007: Harness teaching meets plugin content at fixed keys Date: 2026-08-25 -Status: proposed — drafted for Lu's ratification; nothing below governs until accepted +Status: accepted 2026-08-25 (Lu), with one caveat recorded as decision 9 — the key catalogue of +decision 2 is a working set that two plugins converge on, not a list frozen by this record Amends: [ADR-0006](0006-plugins-per-target-formalism.md), decision 2 (a plugin is no longer one Markdown file whose prose is concatenated whole; the machine-read tables become schema-validated data and the prose becomes cells under harness-owned keys) and decision 5 (the "later lift" of @@ -65,8 +66,8 @@ regex over prose and the completion anchor found by naming convention — the si with content that names its kinds and never a domain. Rendering interleaves, key by key: the key, the harness default, then the plugin's cell if it is not blank. Cells add; they never override a default — a default a plugin needs to contradict is a finding about the harness. - Adding a key is an amendment to this record; the generality test of ADR-0006 extends to keys — - a second formalism or a third job adds zero. + Once the catalogue is frozen (decision 9), adding a key is an amendment to this record and the + generality test of ADR-0006 extends to keys — a second formalism or a third job adds zero. 2. **The keys, in four groups.** Groups are by nature — data, guidance, procedure, code — not by file. @@ -151,6 +152,23 @@ regex over prose and the completion anchor found by naming convention — the si interleaving. Every layer ships with its intent — a package README saying what the layer is for, pointing here. +9. **The catalogue converges by co-authoring, not by decree.** Decision 2 names a working set. + Fixing it before it has been written against would repeat the record this ADR corrects: a + structure affirmed in prose and tested by nothing. The set is stabilised in cycles — write the + schema, `plugin-sdcpn`, `plugin-gherkin`, and the repertoire _together_; review whether each key + plausibly serves both plugins; run the result where a run is available; edit. Two pressures are + applied in every cycle. The first is the two test-case plugins: one schema must read well for + both. The second is the process-modelling edge material already in the record (the CPS + grilling inputs, the truck-fleet and coating cases, the literature deposit), asked three + questions — is the set general enough to cover different elicitations of that kind; is it + specific enough that an author can give direction that changes what the interviewer does; does + it still fit elicitations of another kind (gherkin now; formal verification as the sketch)? + During convergence, adding, merging, or dropping a key is done in the schema and both plugins at + once and recorded in the package changelog, not by amending this record. The catalogue is + **frozen** when a cycle changes no key and a third-formalism sketch fills cells only; from then + decision 1's amendment rule applies. The cycle is the method; its product is the catalogue, the + two plugins, and the repertoire, converged at the same time. + ## Condition Revisit if a second formalism or a third job needs a new key; if a plugin cell must contradict a @@ -166,8 +184,9 @@ evidence; the audit records three rescopings that cited none. as its design and `packages/repertoire` as its deliverable; the 2026-08-25 five-row scope is replaced by decision 6. **FE-1431** (declarative plugin authoring) becomes the plugin side of decision 8: the schema, `plugin.yaml`, the key reader, and the SDCPN plugin's migration. - **FE-1393** keeps its role: the gherkin plugin fills cells only and adds zero keys. These are - proposed Linear edits, not ones made here. + **FE-1393** keeps its role: the gherkin plugin fills cells only and adds zero keys. Under + decision 9 the three advance together in each cycle rather than in sequence; the Linear edits + were made on acceptance (2026-08-25). - **The SDCPN `construct` runbook shrinks.** Slice, sweep, probe, ledger, and close move to the repertoire; the plugin keeps what one case is, its kind order, and its stopping outcomes. The `review and revise` runbook keeps orientation, scope, and its job checks. `Patterns` P06, P09, diff --git a/libs/@hashintel/brunch-agent/docs/control/SPEC-LEDGER.md b/libs/@hashintel/brunch-agent/docs/control/SPEC-LEDGER.md index 1946a4cab18..7603d2878f5 100644 --- a/libs/@hashintel/brunch-agent/docs/control/SPEC-LEDGER.md +++ b/libs/@hashintel/brunch-agent/docs/control/SPEC-LEDGER.md @@ -104,10 +104,10 @@ states. | Obligation | Spec | Status | Evidence | | -------------------------------------------------------------------------------- | ---------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Plugin ownership: packs, forms, validators | §11.1 | **superseded → partial** | ADR-0006 (2026-08-25) makes a plugin one sectioned Markdown file per target formalism plus `project`/`validate` code ([`plugin-contract.md`](../specs/plugin-contract.md)); cards became kind-indexed `Patterns`, the completion contract became the `Must know` table. `plugin-gherkin` owns its one FE-1392 proposal declaration/schema and target identity; [`plugin-sdcpn/plugin.md`](../../packages/plugin-sdcpn/plugin.md) is authored but unparsed; the file parser, fold, and demand runner remain FE-1393 work | -| Pack form, Principle v2 | §11.2 | **superseded → pending** | ADR-0006 fixes pack form as the heading contract (`Purpose · Kinds · Must know · Patterns · Moves · Deliverable`) with three machine-read tables; Principle v2 still governs the prose sections. No parser or loader exists | +| Plugin ownership: packs, forms, validators | §11.1 | **superseded → partial** | ADR-0006 (2026-08-25) makes a plugin one sectioned Markdown file per target formalism; ADR-0007 (same day) re-forms it as cells under harness-owned keys with the tables as schema-validated data (FE-1431) plus `project`/`validate` code ([`plugin-contract.md`](../specs/plugin-contract.md)); cards became kind-indexed `Patterns`, the completion contract became the `Must know` table. `plugin-gherkin` owns its one FE-1392 proposal declaration/schema and target identity; [`plugin-sdcpn/plugin.md`](../../packages/plugin-sdcpn/plugin.md) is authored but unparsed; the file parser, fold, and demand runner remain FE-1393 work | +| Pack form, Principle v2 | §11.2 | **superseded → designed** | ADR-0007 fixes pack form as the key contract (four groups; `plugin.yaml` + JSON schema in core; converging per decision 9); ADR-0006 had fixed it as the heading contract (`Purpose · Kinds · Must know · Patterns · Moves · Deliverable`) with three machine-read tables; Principle v2 still governs the prose sections. No parser or loader exists | | Smallest honest plugin as a standing bar | §11.3 | **partial** | `statement-noted.test.ts` and the core plugin fixture encode the one-type verbatim floor and reject undeclared parsed/pointer shape; the standing bar must grow with FE-1393's operations | -| Generic strategy quiver | §11.5 | **pending** (ownership repaired) | was **orphaned** — named-not-designed, carried by no map — now FE-1406 (root issue) | +| Generic strategy quiver | §11.5 | **designed** (ADR-0007) | designed 2026-08-25 as the **repertoire** (`packages/repertoire`, ADR-0007 decisions 3, 6–8); built under FE-1406 in the co-authoring cycle of S-009; the key catalogue converges before it freezes (decision 9) | | Portfolio + hybrid order: both packs authored before the pack interface freezes | §13 | **superseded → partial** | ADR-0006 makes the interface the heading contract and three table grammars; the SDCPN plugin file is authored (`plugin-sdcpn/plugin.md`), the Gherkin file is not. Owned by FE-1387 (FE-1383 slice, backlog); current sequencing puts the SDCPN proof before generic freeze (see `STEERING.md`). Gherkin wiring ahead stays legal while FE-1387 holds the freeze | | Gherkin validation (parse validity, step lexicon) | §13.1 | **pending** | — | | Assurance target (Statement record, four edges, five-stratum derivation, ledger) | §13.2–13.3 | **pending** | — | diff --git a/libs/@hashintel/brunch-agent/docs/control/STEERING.md b/libs/@hashintel/brunch-agent/docs/control/STEERING.md index 27128489f57..4fa8df4dd9c 100644 --- a/libs/@hashintel/brunch-agent/docs/control/STEERING.md +++ b/libs/@hashintel/brunch-agent/docs/control/STEERING.md @@ -19,8 +19,9 @@ evidence under [proof evidence](../evidence/proofs/). Governing strategic decisions: [S-001](STRATEGY-LOG.md#s-001), [S-004](STRATEGY-LOG.md#s-004), [S-007](STRATEGY-LOG.md#s-007), and [S-008](STRATEGY-LOG.md#s-008). Governing architecture: [ADR-0003](../adr/0003-three-register-ir.md), [ADR-0005](../adr/0005-model-assisted-sdcpn-realization.md), -[ADR-0006](../adr/0006-plugins-per-target-formalism.md); [ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md) -is proposed and governs the teaching layer on ratification (see gates). +[ADR-0006](../adr/0006-plugins-per-target-formalism.md), +[ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md) (accepted +2026-08-25; its key catalogue is a working set converging under decision 9). ## Selected frontier: the vertical slice, worked outward from its epicentres @@ -40,7 +41,7 @@ evaluation apparatus) are not worked until an epicentre needs them. | **E2 — the SDCPN plugin in code** | The plugin file exists as a spec; nothing parses its three tables, folds captures onto its kinds, or projects from them. | FE-1482 (gist: CPS plugin, redefined as the skeleton epicentre) | | **E3 — targeted correction** | `supersedes` is unreachable from extraction; no affected-slice computation; no delta; the target-document is still identified with the conversation. | FE-1479 (targeted re-elicitation), FE-1478 (provenance read), FE-1439 (durable session / document boundary) | | **E4 — the real entry** | Client-tool results do not return to the elicitor; retry/abandonment semantics unproven; realization gated. | FE-1438, FE-1420, FE-1480 | -| **E5 — the teaching layer** | The harness teaches eight sentences; the plugin runbook carries five-sixths harness method that gherkin would repeat; the parser reads the floor and anchor from prose by convention. Opened by E1's landing ([S-008](STRATEGY-LOG.md#s-008)); designed by [ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md) (proposed). | FE-1431 (authoring surface: schema, `plugin.yaml`, key reader), FE-1406 (`packages/repertoire`), FE-1393 (zero new keys) | +| **E5 — the teaching layer** | The harness teaches eight sentences; the plugin runbook carries five-sixths harness method that gherkin would repeat; the parser reads the floor and anchor from prose by convention. Opened by E1's landing ([S-008](STRATEGY-LOG.md#s-008)); designed by [ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md); converged by co-authoring both plugins ([S-009](STRATEGY-LOG.md#s-009)). | FE-1431 (authoring surface: schema, `plugin.yaml`, key reader), FE-1406 (`packages/repertoire`), FE-1393 (zero new keys) | ```text skeleton (construct job; proves the loop, produces fixtures) @@ -51,17 +52,19 @@ reviewer lane (review-and-revise job; the acceptance proof) FE-1420 retry/abandonment safety -> FE-1438 client-tool return -> FE-1439 durable session FE-1478 provenance read -> FE-1480 scaffold/realization -> FE-1479 targeted correction join -authoring lane (E5; alongside the skeleton run, joins it at a second run over the migrated plugin) -FE-1431 schema + plugin.yaml + key reader; SDCPN plugin migrated --> FE-1406 packages/repertoire: every guidance and runbook key filled; binding renders key -> default -> cell --> FE-1393 gherkin fills cells only, adds zero keys (generality check) +authoring lane (E5; a convergence cycle alongside the skeleton run, joining it at a run over the migrated plugin) +each cycle: write schema + plugin-sdcpn/plugin.yaml + plugin-gherkin/plugin.yaml + repertoire together + -> review: does every key plausibly serve both? press against the CPS edge material + -> run where a run exists -> edit; the catalogue freezes when a cycle changes no key +FE-1431 (schema, plugin.yaml, key reader) | FE-1406 (packages/repertoire) | FE-1393 (gherkin, zero keys) advance together ``` Arrows are strategic order. The skeleton lane and the reviewer lane run in parallel; they join at FE-1479, whose "affected slice", "re-evaluate", and "delta" moves consume E1's fold and completion. No hard blocker chain remains from the retired design queue. The authoring lane's sizing -(FE-1406 as a package, FE-1431 as the authoring surface) is [S-008](STRATEGY-LOG.md#s-008)'s and -waits on the ADR-0007 gate before Linear reflects it. +(FE-1406 as a package, FE-1431 as the authoring surface) is [S-008](STRATEGY-LOG.md#s-008)'s; its +method — both plugins written together, the catalogue converging — is [S-009](STRATEGY-LOG.md#s-009)'s. +Linear reflects both as of 2026-08-25. ### Proof bundle for the selected frontier @@ -109,7 +112,6 @@ The read-only Linear graph supplies mechanical availability, never priority. | FE-1480 executable realization unavailable | FE-1438; [ADR-0005](../adr/0005-model-assisted-sdcpn-realization.md) | Client tools return code diagnostics to the elicitor. | 2026-08-25 | Scaffold work may proceed; no runnable FE-1480 proof until the gate opens. | | Final use case outstanding | Dora; FE-1476 / September Plan | Dora confirms or changes it. | 2026-08-25 | If creation is required, Proof 1 becomes acceptance-relevant rather than a harness proof; reconcile ADR-0004/proof. | | Deferral licensing (completion spec rules 17–19) unbuildable | [elicitation-completion](../specs/elicitation-completion.md) rules 17–19; FE-1480 / [ADR-0005](../adr/0005-model-assisted-sdcpn-realization.md) | A durable projection delivery exists for an evaluated revision. | 2026-08-25 | E1 supplies the report and revision (FE-1497, #9325); rule 18 makes licensing `false` without a delivered projection, so no issue is opened. When FE-1480 delivers, it is one read-time function beside `evaluateCompletion` plus a binding hook at settlement; no new persistence. | -| ADR-0007 awaiting ratification | Lu; [ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md), PR #9327 | Lu accepts, amends, or rejects the record. | 2026-08-25 | Until accepted, FE-1406, FE-1431, and FE-1393 keep their S-007 scope in Linear and E5 is design-only on its branch. On acceptance: the three Linear edits, the glossary and SPEC-LEDGER amendments, then FE-1431 starts. | | Truck-fleet dossier missing from the repository | FE-1382 is Done but its promised `docs/reference/research/` artifact is absent. | Artifact path/branch is supplied or a reviewed replacement is selected. | 2026-08-25 | The generality half of Proof 1 uses a fixture derived from the inbox truck SDCPN and Layer B's worked example; claim no dossier-backed domain provenance. | ## Decision-relevant beliefs and unknowns @@ -142,6 +144,8 @@ The read-only Linear graph supplies mechanical availability, never priority. - The teaching layer is built as topology — a package, fixed keys, a schema, gates — with each layer paired with the document that states its intent, never as spec prose alone; and it is not rescoped without run evidence ([S-008](STRATEGY-LOG.md#s-008), [ADR-0007](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md)). +- The key catalogue is a working set until a cycle changes no key: fix it by writing both plugins + against it, not by decree ([S-009](STRATEGY-LOG.md#s-009), ADR-0007 decision 9). ## Stop or replan diff --git a/libs/@hashintel/brunch-agent/docs/control/STRATEGY-LOG.md b/libs/@hashintel/brunch-agent/docs/control/STRATEGY-LOG.md index 954d80e94f3..549bb6e14d4 100644 --- a/libs/@hashintel/brunch-agent/docs/control/STRATEGY-LOG.md +++ b/libs/@hashintel/brunch-agent/docs/control/STRATEGY-LOG.md @@ -270,3 +270,41 @@ than the plugin it teaches (the instrument-larger-than-the-thing heuristic, appl [lineage audit](../evidence/proofs/audits/harness-teaching-lineage-audit.md), [penciled directions 2026-08-14](../archive/planning-inputs/penciled-directions-2026-08-14.md), [SDCPN plugin file](../../packages/plugin-sdcpn/plugin.md), FE-1406, FE-1431, FE-1393, FE-1497 + +### S-009 + +**Date:** 2026-08-25 + +**Trigger/evidence:** Lu accepted ADR-0007 with one caveat: fixing the precise key catalogue now +would be counter-productive. The evidence behind the caveat is the FE-1482 arc itself — an agent +can produce a plausible plugin definition from a given structural and semantic schema in minutes, +so the design activity being left on the table is not writing the catalogue but pressing it: two +test-case plugins (`sdcpn`, `gherkin`) that must both read well under one schema, and a body of +process-modelling edge material (the CPS grilling inputs, the truck-fleet and coating cases, the +FE-1360 literature deposit) that the key set must be general enough to cover, specific enough to +direct, and flexible enough not to bind to. + +**Decision:** Converge the catalogue by co-authoring. Each cycle writes the schema, both plugin +files, and the repertoire together; reviews whether every key plausibly serves both plugins and the +edge material; runs the result where a run exists; edits. FE-1431, FE-1406, and FE-1393 advance in +the same cycle rather than in the sequence S-008 gave them. Keys may be added, merged, or dropped +inside a cycle, recorded in the package changelog; the catalogue freezes when a cycle changes no +key and a third-formalism sketch (formal verification) fills cells only. Rejected: freezing the +catalogue from the ADR (untested structure, the failure the record shows); and writing the SDCPN +plugin first with gherkin as an after-the-fact check (the S-007 order, which would let one +formalism shape the schema before the other pressed it). Complements S-008 (amending its lane +order); supersedes nothing. + +**Consequences/cuts:** STEERING's authoring lane becomes a cycle; the ADR-0007 gate closes; the +ADR gains decision 9; the three Linear issues are rewritten to advance together. The catalogue's +changelog lives in `packages/core` beside the schema. A cycle that changes no key is the freeze +signal, and the first one is a recorded event. + +**Revisit when:** three cycles pass without the set shrinking or stabilising (the pressure is not +converging it); or the two plugins need different groups rather than different cells (the +one-schema premise fails); or a run contradicts what a review call plausible. + +**Supersedes:** none + +**Evidence links:** [ADR-0007 decision 9](../adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md), +[S-008](#s-008), [grilling inputs](../archive/planning-inputs/), FE-1482, FE-1406, FE-1431, FE-1393