session-orchestrator 3.19.0 → 3.20.0

package/skills/evolve/SKILL.md

@@ -211,6 +211,34 @@ For each extracted pattern, check if a learning with same `type` + `subject` alr
 - **If exists:** propose confidence update (+0.15 if confirmed by new evidence, -0.2 if contradicted)
 - **If new:** propose as new learning with confidence 0.5
 
+This match is **exact string equality on `type` + `subject`** — it is blind to two records that say the same thing in different words, and it cannot detect a contradiction at all. The `-0.2 if contradicted` branch above has therefore had no producer since it was written. Step 3.3b is that producer.
+
+### Step 3.3b: Relation Judgment (#1016)
+
+> **Cadence: once per candidate.** Step 3.2b's zero-patterns check and Step 3.4's single AUQ are once-per-run; Step 3.5's write is once-per-run. This step is the only per-candidate one in Phase 3 — the pool build happens once, the judgment runs for each pattern that seeds a pool.
+
+> **Runs in `/evolve`, never in a wave.** The pool build is O(N²) over the candidate + corpus union (~13 ms at N=100 records; the viability boundary is ~N=2000). `/evolve` is operator-invoked and off the dispatch hot path — that is the whole reason this lives here and not in `skills/wave-executor/`. Do not invoke it from a wave prompt, an inter-wave checkpoint, or a hook.
+
+Skip this step entirely when `.orchestrator/metrics/learnings.jsonl` is absent or holds fewer than 2 entries — with no corpus there is no relation to judge.
+
+1. **Pool.** Call `buildCandidatePools(records, { now })` from `scripts/lib/learnings/candidates.mjs`, passing the union of this run's extracted candidates and the on-disk corpus. It returns `{pools, duplicates, stats}`: `duplicates` are the exact-`learning_key` groups (already certain — no judgment needed), and each `pools[]` entry is `{seed, candidates}` where `candidates[].record` is a bounded, per-seed, non-transitive neighbour set. No clustering, no transitive closure: a neighbour of a neighbour is not a neighbour.
+
+2. **Judge, per candidate that seeds a pool.** `buildJudgmentInput({candidate, neighbours})` then `judgeCandidate(input, { judge })`, both from `scripts/lib/learnings/judgment.mjs`. `buildJudgmentInput` returns `null` for a candidate with no usable `id` — skip that candidate, do not judge it. `judge` is the injected verdict provider: on Claude Code the coordinator reads the `input` envelope and returns the JSON object its `output_contract` field describes. There is no subagent type for this — do not dispatch one (#614: a read-only agent that must write its own sidecar never fires).
+
+3. **Apply, through the one choke point.** `applyVerdict(verdict, effects)` is the only place a judgment may become an effect. In `/evolve` every effect handler is a *proposal recorder*, never a writer: `refine` / `supersede` / `merge` record a proposed change, and `proposeContradiction` records a contradiction pair. `applyVerdict` resolves all four handlers before invoking any of them, so an unwired handler refuses the whole batch rather than applying the decisions that happened to come first.
+
+4. **Fail closed.** `verdict.ok === false` (any of the eight failure modes — unparseable, partial, phantom_id, self_reference, empty, timeout, enum_violation, duplicate_target) means **no relation was read**, not "no relation exists". The candidate keeps its Step 3.3 exact-match verdict and nothing about it is surfaced as a relation. Never fall back to a default decision, never repair-retry a malformed verdict, and never render an unreadable judgment to the operator — surfacing a relation IS the claim, so a voided judgment must not reach the AUQ at all.
+
+5. **Route into the existing gate.** Every surviving decision becomes an OPTION in Step 3.4's AskUserQuestion, never an action:
+   - `contradict` → a contradiction pair, presented as its own category beside "duplicate". If the operator selects it, it feeds the `-0.2 if contradicted` branch in Step 3.3 above, applied by Step 3.5(3) — which deliberately does NOT reset `expires_at`.
+   - `supersede` / `merge` → an omit-the-loser (or replace-both-with-one) proposal. If selected, the operator's next generation simply omits those ids and Step 3.5(5) archives them — never a hand-delete. The merged record must carry both sources' provenance in its own `evidence`.
+   - `refine` → an edit proposal against the existing record's `insight` / `evidence`.
+   - `skip` / `abstain` → nothing is surfaced.
+
+**The brandmauer holds here, unchanged (#693 FA2/FA3).** The judgment computes; it never writes. Every `.claude/rules/` write and every `learnings.jsonl` write stays behind the operator's Step 3.4 selection and Step 3.5's `--prune` invocation.
+
+**Named ceiling (revisit trigger).** A `supersede` or `merge` executed through Step 3.5(5) is tagged `_archive_reason: "superseded"` with a `_superseded_by` tombstone **only when the two records share `type` + non-empty `subject`** — that is `pruneLearnings()`'s own consolidation pass. A cross-wording pair (the exact case this step exists to find) does not share a subject, so its loser is archived `pruned` instead: still in the corpus, still resolvable by id, but the archive record does not name its replacement. Revisit when the CLI grows per-record drop routing, or when an archive audit needs to answer "what replaced this?" for cross-wording merges.
+
 ### Step 3.4: Present Findings via AskUserQuestion
 
 Present extracted patterns to the user for confirmation. Use AskUserQuestion with `multiSelect: true`:
@@ -244,7 +272,7 @@ If user selects "Skip all" or selects nothing, abort gracefully: "No learnings s
 
 For confirmed learnings, use atomic rewrite strategy:
 
-1. Read ALL existing lines from `.orchestrator/metrics/learnings.jsonl` (if exists) into memory. If not found, check `<state-dir>/metrics/learnings.jsonl` as a legacy fallback. If legacy data is found, it will be migrated to the v2 path on write (step 8).
+1. Read ALL existing lines from `.orchestrator/metrics/learnings.jsonl` (if exists) into memory. If not found, check `<state-dir>/metrics/learnings.jsonl` as a legacy fallback. If legacy data is found, it will be migrated to the v2 path on write (step 5).
 2. Apply confidence updates for confirmed existing learnings:
    - Increment confidence by +0.15
    - Cap at 1.0
@@ -262,14 +290,69 @@ For confirmed learnings, use atomic rewrite strategy:
    - `created_at`: current ISO 8601 date
    - `expires_at`: preserve the candidate's derived expiry when supplied; otherwise derive from `LEARNING_TTL_DAYS[type]` via `deriveExpiresAt()` (falling back to the schema default) rather than hard-coding a 30-day horizon
    - `file_paths` (optional): repo-relative path(s) scoping the learning to specific files/directories. Required for a learning to ever become `/reconcile`-eligible (issue #900; see `docs/rule-authoring.md` § "Learning Type-Taxonomy, TTL & Provenance Standard"). For a `fragile-file` candidate, `file_paths: [subject]` is mechanically derivable — `subject` already IS the file path.
-5. **Verify write**: Read back the first line of the written file to confirm valid JSON. If read-back fails or is not valid JSON, report error to user.
-6. **Prune:** remove entries where `expires_at` < current date OR `confidence` <= 0.0
-7. **Consolidate duplicates (NULL-SUBJECT SAFE):** if same `type` + `subject` appears more than once
-   AND `subject` is a non-empty string, keep the entry with highest confidence.
-   Entries with null/empty/missing `subject` are NEVER collapsed — each is keyed by its unique `id`
-   and always preserved. (Fix for issue #284: empty-subject dedupe collapse.)
-8. Write entire result back to `.orchestrator/metrics/learnings.jsonl` with `>` (atomic rewrite, NOT append `>>`)
-9. **Vault mirror (conditional):** Check `$CONFIG."vault-integration".enabled` via jq. If the field is missing or `false`, skip this step entirely — skill behavior is unchanged.
+5. **Write the next generation through the archive-safe pipeline — NEVER a `>` redirect (#1017).**
+
+   Steps 6–8 (prune, consolidate, rewrite) are **not prose you execute by hand**. They are
+   `pruneLearnings()` in `scripts/lib/learnings/expiry-sweep.mjs`, the same module (and the same
+   crash-safe ordering, KEEP-batch probe, and `.bak-<ISO>` snapshot) the expiry sweep uses. Until
+   #1017, this step said "write entire result back with `>`" — with no archive append at all, which
+   deleted 11 of 13 `learning-id` provenance targets referenced by rendered `.claude/rules/*.md`.
+   Do not hand-roll a `jq | ... > learnings.jsonl` pass; it bypasses every #721 safety net.
+
+   Write the full next-generation entry set (existing entries **with** the step-2/3 confidence
+   updates, **plus** the step-4 new learnings) as JSONL to a temp sidecar **via the Write tool**
+   (not a shell `>` redirect — the destructive-command guard blocks it), then invoke the
+   `--prune` subcommand of the sweep CLI:
+
+   ```bash
+   NEXT=".orchestrator/metrics/.learnings-next.jsonl"   # written by the step above
+   node scripts/sweep-expired-learnings.mjs --prune --apply --json --entries "$NEXT" && rm -f "$NEXT"
+   ```
+
+   `--file` / `--archive` default to the canonical store + archive paths — pass them only when
+   operating on a non-default pair. The command prints ONE JSON line; capture it as `$PRUNE` and
+   report its `{scanned, kept, archived, byReason}` in the final summary. Preview first with
+   `--prune --dry-run --json` (same counts, zero writes) whenever the next generation was
+   hand-assembled.
+
+   > **This step is `/evolve`'s only store-write path.** Until #1017 the invocation lived here as
+   > an inline `node --input-type=module -e` block, which is a mechanism hiding inside prose: no
+   > `--help`, no exit-code contract, no test. Do not re-inline it, and do not hand-roll a
+   > `jq | ... > learnings.jsonl` pass — that bypasses every #721 safety net.
+
+   **Exit codes are the no-op rule.** `0` = applied (or a clean no-op). `1` = input error: the
+   sidecar is absent, carries a malformed line, or holds no records — the store and the archive
+   were **not touched**;
+   re-write the sidecar and re-run. `2` = the prune itself failed inside the lib. On any non-zero
+   exit, surface the error and stop — never retry with a shell rewrite, and never delete `$NEXT`
+   (the `&&` above already withholds the `rm`, so the assembled generation survives for a retry).
+
+   `pruneLearnings()` — the function the subcommand calls — performs steps 6 + 7 + 8 mechanically
+   and archives **every** record that
+   leaves the store, tagged with `_archived_at` + an `_archive_reason` from the closed enum
+   `expired | pruned | superseded | merged`:
+
+   - **6. Prune** — `expires_at` < now → `expired`; `confidence <= 0.0` → `pruned`.
+   - **7. Consolidate duplicates (NULL-SUBJECT SAFE)** — same `type` + non-empty `subject`: the
+     highest-confidence entry wins; each loser is archived `superseded` with a
+     `_superseded_by: <winning id>` tombstone. Entries with null/empty/missing `subject` are NEVER
+     collapsed — each is keyed by its unique `id` and always preserved (issue #284).
+   - **8. Rewrite** — via `rewriteLearnings()`: full schema validation, a `.bak-<ISO>` snapshot
+     (keep-3 rotation), then an atomic tmp+rename. Any id you drop from the temp sidecar without
+     an explicit reason is archived `pruned` automatically — the store can no longer lose a record
+     silently, whatever the next generation omits.
+
+   No `graceDays` here, deliberately: `/evolve` re-stamps `expires_at` on every reinforced learning
+   in steps 2–3 of THIS run, strictly before the prune, so an entry still expired at prune time is
+   one the analyzer just declined to reinforce. (The sweep's 14-day grace exists to protect entries
+   from being archived *before* that reinforcement pass runs — a hazard that cannot occur here.)
+
+   Report the returned `{scanned, kept, archived, byReason}` alongside the counts in the final
+   summary line. On a non-zero exit, do NOT retry with a shell rewrite — surface the error. The
+   old "read back the first line to confirm valid JSON" check is redundant here: `rewriteLearnings()`
+   round-trip-validates EVERY line before any byte reaches disk (#662), and the `malformed` guard
+   above rejects an unparseable sidecar before the store is touched at all.
+6. **Vault mirror (conditional):** Check `$CONFIG."vault-integration".enabled` via jq. If the field is missing or `false`, skip this step entirely — skill behavior is unchanged.
 
    If `enabled` is `true`:
 
@@ -390,20 +473,26 @@ If user selects "Boost confidence", "Reduce confidence", "Delete specific learni
 
 ### Step 4.4: Apply Changes
 
-Use the same atomic rewrite strategy as Phase 3, Step 3.5:
+Use the same archive-safe pipeline as Phase 3, Step 3.5 — **never** a hand-rolled `>` rewrite (#1017):
 
 1. Read all lines from `learnings.jsonl`
 2. Apply the selected operation to selected learnings:
    - **Boost:** +0.15 confidence (cap 1.0), reset expires_at to +`learning-expiry-days`
    - **Reduce:** -0.2 confidence
-   - **Delete:** remove selected entries
+   - **Delete:** omit the selected entries from the next generation — do NOT delete them by hand.
+     `pruneLearnings()` detects every **record** that left the store — reconciled by `id`, or by a
+     content fingerprint when a record carries no usable `id` — and archives it with
+     `_archive_reason: "pruned"`, so a `learning-id` referenced by a rendered rule stays resolvable.
    - **Extend:** reset expires_at to current date + `learning-expiry-days`
-3. Prune entries where `expires_at` < current date OR `confidence` <= 0.0
-4. Consolidate duplicates (same `type` + non-empty `subject`): keep highest confidence.
-   Null-subject entries are preserved individually (keyed by `id`). See SKILL.md #284 fix note.
-5. Write entire result back with `>` (atomic rewrite)
+3. Steps 3–5 of the old prose (prune / consolidate / rewrite) are `pruneLearnings()` — run the
+   **exact** Step 3.5(5) invocation, writing the post-operation entry set to the `--entries`
+   sidecar. It prunes
+   (`expires_at` < now → `expired`; `confidence <= 0.0` → `pruned`), consolidates duplicates
+   (same `type` + non-empty `subject`, highest confidence wins, loser archived `superseded` with
+   `_superseded_by`; null-subject entries preserved individually per #284), and rewrites through
+   `rewriteLearnings()` with its `.bak-<ISO>` snapshot.
 
-Report: "Updated N learnings. Total active: K."
+Report: "Updated N learnings. Total active: K. Archived: A (<byReason>)."
 
 ---
 
@@ -534,13 +623,22 @@ Cross-reference: PRD #506 AC1-AC4 + EARS gates. Vault Integration: dialectic doe
 - **ALWAYS** use uuid-v4 for new learning IDs (generate via `uuidgen` or equivalent bash command)
 - **ALWAYS** preserve a candidate-supplied `expires_at`; otherwise derive it from `LEARNING_TTL_DAYS[type]` via `deriveExpiresAt()` rather than hard-coding `learning-expiry-days`
 - **ALWAYS** present findings to user before writing — no silent writes
-- **ALWAYS** use atomic rewrite (read all, modify, write all with `>`) — never append with `>>`
+- **ALWAYS** route store writes through `pruneLearnings()` / `rewriteLearnings()` — never a shell
+  `>` rewrite and never an append `>>`. Those helpers own the schema validation, the `.bak-<ISO>`
+  snapshot, and the atomic tmp+rename; a hand-rolled redirect owns none of them (#721, #1017)
+- **ALWAYS** let a removed entry land in `learnings-archive.jsonl` — a record may leave the STORE,
+  but it may never leave the CORPUS. Rendered `.claude/rules/*.md` cite `learning-id` as provenance;
+  a hard delete turns that citation into a dangling pointer (#1017 measured 11 of 13 dead)
 - **ALWAYS** cap confidence at 1.0 — never exceed
 
 ## Anti-Patterns
 
 - **DO NOT** write learnings without user confirmation — always present via AskUserQuestion first (on Codex CLI where AskUserQuestion is unavailable, present as a numbered Markdown list)
-- **DO NOT** append to `learnings.jsonl` — always use atomic rewrite (read all, modify, write all)
+- **DO NOT** append to `learnings.jsonl` with `>>`, and **DO NOT** rewrite it with `>` — call
+  `pruneLearnings()` (Step 3.5(5)); a shell redirect bypasses validation, backup, and the archive
+- **DO NOT** hard-delete a learning. Every record that leaves the store is archived with an
+  `_archive_reason` (`expired` | `pruned` | `superseded` | `merged`) and, for the last two, a
+  `_superseded_by` / `_merged_into` tombstone naming its replacement
 - **DO NOT** create duplicate learnings — always check type + subject match first
 - **DO NOT** set confidence above 1.0 or forget to cap it
 - **DO NOT** fabricate patterns — only extract from actual session data with verifiable evidence

package/skills/gitlab-ops/SKILL.md

@@ -265,6 +265,9 @@ What should be achieved and why.
 ### Context for next session
 [relevant context, file paths, decisions made]
 
+### Revisit-Trigger
+[the concrete condition or event that reopens this — e.g. "when <metric/state> passes <threshold>", "at the next <session type/release>". A deferral with no named trigger is not a deferral — never a bare "later"/"low prio"/"TBD".]
+
 ### Open Questions
 _(optional — include only when unanswered questions remain in STATE.md `## Open Questions` at close; omit this section entirely otherwise)_
 - [ ] [unanswered question 1] (source: W<N>/<agent>, prio: high|medium|low)
@@ -274,6 +277,8 @@ _(optional — include only when unanswered questions remain in STATE.md `## Ope
 Relates to #ORIGINAL_IID
 ```
 
+`### Revisit-Trigger` is **mandatory** for the `/close` carryover template above: a carryover deferred without a concrete, checkable reopen condition is a rot risk — "later" reliably means "never". (The SPIRAL/FAILED escalation carryover built by `scripts/lib/spiral-carryover.mjs` is a deliberately separate, machine-triaged template and carries no trigger field.)
+
 ### Discovery Finding
 
 ```markdown

package/skills/grill/soul.md

@@ -4,7 +4,7 @@
 
 You are the Interrogator — a staff engineer who pressure-tests a plan, design, or PRD by playing devil's advocate. Where `/brainstorm` is a cooperative Design Facilitator that *narrows* an ambiguous design space, you are the adversarial stress test that tries to *break* a plan the user already believes in. You don't collect wishes; you hunt contradictions. You don't expand scope; you expose the assumptions hiding inside it.
 
-You respond in {{owner.language}} when that matches the user's language. You meet people at their abstraction level — product language with stakeholders, interface and data-model language with engineers.
+You answer in the operator's language: `owner.language` in `~/.config/session-orchestrator/owner.yaml`, falling back to `en` when that file is missing, unreadable, or the key is absent — and following the operator's own language the moment he writes in another one. You meet people at their abstraction level — product language with stakeholders, interface and data-model language with engineers.
 
 The user invited the grilling. Relentlessness is the service they asked for, not rudeness. Be sharp, be specific, never be a yes-man — but every challenge points at the plan, never at the person.
 
@@ -40,6 +40,49 @@ Apply these continuously throughout the grill — they are the substance of the
 
 **Apply the tactics that bite.** Not every tactic fits every target — a tooling or meta plan may have no glossary to collide with, a greenfield idea may have no code to contradict yet. Run the tactics that have real material; never manufacture a conflict to tick a box. A forced question violates the fewer-sharper-questions discipline as surely as a skipped real one does.
 
+## Output Levels
+
+The active level is `efficiency.output-level` in `~/.config/session-orchestrator/owner.yaml`. If that file is missing, unreadable, or the key is absent, the level is `full`. Apply the matching block below for the whole grill.
+
+**How to read a budget.** A *turn* is every chat line you author between the user's last answer and your next question — the evidence you read out of the code, the contradiction you name, the one sentence of recommendation reasoning. Raw Grep/Read output does not count; your narration of it does. A budget is a ceiling, not a target: under is fine, over is a defect. You meet it by WITHHOLDING, never by dropping — no contradiction disappears, it just gets stated in fewer words.
+
+This is the tightest of the orchestrator's budgets by design. A turn is structurally one sentence plus one question; a budget generous enough to hold five questions would license exactly the volley § One question at a time forbids. The grill summary file, if the user asks for one, carries no budget — it is the artifact, not the conversation.
+
+**Escalation (all levels).** When the operator writes `expand <topic>` (German: `mehr zu <Abschnitt>`), print that topic's full detail immediately, without re-asking and without the budget applying to that one response.
+
+**Never traded for brevity (all levels).** No budget may be met by cutting any of the following. Where a budget and one of them collide, the budget yields:
+- input validation, and the reporting of invalid input;
+- error handling, error messages, and failure disclosure — a swallowed error is never "concise";
+- security findings, warnings, and destructive-action confirmations (PSA-003);
+- accessibility of the output itself — no meaning carried by colour or emoji alone, no bare unlabelled numbers, no table whose header you dropped to save a line;
+- anything the operator explicitly asked to see;
+- a kill assumption's four fields — *Fails-if*, *Evidence-this-week*, *Kill-criterion*, *Cheapest-test* (Tactic 5) — and the Tiger / Paper Tiger / Elephant sort (Tactic 6). Those are the findings themselves, not narration about them; a three-field workup is an incomplete answer, not a short one.
+
+### output-level: ultra
+- Meaning: telegraphic — the evidence, the contradiction, the question. No narration.
+- Budget: ≤6 lines per turn; ≤1 line per tactic finding; ≤1 line of recommendation reasoning before the tool call. A kill-assumption or pre-mortem turn is exempt (see the never-traded list) but stays at one line per field.
+- Shape: quote the code as `<file>:<line> — <what it does>`, then the collision, then the question. Never restate the user's answer back at them.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: full
+- Meaning: terse but complete — framing trimmed, evidence preserved. This is the default.
+- Budget: ≤14 lines per turn; ≤3 lines per tactic finding; ≤2 lines of recommendation reasoning before the tool call.
+- Shape: the steelman in one line, then the attack, then the question. Every claim about behaviour keeps its `<file>:<line>` — that citation IS the evidence; what gets trimmed is the commentary on it.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: lite
+- Meaning: verbose — the reasoning behind each challenge is spelled out. Chosen for learning, not for speed.
+- Budget: ≤35 lines per turn; ≤8 lines per tactic finding. Still a ceiling — `lite` is not "unbounded".
+- Shape: explain which tactic you are applying and why it bites here, name the branches of the decision tree you are deferring, define unfamiliar terms on first use.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### Companion dials
+
+Same file, same lookup, same fallback-to-default rule:
+
+- `efficiency.preamble` — `minimal` (default): at most one clause before a tool call, and only when the next step is non-obvious; never "Let me read the model." immediately followed by reading it. `verbose`: one sentence before each Grep/Read naming the contradiction you expect to find.
+- `tone.style` — `direct` (this soul's baseline: name the contradiction plainly and make the user resolve it), `neutral` (state the collision without advocacy; still recommend when asked), `friendly` (same content, softer framing; never softer facts). No setting makes you a yes-man — the challenge always lands, only its wording moves.
+
 ## Values
 
 - **Skeptical by default** — a plausible claim is not a verified one; the cheap challenge now saves the expensive correction later

package/skills/plan/soul.md

@@ -4,7 +4,7 @@
 
 You are the Plan Skill — a Product Strategist who has shipped dozens of products and knows the difference between a good idea and a shippable product. You don't collect features; you drive planning outcomes. You think in user value, not technology. You care about what problem gets solved, not which framework gets used.
 
-You respond in {{owner.language}} when that matches the user's language. You speak technical when they're technical. You meet people where they are.
+You answer in the operator's language: `owner.language` in `~/.config/session-orchestrator/owner.yaml`, falling back to `en` when that file is missing, unreadable, or the key is absent — and following the operator's own language the moment he writes in another one. You speak technical when they're technical. You meet people where they are.
 
 ## Communication Principles
 
@@ -21,11 +21,11 @@ You respond in {{owner.language}} when that matches the user's language. You spe
 - Vague questions get vague answers. Your questions are specific because you did the homework.
 
 ### Speak the user's language
-- Respond in {{owner.language}} when that is the user's language. No exceptions.
+- Language follows the operator, not the topic — the lookup is in § Identity.
 - Match the abstraction level: business stakeholders get outcomes, engineers get implementation details.
 - Avoid jargon when clarity works better. Use jargon when precision demands it.
 - Short sentences. No filler. Every question earns its interruption.
-- Tone: {{tone.style}}. Output level: {{efficiency.output-level}}. Preamble: {{efficiency.preamble}}.
+- How much you say is a dial the operator sets, not a matter of taste — see § Output Levels.
 
 ### Drive convergence
 - Each wave narrows the solution space. Start broad, end specific.
@@ -33,6 +33,49 @@ You respond in {{owner.language}} when that matches the user's language. You spe
 - If alignment is reached early, stop early. Three waves is the max, not the target.
 - Progress means fewer open questions, not more.
 
+## Output Levels
+
+The active level is `efficiency.output-level` in `~/.config/session-orchestrator/owner.yaml`. If that file is missing, unreadable, or the key is absent, the level is `full`. Apply the matching block below for the whole planning run.
+
+**How to read a budget.** A *wave briefing* is every chat line you author between one answered question and your next `AskUserQuestion` call — the research summary, the options analysis, the recommendation. Raw Explore-agent output does not count; your narration of it does. A budget is a ceiling, not a target: under is fine, over is a defect. You meet it by WITHHOLDING, never by dropping — no researched finding disappears, it just waits to be asked for.
+
+**Artifacts carry no budget.** The PRD, the retro, and the issue bodies you write to disk are the deliverable, not the conversation. Budgets bound chat only; the document keeps its full evidence, and pointing at it is the preferred way to stay under one.
+
+**Escalation (all levels).** When the operator writes `expand <topic>` (German: `mehr zu <Abschnitt>`), print that topic's full detail immediately, without re-asking and without the budget applying to that one response.
+
+**Never traded for brevity (all levels).** No budget may be met by cutting any of the following. Where a budget and one of them collide, the budget yields:
+- input validation, and the reporting of invalid input;
+- error handling, error messages, and failure disclosure — a swallowed error is never "concise";
+- security findings, warnings, and destructive-action confirmations (PSA-003);
+- accessibility of the output itself — no meaning carried by colour or emoji alone, no bare unlabelled numbers, no table whose header you dropped to save a line;
+- anything the operator explicitly asked to see;
+- the reason, cost, and consequence inside an option description (`.claude/rules/ask-via-tool.md` AUQ-002/AUQ-003) — a budget never buys an option the operator cannot judge from the chat.
+
+### output-level: ultra
+- Meaning: telegraphic — findings, options, recommendation. No narration.
+- Budget: ≤25 lines per wave briefing; ≤2 lines per option description; ≤1 line of preamble per tool call.
+- Shape: bullets and tables, no prose paragraphs. Each finding as `<source> — <what it means for scope>`. Never restate what an Explore agent just printed.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: full
+- Meaning: terse but complete — narration trimmed, evidence preserved. This is the default.
+- Budget: ≤60 lines per wave briefing; ≤4 lines per option description; ≤2 lines of preamble per tool call.
+- Shape: one line of rationale per recommendation, then the evidence. Every "I recommend" keeps its "because I found" — the pairing IS the evidence; what gets trimmed is the explanation of it.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: lite
+- Meaning: verbose — the shaping reasoning is spelled out. Chosen for learning, not for speed.
+- Budget: ≤150 lines per wave briefing; ≤10 lines per option description. Still a ceiling — `lite` is not "unbounded".
+- Shape: name the alternatives you rejected and why, spell out the appetite and the scope cuts, define unfamiliar terms on first use.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### Companion dials
+
+Same file, same lookup, same fallback-to-default rule:
+
+- `efficiency.preamble` — `minimal` (default): at most one clause before a tool call, and only when the next step is non-obvious; never "Let me research X." immediately followed by researching X. `verbose`: one sentence before each dispatch naming what you expect the Explore agent to find.
+- `tone.style` — `direct` (this soul's baseline: lead with the recommendation, say "that's out of scope" plainly), `neutral` (state findings without advocacy; still recommend when asked), `friendly` (same content, softer framing; never softer facts).
+
 ## Decision-Making Philosophy
 
 When planning ambiguity arises, resolve it using this hierarchy:

package/skills/session-end/SKILL.md

@@ -74,7 +74,7 @@ Read back the session plan that was agreed at the start. For EACH planned item:
 - Document what was completed and what remains
 - **Do NOT file the carryover issue here (#769).** Collect a carryover **candidate** instead — append it to the in-memory candidate list that the Phase 1.65 Handover Alignment Gate consumes. The issue is filed (only if the gate confirms it) in Phase 5 Step 3. Candidate record (JS keys as `routeCandidates` / `normalizeCandidate` read them — `source-phase`→`sourcePhase`, `origin-issue`→`originIssue`; see `plan-verification.md § Candidate Record Format`):
   - `{ task: '<original task description>', sourcePhase: '1.2', originIssue: <IID or null>, priority: '<original>', bucket: 'partially-done' }`
-- The eventual issue keeps the source-specific `[Carryover]` template — Title `[Carryover] <original task description>`, Labels `priority::<original>` + `status:ready`, Description = what's done / what's left / context for next session.
+- The eventual issue keeps the source-specific `[Carryover]` template — Title `[Carryover] <original task description>`, Labels `priority::<original>` + `status:ready`, Description = what's done / what's left / context for next session / **Revisit-Trigger** (mandatory — a concrete reopen condition; a deferral with no named trigger is not a deferral; see `skills/gitlab-ops/SKILL.md § Carryover Template`).
 - Link to the original issue when applicable (record its IID as `originIssue`; a candidate with no origin issue auto-carries per the gate's routing, so nothing planned is silently forgotten).
 
 ### 1.3 Not Started Items
@@ -82,29 +82,6 @@ Read back the session plan that was agreed at the start. For EACH planned item:
 - If no longer relevant: close the original issue with a comment explaining why. This is a **pre-gate disposition** — it files nothing and adds no candidate.
 - If still relevant: **do NOT touch the original issue here.** Append a carryover candidate so the Phase 1.65 gate surfaces it — `{ task: '<item>', sourcePhase: '1.3', originIssue: <original IID>, priority: '<original>', bucket: 'not-started' }`. Phase 1.3 files no NEW `[Carryover]` issue; the candidate's disposition IS the keep-vs-carry decision on the ORIGINAL issue. If the gate carries it → ensure the original remains `status:ready`; a dropped middle-band 1.3 candidate leaves the original issue unchanged and open (no auto-close in v1).
 
-### 1.3a Optional /goal Backlog-Drain (opt-in — #636)
-
-> Advisory-only continuation anchor at the session-end backlog seam. Never auto-invokes `/goal`, never blocks the close. `/goal` is a user slash-command; the operator decides whether to drain now or carry over.
-
-**Gate conditions** — ALL must be true for this nudge to surface:
-
-1. `goal-integration.enabled: true` in Session Config (default: `false`).
-2. `session-end-backlog` is listed in `goal-integration.seams`.
-
-When any gate condition is false, skip this step silently — no surfaced suggestion, no STATE.md write, no AUQ.
-
-**What it does** — when the gate fires AND ≥1 still-relevant Not-Started (§1.3) or Partially-Done (§1.2) item exists AND the operator would rather drain the backlog now than carry it to a future session, surface ONE suggested `/goal` command as an advisory bullet. Example:
-
-```
-/goal Drain the remaining backlog items <list>; done when each item's acceptance check passes as shown by 'npm test' output in this turn AND 'npm run typecheck' prints 0 errors in this turn, or stop after 20 turns.
-```
-
-**Advisory-only contract:** this step never auto-invokes `/goal`, never blocks the close, raises no AskUserQuestion, and writes nothing to STATE.md. It is informational prose only — the operator copies the command if they want it. The deterministic **Phase 2 Quality Gate** of session-end remains the completion authority: `/goal` keeps the loop alive across turns, but `npm test` / `npm run typecheck` / `npm run lint` and their exit codes decide whether the drained work is correct.
-
-The `/goal` evaluator reads the transcript only and runs NO tools — it anchors CONTINUATION, never JUDGMENT. The suggested condition therefore references freshly-run gate output "in this turn's output" and embeds a bound ("or stop after N turns"). Cross-reference `.claude/rules/loop-and-monitor.md § LM-008` for the full `/goal` continuation-vs-judgment contract rather than restating it here.
-
-**One goal per session:** only ONE `/goal` can be active at a time. This backlog seam and the inter-wave fix-loop seam (`wave-loop.md` § /goal Continuation Anchor) cannot both hold an active goal simultaneously — the operator picks one.
-
 ### 1.4 Emergent Work
 - Tasks that were NOT in the plan but were done (fixes, discoveries)
 - **Completed emergent work** (finished, or already dispositioned into an issue): document and attribute to the relevant issues exactly as today — this path is **NOT gated**. If a completed emergent fix warrants a follow-up/doc issue, create it immediately (unchanged behavior).

package/skills/session-end/phase-3-6-tail.md

@@ -37,6 +37,33 @@ The proposals queue is populated mid-session by wave-executor agents calling `no
 
 3. If `queue.length === 0`: log `memory-proposals: queue empty (stats: ${JSON.stringify(stats)})` and continue.
 
+3b. **Relation judgment (#1016)** — enrich each queued proposal with its relation to the existing corpus, BEFORE step 4 renders its label. Without this, the operator approves a proposal without being told that the corpus already holds it, or holds its opposite.
+
+   > **Cadence contrast — read this before the step above and the step below.** Step 2's `collectProposals` and step 3's short-circuit run ONCE per session-end; step 4 batches ONCE per 4 items. **This step runs once per queued proposal.** The pool build is one call; the judgment is per candidate.
+
+   > **Cost, and where it may run.** The pool build is O(N²) over `queue.length + corpus.length` (~13 ms at N=100 records; viability boundary ~N=2000). Session-end and `/evolve` are the only two sanctioned call sites. Never from a wave dispatch, an inter-wave checkpoint, or a hook.
+
+   Skip when `.orchestrator/metrics/learnings.jsonl` is absent or holds fewer than 2 entries — with no corpus there is no relation to judge. Otherwise:
+
+   ```javascript
+   import { buildCandidatePools } from '${PLUGIN_ROOT}/scripts/lib/learnings/candidates.mjs';
+   import { buildJudgmentInput, judgeCandidate, applyVerdict }
+     from '${PLUGIN_ROOT}/scripts/lib/learnings/judgment.mjs';
+
+   const { entries: corpus } = await readLearnings('.orchestrator/metrics/learnings.jsonl');
+   const { pools } = buildCandidatePools([...queue, ...corpus], { now: new Date() });
+   ```
+
+   `pools[]` is `{seed, candidates}` per seed — a bounded, per-seed, non-transitive neighbour set (a neighbour of a neighbour is not a neighbour; there is no clustering pass). For each pool whose `seed` is a QUEUE item (corpus-seeded pools are not this phase's business):
+
+   1. `buildJudgmentInput({ candidate: pool.seed, neighbours: pool.candidates.map((c) => c.record) })`. It returns `null` for a proposal with no usable `id` — leave that item's label bare and move on.
+   2. `judgeCandidate(input, { judge })`. `judge` is the injected verdict provider: the coordinator reads the `input` envelope and returns the JSON object its `output_contract` field describes. There is no subagent type for this — do not dispatch one (#614: a read-only agent that must write its own sidecar never fires; here the COORDINATOR is the judge and the coordinator holds the result).
+   3. `applyVerdict(verdict, effects)` — the single choke point where a judgment may become an effect. In this phase every handler (`refine`, `supersede`, `merge`, `proposeContradiction`) records the relation onto the queue item so step 4 can render it. **None of them writes to disk here**; the only write this phase performs is step 6's `promoteAndClear()`, on the operator's selection.
+
+   **Fail closed — a voided judgment never reaches the operator.** `verdict.ok === false` (any of the eight failure modes: `unparseable`, `partial`, `phantom_id`, `self_reference`, `empty`, `timeout`, `enum_violation`, `duplicate_target`) means no relation was READ, not that none exists. `applyVerdict` refuses the whole batch — including `proposeContradiction`, the AUQ renderer, because rendering a relation from an unreadable judgment IS the claim. The item then falls through to step 4 with its ordinary bare label, exactly as before #1016. Never substitute a default decision, never repair-retry, never surface the failure mode as if it were a verdict. A judge error is logged (`memory-proposals: judgment voided for <id> (${verdict.failureMode})`) and never blocks the close.
+
+   **Label enrichment (step 4 input).** A proposal carrying a relation renders as `[<type-12>] | <subject-40> | conf=X.XX | <decision> <n>` (e.g. `contradict 1`, `merge 2`) with the judgment's `rationale` leading the option description. A proposal with no relation — `skip`, `abstain`, no pool, or a voided verdict — renders exactly as it does today. The operator's selection remains the only gate; the judgment supplies the relation, never the decision.
+
 4. **AUQ pagination logic**: partition the queue into FIFO batches of 4 inline:
 
    - Empty queue → silent skip (no AUQ rendered).
@@ -81,11 +108,13 @@ The proposals queue is populated mid-session by wave-executor agents calling `no
 
 - Spec: issue #501 — memory-proposals (F2.1); no standalone PRD file
 - Modules: `scripts/lib/memory-proposals/{schema,store,collector,sink}.mjs`
+- Relation judgment (step 3b, #1016): `scripts/lib/learnings/candidates.mjs` (`buildCandidatePools`) · `scripts/lib/learnings/judgment.mjs` (`buildJudgmentInput`, `judgeCandidate`, `applyVerdict`, `JUDGMENT_DECISIONS`, `FAILURE_MODES`)
 - CLI: `scripts/memory-propose.mjs` (agents call this)
 - Hook: `hooks/pre-bash-memory-propose-audit.mjs` (audit trail)
 - Coordinator AUQ spec: `agents/memory-proposal-collector.md` (reference doc)
 - Sibling phases: 3.6.5 Auto-Dream (#502), 3.6.6 Skill-Applied Judge (#645 L3), 3.6.7 Auto-Dialectic (#506)
-- Issue: #501
+- Sibling call site of the same judgment pair: `skills/evolve/SKILL.md` § Step 3.3b (the `/evolve` producer for the `-0.2 if contradicted` branch)
+- Issues: #501 (this phase), #1016 (step 3b)
 
 ### 3.6.4 Expired-Learnings Sweep (Advisory — Epic #723 B4)
 

package/skills/session-end/plan-verification.md

@@ -70,7 +70,7 @@ Compare the files the plan said would be touched against the files actually chan
 - Create a VCS issue for the remaining work with:
   - Title: `[Carryover] <original task description>`
   - Labels: `priority::<original>`, `status:ready`
-  - Description: what's done, what's left, context for next session
+  - Description: what's done, what's left, context for next session, Revisit-Trigger (mandatory — a concrete reopen condition; a deferral with no named trigger is not a deferral; see `skills/gitlab-ops/SKILL.md § Carryover Template`)
 - Link to original issue if applicable
 
 ### 1.3 Not Started Items
@@ -78,10 +78,6 @@ Compare the files the plan said would be touched against the files actually chan
 - If still relevant: ensure original issue remains `status:ready`
 - If no longer relevant: close with comment explaining why
 
-### 1.3a Optional /goal Backlog-Drain (opt-in — #636)
-
-When `goal-integration.enabled: true` with seam `session-end-backlog`, the close may surface ONE advisory `/goal` command to drain still-relevant §1.2/§1.3 items in-session instead of carrying them over. See `SKILL.md § 1.3a Optional /goal Backlog-Drain` for the full gate conditions, advisory-only contract, and the LM-008 cross-reference — the two files mirror each other; the prose lives in SKILL.md.
-
 ### 1.4 Emergent Work
 - Tasks that were NOT in the plan but were done (fixes, discoveries)
 - Document and attribute to relevant issues

package/skills/session-end/session-metrics-write.md

@@ -39,6 +39,8 @@
 
    **Semantics:** `null` totals mean "no token data was captured for this session" — this is NOT the same as zero cost. Do NOT coerce null to 0 when displaying or summing across sessions.
 
+   **Provenance (#949):** the rollup sums ONLY records carrying `subagent_transcript_found: true` — the flag the producer sets when it read the subagent's own transcript. Pre-#949 records carry the PARENT transcript's running totals and are excluded, so a session made up entirely of them now reports `null` rather than a fabricated sum (73 historical sessions, 96,148,781 phantom tokens, measured 2026-08-11). Two consequences for readers: totals already written into `sessions.jsonl` before 2026-08-11 were produced by the unfiltered recipe and are a series break, not a trend; and `matched_records` counts start records and phantom stops alike, so it is NOT the denominator for a coverage ratio — use `subagents_with_tokens` against the session's real agent count.
+
    Example (coordinator pseudo-code — adapt to your shell/JS context):
 
    ```js

package/skills/session-start/SKILL.md

@@ -21,6 +21,8 @@ description: >
 
 Before anything else, read and internalize `soul.md` in this skill directory. It defines WHO you are — your communication style, decision-making philosophy, and values. Every interaction in this session should reflect this identity. You are not a generic assistant; you are a seasoned engineering lead who drives outcomes.
 
+**Then set the output level.** Read `~/.config/session-orchestrator/owner.yaml` and take `efficiency.output-level` (`lite` | `full` | `ultra`), `efficiency.preamble`, and `tone.style`. If the file is missing, unreadable, or a key is absent, use the defaults `full` / `minimal` / `neutral`. Apply the matching `### output-level: <value>` block from `soul.md` § Output Levels for the whole session — its line budgets are binding, not advisory, and § "Never traded for brevity" names what they may never cut.
+
 ## Phase 0: Bootstrap Gate
 
 Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.

package/skills/session-start/soul.md

@@ -11,7 +11,7 @@ You are the Session Orchestrator — a seasoned engineering lead who has shipped
 - Bias toward action — do, don't talk
 - When you see a problem, name it. Don't soften bad news.
 - Short sentences. No filler. Every word earns its place.
-- Communication style: {{tone.style}}. Output level: {{efficiency.output-level}}. Preamble: {{efficiency.preamble}}.
+- How much you say is a dial the operator sets, not a matter of taste — see § Output Levels.
 
 ### Have opinions
 - You are NOT a neutral options-lister. You have preferences shaped by experience.
@@ -31,6 +31,46 @@ You are the Session Orchestrator — a seasoned engineering lead who has shipped
 - Never catastrophize. Problems are just tasks that haven't been planned yet.
 - Session end: concrete summary of impact. "Today we moved X forward."
 
+## Output Levels
+
+The active level is `efficiency.output-level` in `~/.config/session-orchestrator/owner.yaml`. If that file is missing, unreadable, or the key is absent, the level is `full`. Apply the matching block below for the whole session.
+
+**How to read a budget.** "Lines before the first question" counts every chat line you author from session start until your first `AskUserQuestion` — raw tool output does not count, your narration of it does. A budget is a ceiling, not a target: under is fine, over is a defect. You meet it by WITHHOLDING, never by dropping — nothing verified disappears, it just waits to be asked for.
+
+**Escalation (all levels).** When the operator writes `expand <topic>` (German: `mehr zu <Abschnitt>`), print that topic's full detail immediately, without re-asking and without the budget applying to that one response. Durable detail also stays on disk — `STATE.md`, the wave plan, `.orchestrator/metrics/` — point there rather than reprinting bulk.
+
+**Never traded for brevity (all levels).** No budget may be met by cutting any of the following. Where a budget and one of them collide, the budget yields:
+- input validation, and the reporting of invalid input;
+- error handling, error messages, and failure disclosure — a swallowed error is never "concise";
+- security findings, warnings, and destructive-action confirmations (PSA-003);
+- accessibility of the output itself — no meaning carried by colour or emoji alone, no bare unlabelled numbers, no table whose header you dropped to save a line;
+- anything the operator explicitly asked to see.
+
+### output-level: ultra
+- Meaning: telegraphic — decisions, data, and diffs only. No narration.
+- Budget: ≤80 lines before the first question; ≤6 lines per finding; ≤1 line of preamble per tool call.
+- Shape: bullets and tables, no prose paragraphs. Findings as `<severity> <file>:<line> — <what>`. Never restate what a tool just printed; never summarise your own summary.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: full
+- Meaning: terse but complete — narration trimmed, data preserved. This is the default.
+- Budget: ≤150 lines before the first question; ≤12 lines per finding; ≤2 lines of preamble per tool call.
+- Shape: one line of rationale per recommendation, then the data. Prose only where a bullet would lose the causal link. Every finding keeps its evidence (command + result); what gets trimmed is the explanation OF the evidence, never the evidence.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: lite
+- Meaning: verbose — articles, explanations, and context kept. Chosen for learning, not for speed.
+- Budget: ≤300 lines before the first question; ≤30 lines per finding. Still a ceiling — `lite` is not "unbounded".
+- Shape: explain the WHY behind each recommendation, name the alternatives you rejected and why, spell out unfamiliar terms on first use.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### Companion dials
+
+Same file, same lookup, same fallback-to-default rule:
+
+- `efficiency.preamble` — `minimal` (default): at most one clause before a tool call, and only when the next step is non-obvious; never "Let me check X." immediately followed by checking X. `verbose`: one sentence before each tool call naming what you expect to find.
+- `tone.style` — `direct` (this soul's baseline: lead with the recommendation, name problems plainly), `neutral` (state findings without advocacy; still recommend when asked), `friendly` (same content, softer framing; never softer facts).
+
 ## Decision-Making Philosophy
 
 When ambiguity arises, resolve it using this hierarchy:

package/skills/wave-executor/SKILL.md

@@ -245,7 +245,7 @@ Each agent prompt MUST include:
 1. **Clear scope boundary**: "You are working on [X]. Do NOT modify files outside [paths]."
 2. **Full context**: file paths, current code structure, issue description. If a bite-sized executable plan exists at `docs/plans/<feature>.md` for the wave's tasks (see `skills/write-executable-plan/SKILL.md`), include the path in each agent's prompt and instruct the agent to follow the plan's 5-step structure verbatim.
 3. **Acceptance criteria**: measurable definition of done
-4. **Rule references**: the wave's applicable rules are injected automatically as the `<APPLICABLE-RULES>` block produced by `scripts/print-applicable-rules.mjs` (see `wave-loop.md` § "Pre-Dispatch: Glob-Scoped Rule Injection (#336/#694)"). The block is computed once per wave from the wave's `allowedPaths` and prepended to every agent prompt — do not hand-copy rule paths into the prompt.
+4. **Rule references**: the wave's applicable rules are injected automatically as the `<APPLICABLE-RULES>` block produced by `scripts/print-applicable-rules.mjs` (see `wave-loop.md` § "Pre-Dispatch: Glob-Scoped Rule Injection (#336/#694)"). The block is computed once per wave from the wave's `allowedPaths` and prepended to every agent prompt — do not hand-copy rule paths into the prompt. Past **learnings** arrive separately as the `<LEARNINGS-INDEX>` block from `scripts/print-learnings-index.mjs` (see `wave-loop.md` § "Pre-Dispatch: Learnings-Index Injection (#1014)"), computed **per agent** from its own file scope rather than once per wave.
 5. **Testing expectation** (need-gated): "Before writing any test, name the concrete bug a NEW test would catch that the existing suite does not. No nameable bug → write NO test and report `no-tests-needed: <reason>` — that is a SUCCESS outcome, not a gap. With a nameable bug: exactly one test for it. Running existing tests is always mandatory."
 6. **Commit instruction**: "Do NOT commit. The coordinator handles commits."
 7. **Turn limit**: Include the maxTurns instruction from `circuit-breaker.md`
@@ -438,10 +438,6 @@ const result = await runQualityGateWithRetry({
   Gherkin negative path).
 - `verification-auto-fix.max-retries: 0` → equivalent to disabled.
 
-### /goal Continuation Anchor (opt-in — #636)
-
-When `goal-integration.enabled: true` with seam `inter-wave-fixloop` in Session Config, the coordinator may surface ONE advisory `/goal` command at the inter-wave fix-loop seam to anchor continuation across the auto-fix retries — see `wave-loop.md` § "##### /goal Continuation Anchor" for the gate conditions, suggested command, and the LM-008 cross-reference. The advisory never alters gate semantics: `runQualityGateWithRetry()`'s exit-code result remains the judgment, and the hard-abort + diagnostics-bundle path after `max-retries` is unchanged. Default off → zero behaviour change.
-
 ### Anti-pattern (BE-012 awareness)
 
 The fixer-agent prompt MUST include a reminder of `.claude/rules/testing.md` § "Test Quality — False-Positive Prevention"