I3163 — Each episode boundary derives whether evolve is due — skip, defer or run — and the next session is told why

At episode close in lib/session.sh, derive once a readiness verdict from the candidate groups, their recurrence and routes, the last evolve.run, live mesh claims, and a cooldown and budget declared in policy; record it as a ledger event even when it is skip; name it in the SessionStart briefing, with a directive on run, and in brief.session, CLI, HTTP, MCP and /ui/knowledge; 'run' tells the session to run the evolve skill, never promotes.

READY wave 0 · p1 · implementation profile · parallel safe

Part of knowledge-acts-on-what-it-learns — The repository decides when to evolve its layer, and a session carries it out.

Ready. Every dependency is done, so majordomus plan start I3163 will be accepted.

Objective

Why

Owner, 2026-10-16: wire /evolve in automatically at the right time. The skill lists when to use it; nothing derives it. ADR 0091 keeps promotion a person's act. brief.rs is brief.session (peers, mesh, queues); case 710 exercises the briefing in lib/context.sh. Derives triggered by compaction (lib/capture.sh:1797) would multiply verdicts per episode. Source c274#2 lists the hard conditions: no concurrent evolution on the scope, no conflicting merge or deploy, new evidence since the last run, rollback available. On 2026-10-18 f6 settled the overlap on the mesh: what a session does next at entry is proceed.plan's answer (I2972), which this issue reads; the evolve-readiness verdict stays here. It waits on in-flight work not yet on master: I2972. Proposed in ADR 0183 (Evolution is scheduled at the episode boundary and carried out by a session; nothing promotes itself) (proposed; it carries no authority until the owner accepts it). Sources: chatgpt-majordomus:c197#8, chatgpt-majordomus:c274#2.

Current state

No verdict; evolve runs when someone calls it and leaves no typed event of its own; brief.rs is brief.session and carries no knowledge content.

Desired state

Every closed episode carries the verdict and its factors.

Scope

lib/knowledge.sh
apps/majordomus-cli/src/capability/builtin/knowledge_base.rs
apps/majordomus-cli/src/capability/builtin/brief.rs
share/events.yaml
.ai/repo/policy.yaml
.ai/repo/skills/evolve/SKILL.md
lib/context.sh
lib/session.sh
apps/majordomus-cli/src/ui/knowledge.rs
share/schemas/majordomus/policy/policy.v1.schema.json
share/skeleton/policy.yaml
share/allow/policy.txt
.ai/repo/adrs/0183-evolution-is-scheduled-at-the-episode-boundary-and-carried-out-b.md
.ai/repo/adrs/0118-a-session-leaves-what-it-observed-and-one-candidate-per-defect-is-routed.md
.ai/repo/project/intents
docs/CLAIMS.yaml
docs/claims/knowledge-served-on-every-surface.md
site/content/guarantees/knowledge-served-on-every-surface.md
test/cases/710_briefing_names_the_candidates.sh
test/cases/3004_evolve_is_a_procedure_of_existing_commands.sh
apps/majordomus-cli/src/cockpit
site/content/guarantees

Out of scope

Running evolve from the hook
Promoting a candidate
Starting evolve from a hook or without a session
Writing a verdict from knowledge derive

Dependencies

None. This issue is a root of the graph.

What waits on this

Acceptance criteria

Every closed episode records a verdict with its factors
The next brief names a 'run' verdict
Cooldown and budget are respected
Each new case named here takes its number from `scripts/case-numbers next` and is announced on the board before the file is written (ADR 0053); a case number written in this record before that is provisional
The verdict is written exactly once per episode, at episode close in lib/session.sh, and never by knowledge derive run from compaction, by hand or from the evolve skill
The SessionStart briefing (lib/context.sh via mj_knowledge_briefing_section) names the verdict and its factors, and on 'run' gives the directive to run the evolve skill now with its reasons; the case asserts the directive
brief.session reads the latest verdict from the ledger, so the CLI and MCP brief carry it to Codex and Gemini sessions without their hooks
One evolve.run event, declared in share/events.yaml and written by the evolve skill at its start and end with the commit range, marks each run; the cooldown and the new-evidence condition read it, and no other issue adds a second marker
'run' is given only when no live mesh claim covers the evolve scope (else defer), no landing or release claim is in progress (else defer), and evidence newer than the last evolve.run exists (else skip); each factor is listed with the verdict
The evolve skill takes an exclusive mesh claim on its scope before acting on 'run', reports a refused claim and does not retry it, and lands its change through a pull request so that a revert rolls it back
An episode whose ledger holds an evolve.run closes with skip and the factor 'this episode evolved'
The verdict, its factors and the last evolve.run are shown on CLI, HTTP, MCP and /ui/knowledge, with a guarantee page under site/content/guarantees
Cooldown and budget are optional policy keys with defaults, declared in the policy schema and skeleton; doctor passes on a policy without them
ADR 0183 is accepted and ADR 0118 is amended to reference it
The criterion evolve-readiness-is-derived is rewritten to evidence: test with the allocated case path, and that case runs in this issue's validation
The next actions the briefing names at entry are proceed.plan's answer (its selected issue, reason and next step), read and never derived a second time

Validation

bash test/run.sh 710_briefing_names_the_candidates 3004_evolve_is_a_procedure_of_existing_commands

Evidence required

case_evolve_readiness_is_derived

Evidence

None recorded. Every token above needs a command or an artifact behind it before this issue can be completed; narrative is refused.

Timeline

started: —
verified: —
completed: —

Those three fields, the evidence above and the state of the dependencies are all the status is made of. There is no status field to disagree with them.

Canonical record: .ai/repo/project/issues/I3163.yaml. Read it back with majordomus plan show I3163.