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 99322d53cc7..19750651af5 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-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 new file mode 100644 index 00000000000..d6aac0c31f3 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md @@ -0,0 +1,207 @@ +# ADR-0007: Harness teaching meets plugin content at fixed keys + +Date: 2026-08-25 +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 +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. + 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. + + **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. + +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 +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. 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, + 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/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 64c91b4d84c..4fa8df4dd9c 100644 --- a/libs/@hashintel/brunch-agent/docs/control/STEERING.md +++ b/libs/@hashintel/brunch-agent/docs/control/STEERING.md @@ -17,9 +17,11 @@ 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) (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 @@ -29,7 +31,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 +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); 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) @@ -49,15 +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 -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; 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. +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; 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 @@ -113,7 +120,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 +141,11 @@ 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)). +- 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 @@ -147,6 +160,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..549bb6e14d4 100644 --- a/libs/@hashintel/brunch-agent/docs/control/STRATEGY-LOG.md +++ b/libs/@hashintel/brunch-agent/docs/control/STRATEGY-LOG.md @@ -217,3 +217,94 @@ 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 + +### 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 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..4490b64b013 --- /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-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. + +## 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.