FE-1406: Audit the harness-teaching lineage and propose the fixed-key plugin contract (ADR-0007)

[lunelson]

🌟 What is the purpose of this PR?

Brunch has always had a clear answer for what to notice in an interview — 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: 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. Kernel §11.5 has said since 2026-08-11 that this craft is harness-owned ("guidance ownership follows vocabulary ownership"), and every design station since then has affirmed it and rescoped it down. This pull request does two things about that: it audits every form the idea took, and it proposes ADR-0007, which fixes the plugin authoring surface as a set of harness-owned keys so that the teaching layer has a home a test fails on when it is missing. It also records the strategy (S-008) and reconciles STEERING, so the frontier shows the authoring lane that builds it.

Draft: documentation only, no code. Opened for Lu's ratification of the ADR; the Linear edits it implies wait on that.

🔗 Related links

• FE-1406: Build the harness repertoire (internal; owning issue)
• FE-1431, FE-1393 (internal; the other two issues the ADR resizes)
• Decision: libs/@hashintel/brunch-agent/docs/adr/0007-harness-teaching-meets-plugin-content-at-fixed-keys.md
• Evidence: libs/@hashintel/brunch-agent/docs/evidence/proofs/audits/harness-teaching-lineage-audit.md
• Source of the key set: docs/archive/planning-inputs/penciled-directions-2026-08-14.md
• Strategy: docs/control/STRATEGY-LOG.md S-008; frontier: docs/control/STEERING.md (E5)
• Amends: docs/adr/0006-plugins-per-target-formalism.md decisions 2 and 5

🚫 Blocked by

Nothing in code. Stacks on main; independent of the FE-1404 / FE-1497 stack, which it describes but does not touch.

🔍 What does this change?

The audit (docs/evidence/proofs/audits/harness-teaching-lineage-audit.md) — fifteen dated restatements of the idea from 2026-08-06 to 2026-08-25, the vocabulary each used (lenses, kernel cards, strategy quiver, motions, movements, moves, repertoire…), the layer each assigned it to, what moves it enumerated, and what became of it. Eight findings that never found a home, among them: the split rule was named in canon and designed nowhere; sequence and selection were never separated; rabbit_holes (anti-guidance) was named once and lost; the SDCPN construct runbook is mostly harness craft. A strain appendix lists the places the current design pulls against itself.

ADR-0007 (proposed) — eight decisions:

1. One principle for every key: the harness defines and teaches the concept and ships its default; the plugin specialises it in the harness's terms; the rendered instruction text interleaves them, key → harness default → plugin cell. Cells add, never override. Adding a key is an amendment; a plugin that needs one fails the generality test.
2. Sixteen fixed keys in four groups: contract data (ontology, schema, patterns — machine-matchable only), guidance typed by mechanism (lenses, techniques, movements with slice/sweep, licenses, motifs, smells, rabbit_holes, failure_modes), per-job runbooks (kickoff, trajectory, close), machinery (checks, tools).
3. Words: mechanism types license / technique / attention / anchor; repertoire for the harness's own filling of the keys; selection vs sequence; posture is produced by kickoff and never stored.
4. The jobs construct and review and revise are harness vocabulary.
5. The surface never selects; the agent does.
6. Conversational triggers are guidance, not patterns: SDCPN P06/P10/P12 become techniques, P09/P11 become movements.sweep; their pattern ids retire.
7. Admission by evidence — the first repertoire text comes from FM-12/14/15, the v0 prompt's seven headings, GEN-Q02's batching license, and the lifted rows; nothing because it sounds right.
8. Topology: packages/repertoire depends only on core and is rendered by bindings; plugins never import it. A plugin is plugin.yaml validated by a JSON schema in core plus src/. Gates: unknown key rejected; repertoire fills every guidance and runbook key; a plugin may leave cells blank and may add no key.

