diff --git a/README.md b/README.md index c19da61..7c338fb 100644 --- a/README.md +++ b/README.md @@ -48,10 +48,12 @@ motivated it. The skill is accumulated scar tissue, not a design. ## The pipeline -- **Self** routes the work, keeps the maps, and talks to the operator. -- **Imagination** maps the cut: deletes first, an authority map for anything - that changes ownership, and verification naming the rule each test pins. -- **Hands** executes one cut, in small pushed commits, and never updates the map. +- **Self** routes the work, admits the campaign and the operator's rulings, and + talks to the operator. +- **Imagination** specifies each cut: deletes first, an authority map for + anything that changes ownership, and verification naming the rule each test + pins. +- **Hands** executes one cut, in small pushed commits, and admits a report. - **Soul** runs against the executed commits and tries to falsify every promise, building its own probes rather than trusting the report. - **Life** keeps memory honest at phase boundaries. @@ -77,7 +79,8 @@ Claude Code discovers the skill from the `name` and `description` in `SKILL.md`. on Yggdrasil in a capped container. It is a stopgap until Idunn's verify transaction lands. - `references/briefs.md`: brief templates for each faculty. -- `references/cut-map.md`: the shape of the target document and the cut map. +- `references/campaign-state.md`: the typed document set, the selection + recipes every faculty reads state through, and the prose map's shape. - `references/postmortem-template.md` and `references/postmortem-cultcache.md`: the template and the worked example. - `references/epiphany-comparison-2026-09-15.md`: a dated, source-grounded @@ -86,15 +89,16 @@ Claude Code discovers the skill from the `name` and `description` in `SKILL.md`. ## Status -Eureka keeps its pipeline state in committed documents and memory. A campaign in -Epiphany (`notes/eureka-pipeline-state-target.md`) is giving it typed state -instead: Epiphany owns the schemas and admission, and a memory organ owns each -instance's state. +Campaign state is typed. Questions, rulings, cut specs, reports, verdicts, +findings, follow-ups and resolutions are documents in the instance's mind, +held by the Huginn memory organ and reached through the `eureka-state` MCP +tools. Epiphany owns the schemas (`epiphany-pipeline`) and Huginn owns +admission. The committed prose keeps only body facts, the model page and +rationale. -**That work is partly landed and partly unbuilt.** The organ answers typed -queries over the network today. The `eureka-state` client that would let Eureka -agents admit and query through it is not written, and this skill is not wired to -it. +The skill needs `eureka-state` registered with Claude Code (user scope, with +`EUREKA_INSTANCE` and `HUGINN_ENDPOINT`) and a reachable daemon. Without one, +the pipeline stops rather than keeping state anywhere else. Maps and postmortems are public artifacts from the first cut, with the scars left in. That is deliberate: a pipeline whose record has been tidied up is a diff --git a/SKILL.md b/SKILL.md index 71fdbc7..f67ef8f 100644 --- a/SKILL.md +++ b/SKILL.md @@ -7,16 +7,15 @@ description: Eureka runs a foundation change as a faculty pipeline for Claude Co Eureka is the pipeline used by Claude Code agents. It sits next to **Epiphany**, the running organism in `F:\Projects\Epiphany`, and shares its faculty -vocabulary. The difference is substrate: -- **Epiphany** keeps its findings in typed, admitted state that can be queried - by exact filter. Epiphany removed her own vector stack in `856648de`; - semantic search is planned through the Huginn memory organ, which depends on - Qdrant directly. -- **Eureka** currently keeps them in committed docs (the target and the cut - map), subagent reports and memory files. +vocabulary and its document schemas. -Giving Eureka agents typed state tools is the intended next step; see -`references/changelog.md`. +Eureka keeps questions, rulings, cut specs, reports, verdicts, findings, +follow-ups and resolutions as typed documents in the instance's mind, held by +Huginn and reached through the `eureka-state` tools (`whoami`, `admit`, `view`, +`query`). Status is derived from those documents, never written. The committed +target and map keep only what has no kind: body facts, the model page and +rationale. `references/campaign-state.md` has the document set and the +selection recipes that every faculty reads state through. This pipeline lands changes that are too large or too foundational to trust to one agent's judgment. It turns "migrate X" into a sequence of small, verified @@ -35,18 +34,21 @@ editor. See `references/postmortem-cultcache.md` for the evidence. ## The faculties Faculties are postures, not personalities. The root agent is **Self**. It routes -work, keeps the maps, commits the maps, and talks to the operator. Delegate every -other faculty to a subagent with its own brief. A faculty that grades its own -work has lost the point. +work, admits the campaign's frame and the operator's rulings, commits the prose +map, and talks to the operator. Delegate every other faculty to a subagent with +its own brief. A faculty that grades its own work has lost the point. -| Faculty | Runs against | Produces | Must not | +| Faculty | Runs against | Admits | Must not | |---|---|---|---| -| **Imagination** | the Body (source, docs, probes), plus the target | the cut map: the target shape specified to `file:line` | commit code, choose a product fork silently | -| **Hands** | one cut of the map | small pushed commits, a report with evidence | redesign the spec, work around a fork, update the map | -| **Soul** | Hands' *executed* commits | findings, CONFIRMED or PLAUSIBLE, each with `file:line` and a failure scenario | edit, commit, or review a plan (a pass on a plan is Imagination) | -| **Life** | memory surfaces | named mutations and proposals | touch Body code, restate what an owner doc already records | -| **Eyes** (optional) | history, transcripts, logs | a facts file with evidence pointers | conclude or recommend | -| **Operator** | forks and product meaning | rulings | (not an agent) | +| **Imagination** | the Body (source, docs, probes), plus the target | `question`s and `cut_spec`s specified to `file:line`; body facts and rationale go to the prose map | commit code, choose a product fork silently | +| **Hands** | one `cut_spec` | small pushed commits, then one `cut_report` | redesign the spec, work around a fork | +| **Soul** | Hands' *executed* commits | one `verdict` and its `finding`s | edit or commit a repo, or review a plan (a pass on a plan is Imagination) | +| **Life** | memory surfaces | nothing: named mutations and proposals | touch Body code, restate what an owner records | +| **Eyes** (optional) | history, transcripts, logs | nothing: a facts file with evidence pointers | conclude or recommend | +| **Operator** | forks and product meaning | rulings, which Self admits | (not an agent) | + +Admitting is a write to the Mind, not to the Body. Soul stays read-only on +repos and still admits its verdict. The operator's doctrine defines the faculties. Read the Soul and Imagination lines of the operational litany in `~/.claude/CLAUDE.md`. In short, a pass is @@ -55,16 +57,20 @@ finished when Hands can go straight to the cut. ## The loop -### 0. Map the substrate, scope, target +### 0. Reach the mind, map the substrate, scope, target +- **Call `whoami` first.** If `reachable` is false, stop and tell the operator. + Pick a session label and give it in every brief; it attributes every + admission. - **Map the real substrate before you propose anything.** Run parallel read-only exploration of the old system and the new one, of any prior attempts and why they failed (git history, rollbacks), and of every consumer across repos. -- Write the **target document**: the ends, not the means. Name the invariants - that must survive (wire parity, one owner per decision, what the operator - refuses to lose), the canonical implementations, and what is explicitly **not** - a consumer. For example, AetheriaEve was "taxidermy", and saying so up front - saved every later pass from considering it. +- Admit the stewardships, the `campaign` and the `target` (Self's checklist in + `references/briefs.md`). The target holds the ends, not the means: labelled + invariants that must survive (wire parity, one owner per decision, what the + operator refuses to lose), and what is explicitly **not** a consumer. For + example, AetheriaEve was "taxidermy", and saying so up front saved every later + pass from considering it. - State the scope boundary out loud. The earlier Aetheria attempt failed because it bundled cache, mesh, eve and daemons into one change. One foundation per pipeline. @@ -90,29 +96,25 @@ questions, and none of them needed a line of source to answer: So produce one table before mapping any cut, with a row per persistent kind and three columns: what names it, what happens to it over time, and who decides. -**No cut is mapped while a cell is empty.** This costs a page and an hour. +**No cut is mapped while a cell is empty.** This costs a page and an hour. The +table is the model page in the prose map; no kind carries it. -Assemble the operator's forks in the same pass, as one batch. In that campaign -they surfaced across five cuts instead, so rulings kept landing on code that was -already written. Discovering that the operator wants something different is not -waste; discovering it after the code lands is. +Admit the operator's forks in the same pass, as `question`s in one batch. In +that campaign they surfaced across five cuts instead, so rulings kept landing on +code that was already written. Discovering that the operator wants something +different is not waste; discovering it after the code lands is. ### 1. Imagination maps the cut -Brief an Imagination agent to produce the **cut map**: an ordered list of cuts -against the current Body. Each cut carries: - -- repo and branch; -- **deletes first**, with exact paths and line counts; -- keeps and moves; -- adds; -- per-file changes with `file:line` against a named HEAD, **for code that - exists**; -- an **authority map** for anything that changes ownership: owner, inputs, - outputs, derived state, forbidden writers, shared paths, deletion line; -- **verification**: exact builds, tests with the rule each one pins, negative - greps, and what only the operator can check; -- a subtraction-ledger estimate. +Brief an Imagination agent to admit the cuts: one `cut_spec` per cut against +the current Body, ordered by `depends_on`. The fields are the spec standard: +repo, branch and base; `deletes` first, with exact paths and line counts; +`keeps_moves`; `adds`; `file_changes` at `file:line` **for code that exists**; +an `authority_map` for anything that changes ownership; `verification` (builds, +tests with the rule each pins, negative greps, operator checks); an `estimate` +for the ledger; and the `rulings` and `questions` it rests on. A changed spec is +a new revision, admitted with the resolution that supersedes the old one, never +an edit. **Spend the detail where the map can be wrong, not where Hands will rewrite it anyway.** Anchors against existing code earn their length: they say what to @@ -163,22 +165,24 @@ the data the consumer reads. Imagination must establish mechanism claims by running code: probes, scratch builds, decoding a real file. It must not reason from names. A map built on -unprobed claims is where bad cuts come from. Real forks come back as **explicit -operator questions with a recommended option**, never chosen silently. +unprobed claims is where bad cuts come from. The probes and their results go in +the prose map's body facts. Real forks come back as **`question`s with a +recommended option**, never chosen silently. -Iterate the map with further Imagination passes, not Soul passes, until Hands -could go straight to the cut. Commit the map; it is the durable record of the -means. +Iterate with further Imagination passes, not Soul passes, until Hands could go +straight to the cut. The admitted specs are the durable record of the means. +Self commits the prose map when its body facts, model page or rationale change. -Templates are in `references/briefs.md` and `references/cut-map.md`. +Templates are in `references/briefs.md` and `references/campaign-state.md`. ### 2. Operator rulings -Bundle the open questions. Give each one options and a recommendation, and say -what depends on the answer. Record every ruling in the map, dated, with the -operator's words when they carry meaning the paraphrase would lose. When a ruling -supersedes an earlier one, mark the old text as history instead of leaving two -live designs. +Put the open questions to the operator together, from the open-items recipe, +each with its options, recommendation, and what depends on the answer. Self +admits every answer as a `ruling` that answers its question, keeping the +operator's words in `operator_quote` when they carry meaning a paraphrase would +lose. A ruling that changes an earlier one supersedes it by a `resolution`, +never by an edit, so the rulings-in-force recipe shows one live design. **The operator channel is this session.** Eureka has no Persona: Self is the operator-facing surface, because a question costs one message and loses no @@ -192,8 +196,9 @@ Distinguish a real fork from a default. "Should I use the conventional thing" is not a question. "3-5 are not decisions," as the operator put it, is the failure of asking about non-decisions. Weigh proportion too: a fork that guards only against the project's own code, such as how strictly to enforce an internal -tripwire, gets a default and a recorded follow-up. Asked how much one such -question mattered, the operator said not at all. +tripwire, gets a default and a recorded follow-up: a ruling with +`authority: Defaulted`, plus a `follow_up`. Asked how much one such question +mattered, the operator said not at all. ### 3. Hands executes one cut @@ -204,7 +209,7 @@ stats and shield Hands got "loopy" past 400k, and a StreamPixels fix batch past 550k produced sloppy code. Treat 0.5M as the danger line, never the target. Before dispatch, Self estimates what the run will carry: -- the brief, with the cut quoted inline; +- the brief, and the `cut_spec` Hands views; - the source Hands must read to edit safely: the files it touches and their direct callers, not the repo; - one verification round at the end and one fix round, with their output; @@ -220,12 +225,14 @@ Splitting a cut always beats a bloated brief. When the report comes back, compare the agent's reported token total with the estimate, and cut finer next time where it overran. -Brief Hands with the cut's section of the map, the standing rulings restated -briefly, and the verification. The brief says: +Brief Hands with the `cut_spec` id, the campaign session label, and the +rulings in force that the spec cites. Hands reads the spec with `view`, so +nothing is pasted or paraphrased. The brief says: - **Follow the spec, do not redesign.** If the Body contradicts the spec, fix the - smallest thing that keeps the spec's intent true and report the discrepancy. If - it is a real fork, **stop and report**. + smallest thing that keeps the spec's intent true and record the discrepancy in + the report's `deviations`. If it is a real fork, admit it as a `question` + raised in the spec, **stop, and report**. - **Gaps are filled in their owner, never worked around locally.** If CultMath lacks a function, CultMath gets it; the consumer does not grow a helper. - **Delete before adding.** No shims, no compatibility layers the map did not @@ -242,8 +249,9 @@ briefly, and the verification. The brief says: name: a behavioural test is missing, a fixture is degenerate (see below), or the mutant is equivalent and gets a one-line reason. Boundary flips on float thresholds are equivalent by default and are not chased. The score is - not a gate; the triaged survivor list is the record, and Self commits it in - the map. Soul reruns the tool on the range rather than trusting Hands' + not a gate; the triaged survivor list is the record. It goes in the report's + `mutations`, and a survivor that stays alive goes in `deviations` or becomes a + `follow_up`. Soul reruns the tool on the range rather than trusting Hands' triage. - **No committed hand-written mutation suites, and no fallback harness.** The operator ruled this on 2026-09-22: "Better to have nothing than a @@ -302,18 +310,20 @@ briefly, and the verification. The brief says: instance names, or only their first bytes, survived both suites, because no fixture pair had ever shared a length. The rule had no defence and the suite said it had two. -- Report: commits (and which don't build), verification output, mutation - results, spec discrepancies, forks, structural delta. Hands never updates the - map. +- Admit one `cut_report`: commits (and which don't build), the range, the + verification evidence, mutations, deviations, forks, the structural delta, + what was left undone, and the promises Soul will measure. The report to Self + is its id plus raw output too long for an evidence line. Hands never edits the + prose map. Parallel Hands are fine when they touch different repos or worktrees. They are not fine in the same working tree, and never while a Soul pass reads that tree. ### 4. Soul falsifies -Brief Soul on the exact commit range, with the operator invariants and Hands' -promises listed as claims to falsify. Point it at the specific places a shortcut -would hide. Soul: +Brief Soul with the `cut_report` id and the session label. The report carries +the exact range and Hands' promises; the target in force carries the operator +invariants. Point Soul at the specific places a shortcut would hide. Soul: - reruns builds, tests and captures itself instead of trusting the report; - reruns a selection of Hands' mutations, and designs its own that are not plain @@ -323,11 +333,13 @@ would hide. Soul: real compiler, run the other runtime's decoder; - checks the invariant at the layer where it would actually fail (wire bytes, another runtime, the editor, the GPU), not only in the unit test; -- reports each finding as CONFIRMED or PLAUSIBLE, with `file:line`, a failure - scenario and severity, then lists the promises that held. +- admits one `verdict`, measuring every promise in the report, together with + its `finding`s: each `Confirmed` or `Plausible`, with locations, a failure + scenario, a severity and the target invariants it breaks. -Soul works read-only. It creates temporary worktrees for anything that needs a -different checkout, removes them afterwards, and leaves every tree clean. +Soul works read-only on repos. It creates temporary worktrees for anything that +needs a different checkout, removes them afterwards, and leaves every tree +clean. **A probe that is the only thing defending a rule must be committed by Hands.** Soul cannot commit, so its harnesses die with the session. In the QUIC cut the @@ -344,12 +356,14 @@ exists. ### 5. Triage and repeat -For each Soul finding, decide: +For each finding in force, decide: -- **fix now:** brief Hands with the finding and the target shape; -- **operator fork:** ask, with a recommendation; -- **record as a follow-up:** the map gets the item, the file and the reason it can - wait. +- **fix now:** brief Hands with the finding's id; the landing closes it + `Fixed`; +- **operator fork:** a `question` raised in the finding, with a recommendation; +- **defer:** a `follow_up` with the reason it can wait, and the finding + resolved `Deferred` to it; +- **record** or **withdraw:** a `Recorded` or `Withdrawn` resolution. Run Soul again on the fix batch. **Do not cap the Soul loop early on a foundation cut.** In the CultCache migration, Cuts 6 and 6b each needed four Soul passes, and @@ -393,13 +407,15 @@ later. After each cut: -- Self updates the map's status header: what landed at which SHAs, what was - verified, what Soul found, what was recorded. -- Self reconciles the subtraction ledger against what actually landed. A miss is - allowed, but it must be explained. The CultCache core missed its size target - by roughly 1,200 lines, and nobody looked, because the ledger stopped being - updated after Cut 4. -- Self commits and pushes the map. Hands and Soul never touch it. +- Progress is a query, not a section to update: the recipes for specs with no + report, reports with no verdict, and open items. +- Self reconciles the subtraction ledger with the ledger recipe (each spec's + `estimate` against its reports' `structural_delta`). A miss is allowed, but + it must be explained. The CultCache core missed its size + target by roughly 1,200 lines, and nobody looked, because the ledger stopped + being updated after Cut 4. +- Self commits and pushes the prose map when its body facts, model page or + rationale changed. Hands and Soul never touch it. - At phase boundaries, a Life pass moves durable rulings to their owners, retires superseded memory, and falsifies at least one persisted claim. @@ -408,9 +424,19 @@ and reconciles the target doc with the Body. ## Self's discipline -- **Keep the maps committed and current.** Hands will read stale text as live - design. After a ruling changes a design, sweep the map and the target doc for the - old version the same day. +- **Never restate typed state in prose.** Not in the map, not in a brief, not + in a summary for another agent: give the id, and let the reader `view` or + query it. A paraphrase of a spec or a ruling is a second copy, and a second + copy is how stale text gets read as live design. Tell the operator what + matters in words. Tell agents the id. +- **When the organ is unreachable, stop.** Say so to the operator and wait, or + work on something that does not touch campaign state. Never keep the record in + prose or memory "until it is back": that is a second copy, and it breaks the + invariant that the mind is the only store. +- **Keep the prose map current.** After a ruling changes a design, sweep the + map's body facts and rationale, and the target doc, for the old version the + same day. The specs and rulings need no sweep, because their resolutions + already say what is in force. - **One owner per decision, in code too.** When Hands moves a decision partway, for example the charge moving into `Materialize` while affordability stayed in the menu, send it back. Split authority is the defect Soul most often finds. @@ -433,14 +459,10 @@ and reconciles the target doc with the Body. stopped and reported a concurrency hazard instead of forcing the checkout. **A brief that names a repo path without naming a worktree is a defect in the brief.** -- **Commit maps to `main`, not to whatever branch Self is standing on.** A map - is only current if it is current on the branch the reader has. On 2026-09-22 - a Hands agent on the selection cut reported that the map had no fix-batch-4 - section: the live copy was on Self's own working branch, `main` was a day - behind, and the work branch carried a copy from five days earlier. It worked - from its brief and said so, which is the only reason this surfaced instead of - producing a cut built on stale design. **Also name the map's branch in every - brief**, so a faculty reading a different one notices. +- **Commit the prose map to `main`, and name its branch in every brief.** On + 2026-09-22 a Hands agent found no fix-batch-4 section: the live copy was on + Self's working branch, and `main` was a day behind. Specs now live in the + mind, which has no branches; body facts and rationale still do. - **A subtraction budget is pressure, not a metric.** Say so when you set it, so Hands knows escalating a miss with an argument is allowed. Treat a suspiciously clean hit as a sign that unrelated code was deleted to meet the number. @@ -455,7 +477,9 @@ and reconciles the target doc with the Body. six times is the strongest requirements evidence anyone will ever get for building the thing, and it is worth nothing once the run closes and the pain is remembered only as "the docs got messy". This is not a reason to wait on - the missing thing or route work to it: work around it and leave evidence. + the missing thing or route work to it: work around it and leave evidence. The + evidence is a `follow_up` whose source is the document where the run felt the + gap, and whose owner is the missing thing's owner. - **Never claim an agent's result before its notification arrives.** ## Git and tooling rules (scars) diff --git a/references/briefs.md b/references/briefs.md index b48ade8..7959e17 100644 --- a/references/briefs.md +++ b/references/briefs.md @@ -1,10 +1,20 @@ # Brief templates These are starting points. Fill in every `<>` placeholder. Each brief should let -its agent act without asking what the invariants are. Paste standing rulings in -short form rather than pointing at a long document the agent may skim. +its agent act without asking what the invariants are. Campaign state is typed: +a brief gives ids and recipe names, and never pastes or paraphrases a spec, a +ruling or a finding. The agent reads those itself. Recipes are in +`campaign-state.md`. + +Every brief that reads or admits campaign state carries: +- the campaign slug ``, and the session label `` for its + admissions; +- the Rehydrate block below, as the agent's first step. ## Contents +- Rehydrate (every faculty that touches campaign state) +- Self: open a campaign, rule, triage +- Imagination: settle identity, lifecycle and authority - Imagination: map or refresh a cut - Hands: execute a cut - Soul: falsify executed work @@ -13,16 +23,55 @@ short form rather than pointing at a long document the agent may skim. --- +## Rehydrate + +``` +Campaign state lives in the instance's mind, through the eureka-state tools. +1. Call whoami. If reachable is false, stop and report that; do not work from + prose or memory instead. +2. Run the recipes named for your faculty in references/campaign-state.md, + with root = . +3. view any id this brief names. +Admit as faculty , agent , session . A refusal +names the rule that refused: fix the batch and admit again. isError means no +answer: stop and report it. +``` + +## Self: open a campaign, rule, triage + +Self's own checklist; Self admits as `SelfFaculty`. + +``` +Open: whoami (the mind's instance document, :instance:self, already +exists). For each repo in scope with no stewardship in force, admit a +stewardship (sequence = latest + 1). Then admit the campaign (every repo a cut +may touch) and target revision 1 (labelled invariants, not in scope, +canonical implementations, doc = the committed target document). + +Rule: for each operator answer, a ruling (answers, choice, authority, and +operator_quote when the words matter). A changed ruling carries a resolution +superseding the old one, in the same batch. + +Triage each finding in force: a Hands brief (Fixed on landing), a question +raised in it, a follow_up plus a Deferred resolution, or a Recorded or +Withdrawn resolution. A missing tool or surface a faculty worked around is a +follow_up owned by the missing thing's owner. + +hand_off is parked (Huginn Cut 12): one mind, no transfer. +``` + ## Imagination: settle identity, lifecycle and authority Run this once, before any cut is mapped. It answers the questions that cause re-cuts, and it needs almost no source. ``` -You are Imagination for . Produce the model page in . Do not -map cuts, do not write code, do not commit; the root agent commits. +You are Imagination for . Produce the model page in . Do not map cuts, do not write code, do not commit; the root agent +commits. -Read and enough of the Body to enumerate the persistent kinds. +Rehydrate (recipes: rulings in force, open items; view the target in force). +Read enough of the Body to enumerate the persistent kinds. Give one table, a row per persistent kind: - Identity: what names it. Is the namespace stated? Is the name injective? Can @@ -32,26 +81,27 @@ Give one table, a row per persistent kind: record looks like afterwards and what is now in force. - Authority: who decides. One owner per decision. Name the forbidden writers. -Then, in one batch, every question only the operator can answer, each with -options and a recommendation, and what depends on the answer. +Then admit, in one batch, a question for everything only the operator can +answer: options, the recommended label, and what depends on the answer. An empty cell is the finding. Say so plainly rather than inventing a plausible -value. Report the cells you could not fill and the source you checked. +value. Report the cells you could not fill, the source you checked, and the +question ids you admitted. ``` ## Imagination: map or refresh a cut ``` -You are Imagination for . Map in so Hands -can go straight to the cut with little reading. +You are Imagination for . Admit a cut_spec for so +Hands can go straight to the cut with little reading. -Edit only . Do not commit; the root agent commits. Do not change code -in any repo. Scratch probes in are fine. +Admit only cut_specs, their superseding resolutions, and questions. In the +prose map at , edit only body facts and rationale. Do not commit; the +root agent commits. Do not change code in any repo. Scratch probes in + are fine. -Read first: -- -- -- +Rehydrate (recipes: rulings in force, open items, specs with no report, one +cut's record for ; view the target in force). Body facts to verify (not trust): - @@ -59,42 +109,39 @@ Body facts to verify (not trust): - Every mechanism claim must come from a probe or a source read, not a name. +Record each probe and its result in the prose map's body facts, and cite them +from the spec by DocRef rather than restating them. -Standing rulings: . - -Spec standard, matching the existing cuts: -- repo and branch -- deletes first, with exact paths and line counts -- keeps and moves -- adds -- per-file changes with file:line against HEAD -- an authority map for any ownership change (owner, inputs, outputs, derived - state, forbidden writers, shared paths, deletion line) -- verification: builds, tests with the rule each one pins, Unity or other - runtimes, negative greps, and the operator checks +The cut_spec's fields are the spec standard. Beyond filling them: +- file_changes against base , for code that exists +- cite in `rulings` every ruling in force the cut rests on - the deploy owner: for any cut that changes what a service needs (transport, env, dependency, state), the recipe, binding and runbook that must admit it, changed in the same pass (Ghostlight, 2026-09-23) - every seam with a foreign owner: the owner's code or published schema the fixture is built from, not our own struct +- refreshing a spec: admit revision N+1 with a resolution superseding + revision N by it, in one batch; never a second spec for the same cut If a cut would not fit one Hands pass under , split it with an explicit order and a verification step for each part. +step 3>, split it into specs ordered by depends_on, each with its own +verification. -Where only the operator can decide, list an explicit question with a -recommended option. +Where only the operator can decide, admit a question with a recommended +option, raised in the spec it blocks. -Report: what changed (briefly), operator questions, findings you could not -assign to a cut, and the HEAD you pinned to. +Report: the ids you admitted, findings you could not assign to a cut, and the +HEAD you pinned to. ``` ## Hands: execute a cut ``` -You are Hands for . The spec is
of at . Read it and -the status header. Follow the spec; do not redesign it. If the Body contradicts -it, fix the smallest thing that keeps its intent true and report the -discrepancy. If you hit a real operator fork, stop and report. +You are Hands for . The spec is . Rehydrate, then view the +spec and each ruling it cites. Follow the spec; do not redesign it. If the Body +contradicts it, fix the smallest thing that keeps its intent true and record the +discrepancy in the report's deviations. If you hit a real operator fork, admit +it as a question raised in the spec, stop, and report. Repo/branch: at HEAD . Check that git status is clean first. Pinned siblings: . Do not change them. @@ -102,7 +149,8 @@ When the brief names a worktree, every tool call's path goes under it: Read, Edit and Write as well as the shell's working directory. An absolute path into the main checkout silently edits the wrong tree. -Standing rulings: . +Standing rules (the skill's own; the campaign's rulings are the ones the spec +cites, read by id): - Gaps are filled in their owner, never with local helpers. - Delete before adding. No shims. - One rule, one path. A simpler case of the rule (one lane, one cell, an @@ -117,10 +165,10 @@ Standing rulings: . Every rule the spec or the operator names gets a behavioural test. Measure the suite with , scoped to this cut's diff (`--since:` or the tool's equivalent), against the final spelling of the -code. Triage every survivor in the report by name and line: killed by a new -test, killed by fixing a degenerate fixture, or equivalent with a one-line -reason. A survivor that weakens a rule and cannot be killed is reported, not -hidden. Code no tool reaches gets behavioural tests at the layer where the +code. Triage every survivor in the report's mutations by name and line: killed +by a new test, killed by fixing a degenerate fixture, or equivalent with a +one-line reason. A survivor that weakens a rule and cannot be killed goes in +deviations, not hidden. Code no tool reaches gets behavioural tests at the layer where the rule is decided, never a committed mutation suite (operator, 2026-09-22). A fix for a proxy-for-truth defect is not done until every other site that draws a conclusion from the same class of evidence has been enumerated and @@ -172,9 +220,9 @@ one head (SKILL.md, step 3); keep it fitting: - **Verify once, at the end.** Not after every edit. A full mutation sweep and a batchmode compile per edit is most of a long run's spend and proves nothing the final sweep will not. -- **Carry the cut inline.** Quote the cut's own section in the brief instead of - pointing at a long map; a worker that reads 900 lines to find 60 has spent - its budget before it starts. +- **Read the spec by id, not the map.** The cut_spec is bounded and holds only + this cut; a worker that reads 900 lines of map to find 60 has spent its + budget before it starts. - **Keep expensive scaffolding alive across cuts** (a pinned dependency worktree, a warm build) rather than creating and removing it per pass. - **Hand back rather than push through.** A worker that finds itself far past @@ -185,7 +233,7 @@ one head (SKILL.md, step 3); keep it fitting: remaining scope looks large. Two Sonnet passes on the selection cut stopped at about 150k tokens with no fork, one of them after fourteen tool calls. Each said the remaining work "did not fit the budget". Both had been pointed at a - 1,500-line map instead of given their cut inline. So state the scope as one + 1,500-line map instead of given only their cut. So state the scope as one deliverable, and say the budget is sufficient for it. The hand-back clause is for a head that is actually full, not for a job that looks big. @@ -208,9 +256,9 @@ replays warnings only when it actually rebuilds. Semantic properties ("exactly one call site", "this step actually runs"): prefer a semantic tool (a Clippy lint, the type system) over a text scanner, or state the scanner's limits in the test itself. -If you work around a missing tool, service or typed surface, report what was -missing and what it would have prevented. The workaround is not the finding; -the gap is. +If you work around a missing tool, service or typed surface, say in the +report's deviations what was missing and what it would have prevented. The +workaround is not the finding; the gap is. Commits: - Small and pushed. @@ -229,21 +277,26 @@ Verification: . - Revert incidental asset churn. Budget: if the cut can't land coherently, stop at a pushed, building commit -boundary with no half-deleted authority, and report what remains. +boundary with no half-deleted authority, and put what remains in undone. -Don't update the map. +Don't edit the prose map. -Report, in this shape and nothing else: -- commits (and which don't build) -- verification output, pasted, not summarised -- mutation results: each entry, its exact edit, its killer or SURVIVED -- spec discrepancies you fixed -- forks -- structural delta (lines, dependencies and formats removed or added) -- what remains -No narrative of the pass, no restating the brief, no reasoning about what you -might have done. Self reads the three things above the discrepancies first -and needs them in that order. +Admit one cut_report for , attempt : +- commits (builds: false for any that don't build), and the range; the head + must be one of the commits +- verification: one evidence entry per build, test run and grep, with the + command as locator and the counts as result +- mutations: each entry, its exact edit (before and after), and whether it + failed as expected; the survivor triage goes with it +- deviations: spec discrepancies you fixed, each with why +- forks: the question ids you admitted +- structural_delta: lines, dependencies, formats and targets removed or added +- landed_names, undone, and promises: each thing you claim the cut now + guarantees, labelled, for Soul to measure + +Report to Self, and nothing else: the cut_report id and receipt, then any raw +verification output too long for an evidence line, pasted, not summarised. No +narrative of the pass, no restating the brief or the report. ``` ## Soul: falsify executed work @@ -251,8 +304,8 @@ and needs them in that order. ``` You are Soul for . Soul preserves invariants by falsifying the promises Hands made about executed work: shortcuts, split authority, trivial tests. -Report findings only. -- Do not edit or commit. +Admit findings only. +- Do not edit or commit in any repo. - Restore after every mutation and leave the tree clean. - Use a temporary detached worktree for other checkouts, and remove it afterwards. @@ -265,16 +318,12 @@ Report findings only. Yielding to announce the wait is the same violation: block in-turn or read the finished output, never end the turn to say you are waiting. -Scope: , commits (base ). Spec:
. +Scope: . Rehydrate, then view the report (its range and its +promises), the cut_spec it cites, and the target in force (the operator +invariants, by label). Admitting your verdict is a write to the mind, not to +a repo. -Operator invariants: . - -Hands promised: -1. -2. -... - -Falsify specifically: +Falsify every promise in the report, and specifically: - - '` and -`git log --grep` on the owner's files, and read the scars in SKILL.md. If it +`git log --grep` on the owner's files, run the precedent recipe, and read the +scars in SKILL.md. If it was tried, cite the commit that removed it and say why the new situation differs, or recommend something else. (2026-09-30: a Soul pass recommended writer-thread ordered delivery in CultCache. That scheduler was built in @@ -317,27 +367,37 @@ measure it, as a mutant that changes how a thing is built can leave what it does untouched, and one that looks cosmetic can move damage to the wrong side of a ship. -Report each finding as CONFIRMED or PLAUSIBLE, with file:line, a failure -scenario and severity. Then the promises that held, one line of evidence -each. Then the numbers: test counts, entries killed, path delta, script -paths. Nothing else: no narrative of the pass, no reasoning about mutants -that died. Name the survivors you retriaged. +Admit one verdict (pass ) and its findings in one batch: +- one claim per promise in the report, Holds, Falsified or Unproven, each with + its evidence (the numbers: test counts, entries killed, the survivors you + retriaged) and the report's mutation labels it reran +- claims of your own for what you attacked beyond the promises +- each finding Confirmed or Plausible, with its locations (file:line), failure + scenario, severity, origin, and the target invariant labels it breaks. A + Falsified claim names a Confirmed finding. - scope is the fix batch's diff -plus one rerun of the suite. Do not re-derive the whole cut unless an -invariant moved. Say in one sentence whether the cut closes. +Report to Self, and nothing else: the verdict id and receipt, and one sentence +on whether the cut closes. No narrative of the pass, no reasoning about mutants +that died. + + scope is the fix batch's +cut_report and its diff, plus one rerun of the suite. Do not re-derive the whole +cut unless an invariant moved. ``` ## Life: phase boundary ``` -Phase boundary: . The authoritative record is ; -don't edit those. +Phase boundary: . The authoritative record is +the campaign's mind (read it through the recipes; you admit nothing) and the +prose map and target doc; don't edit those. Surfaces: . -Candidates for durable memory: . Check each against its owner -doc first and don't duplicate what the owner records. Retire or supersede stale +Candidates for durable memory: . Check each against its +owner first, the mind included, and don't duplicate what the owner records. A +memory that restates a ruling or spec is a second copy: point at the id or +retire it. Retire or supersede stale claims instead of adding corrections next to them. Falsify at least one persisted claim against the Body. diff --git a/references/changelog.md b/references/changelog.md index edaeebb..a6c60f2 100644 --- a/references/changelog.md +++ b/references/changelog.md @@ -1161,3 +1161,23 @@ code path", and "such obviously unnecessary split authority should never pass a `KEY = "value"` lines. Same class, found twice in one day. - The Hands brief template now requires that errors, logs and refusals name the field and the error code, never the value, and that this is pinned by a canary test. + +## 2026-09-30: campaign state is typed (Huginn Cut 15, under Q-H6 A) + +- Evidence: the Huginn wiring map (Epiphany `notes/huginn-organ-cut.md` at `74804d83`, Cut 15). Huginn is live + on Yggdrasil with instance `eureka`, and `eureka-state` exposes four tools (`whoami`, `admit`, `view`, + `query`). The operator's ruling on Q-H6: "every bit of prose we're passing around should be viewed as a + potential liability, *especially* if it's too big to just shove the whole thing into context. We should be + looking for ways to turn what remains into typed state as well." +- Questions, rulings, cut specs, reports, verdicts, findings, follow-ups and resolutions are admitted documents. + The committed map keeps body facts, the model page and rationale, and has no status header, no per-cut + sections and no rulings. A superseded ruling or spec is closed by a resolution, never edited. +- `references/cut-map.md` is replaced by `references/campaign-state.md`: the tools, the document set, the + resolution matrix, the selection vocabulary, and recipes that replace the deleted `open_items`, + `rulings_in_force` and `history` presets. Specs with no report is one query, because the substrate's `cited` + hop takes `exists: false`. +- Briefs give ids and recipe names instead of pasted specs or rulings. Every brief starts with Rehydrate: + `whoami`, then the recipes. Hands reads its spec with `view` and admits a `cut_report`. Soul admits a + `verdict` and its findings; admitting is a Mind write, so Soul stays read-only on repos. +- Self stops when the organ is unreachable and keeps no second copy meanwhile. "Record the substrate you + needed and did not have" stays, and the record is now a `follow_up`.