Control surfaces — S-008 appended (complements S-007; the slice forced the layer, so it is built as code and gates with each layer's intent documented, not as spec). STEERING gains epicentre E5 (the teaching layer), the authoring lane FE-1431 → FE-1406 → FE-1393 running alongside the skeleton run, an ADR-0007 ratification gate owned by Lu, a new belief row, a sequencing cut, and a stop/replan trigger against rescoping the repertoire without run evidence. The "controller read path is small" belief's open probe (is the 378-line parser an argument for data?) is answered yes.

🏗️ Agent notes

Commits

• 80b8d8dad9 Audit the harness-teaching lineage and propose ADR-0007 (v1: eight move headings)
• 376e17da48 Fix the harness-teaching layer as keys and steer toward building it (v2: sixteen keys in four groups; S-008; STEERING)

Why v2 replaced v1

v1 proposed eight fixed move headings inside the runbook. Lu's re-reading of the 2026-08-14 penciled directions showed the richer key set was already stated there, that most of its keys are job-independent (so they do not belong inside a runbook), and that every key follows the same principle — formalism-specific direction in harness-defined concepts. v2 keeps the two dimensions v1 found (sequence in the runbook keys, selection in the guidance keys) and puts them under one rule.

What waits on ratification

• Linear edits to FE-1406, FE-1431, FE-1393 (drafted; not written — Linear writes need explicit approval).
• Glossary changes in CONTEXT.md (Plugin by keys; Runbook = the three runbook keys; new Repertoire, Key, Mechanism type, Posture; ElicitationPack retired) and SPEC-LEDGER §11.5 → designed.
• Then FE-1431 starts: the schema and key reader in core, plugin.yaml, SDCPN migration.

Gates

packages/core architecture tests 119/119 (docs-index, control-surfaces, topology, Flue placement); lefthook pre-commit (oxfmt, markdownlint) passed on both commits. Brunch Markdown is excluded from oxfmt by design.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

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

📜 Does this require a change to the docs?

The changes in this PR:

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

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

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• ADR-0007 is proposed; until accepted, FE-1406/FE-1431/FE-1393 keep their S-007 scope in Linear and the glossary still describes the six-heading plugin file.
• The ADR amends ADR-0006 decisions 2 and 5 but does not edit ADR-0006 itself; that cross-reference lands with acceptance.

🐾 Next steps

• Lu ratifies, amends, or rejects ADR-0007.
• On acceptance: Linear edits, glossary and SPEC-LEDGER amendments, then FE-1431.

🛡 What tests cover this?

• packages/core/test/architecture/docs-index.test.ts — every document indexed, every link resolves (covers the ADR rename).
• packages/core/test/architecture/control-surfaces.test.ts — S-008 parses with all required fields; Supersedes resolves; STEERING remains the single mutable control.

❓ How to test this?

Read the ADR, then the audit's "What never found a home" section against it: every finding there should map to a key or a decision.

📹 Demo

None; documentation only.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 27, 2026 5:56pm
petrinaut	Ready	Preview	Aug 27, 2026 5:56pm
petrinaut-docs	Ready	Preview	Aug 27, 2026 5:56pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 27, 2026 5:56pm

[lunelson]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

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

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

[cursor]

PR Summary

Low Risk
Documentation and accepted ADR only; no runtime, auth, or data-path changes. Follow-on FE-1431/FE-1406 work will reshape plugin authoring and instruction assembly.

Overview
This PR documents how generic interview craft leaves the monolithic plugin Markdown file and lands in a harness-owned teaching layer—no implementation in this change.

It adds ADR-0007 (accepted 2026-08-25), which amends ADR-0006: plugins become plugin.yaml + schema-validated contract data and cells under fixed harness keys (contract, guidance, runbook, machinery), rendered as key → harness default → plugin cell. The harness-shipped packages/repertoire is the designed answer to kernel §11.5’s generic strategy quiver; conversational triggers move from pattern rows to guidance keys (decision 6).

A new harness-teaching lineage audit traces fifteen prior restatements of “what the harness teaches” and motivates the ADR (SDCPN runbook mostly generic method, parser/prose pain).

Control surfaces gain epicentre E5, strategy S-008 (build teaching as topology/gates) and S-009 (converge the key catalogue by co-authoring both plugins), plus SPEC-LEDGER §11.5 → designed and CONTEXT.md glossary updates (repertoire, posture, retired ElicitationPack).

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