session-orchestrator 3.21.0 → 3.23.0

package/skills/brainstorm/SKILL.md

@@ -48,12 +48,12 @@ Run a single AUQ to let the user characterize the problem in their own words:
 ```
 AskUserQuestion({
   questions: [{
-    question: "Describe the feature or problem you want to brainstorm. What's the core pain point it addresses, and what's still ambiguous to you?",
-    header: "Feature Frame",
+    question: "What do you want to brainstorm, and what is still unclear about it?",
+    header: "Frame",
     options: [
-      { label: "UX / user-facing surface is unclear", description: "You know what you want to build but not how it should work for the user." },
-      { label: "Scope / boundaries are unclear", description: "You're not sure how much to build, or where one feature ends and another begins." },
-      { label: "Multiple approaches exist — need to pick one", description: "You see 2-3 ways to solve this and aren't sure which is best." },
+      { label: "The user-facing surface", description: "You know what to build but not how it should work for the user." },
+      { label: "Scope / boundaries", description: "You're not sure how much to build, or where one feature ends and another begins." },
+      { label: "Several approaches — pick one", description: "You see 2-3 ways to solve this and aren't sure which is best." },
       { label: "Other / describe below", description: "Free-form: describe the ambiguity in the next prompt." }
     ],
     multiSelect: false
@@ -98,9 +98,9 @@ Example round (adapt to the actual feature):
 AskUserQuestion({
   questions: [{
     question: "Who is the primary user of this feature, and how do they trigger it?",
-    header: "User Surface — Round 2",
+    header: "User surface",
     options: [
-      { label: "Authenticated user via UI action (Recommended)", description: "Pro: fits existing session model. Con: requires UI component work." },
+      { label: "Signed-in user, UI action (Recommended)", description: "Pro: fits existing session model. Con: requires UI component work." },
       { label: "Automated trigger (webhook, cron, event)", description: "Pro: no manual user step. Con: harder to debug and test." },
       { label: "Admin-only operation", description: "Pro: simpler access control. Con: limits who can self-serve." },
       { label: "Other / describe below", description: "Describe the trigger mechanism." }
@@ -128,12 +128,12 @@ Once the dialogue has enough signal, synthesize 2-3 concrete implementation appr
 ```
 AskUserQuestion({
   questions: [{
-    question: "Based on your answers, here are the viable approaches. Which fits best?",
-    header: "Design Approach",
+    question: "Which of these approaches fits best?",
+    header: "Approach",
     options: [
-      { label: "Approach A — [1-sentence summary] (Recommended)", description: "Trade-offs: [key pro]. [key con]. Complexity: low/medium/high." },
-      { label: "Approach B — [1-sentence summary]", description: "Trade-offs: [key pro]. [key con]. Complexity: low/medium/high." },
-      { label: "Approach C — [1-sentence summary]", description: "Trade-offs: [key pro]. [key con]. Complexity: low/medium/high." }
+      { label: "A — [short summary] (Recommended)", description: "Best balance of value, reversibility and scope, because [key pro]. Cost: [key con]. Complexity: low/medium/high." },
+      { label: "B — [short summary]", description: "Trade-offs: [key pro]. Cost: [key con]. Complexity: low/medium/high." },
+      { label: "C — [short summary]", description: "Trade-offs: [key pro]. Cost: [key con]. Complexity: low/medium/high." }
     ],
     multiSelect: false
   }]
@@ -231,13 +231,13 @@ Present the spec path and summary to the user. Then ask via AUQ:
 ```
 AskUserQuestion({
   questions: [{
-    question: "The design spec has been written to docs/specs/YYYY-MM-DD-<slug>-design.md. How do you want to proceed?",
-    header: "Design Hand-off",
+    question: "The spec is at docs/specs/YYYY-MM-DD-<slug>-design.md. How do you want to proceed?",
+    header: "Hand-off",
     options: [
-      { label: "Proceed to /plan feature (Recommended)", description: "Formalize this spec into a PRD with acceptance criteria and issue creation." },
-      { label: "Proceed to /write-executable-plan", description: "Skip the formal PRD and go straight to an executable plan (issue #39, once shipped)." },
-      { label: "Revise the spec", description: "I have feedback — describe what to change and I'll update the spec." },
-      { label: "Done for now", description: "Keep the spec as a reference; no immediate next step." }
+      { label: "Proceed to /plan feature (Recommended)", description: "Turns the spec into a PRD with acceptance criteria, then files the issues. Cost: one more question round." },
+      { label: "Proceed to /write-executable-plan", description: "Skips the formal PRD and writes a step-by-step executable plan instead — tracked in #39 (a numbered ticket, not yet released)." },
+      { label: "Revise the spec", description: "Describe what to change; the spec is updated and comes back here." },
+      { label: "Done for now", description: "The spec stays on disk as a reference. Nothing else runs." }
     ],
     multiSelect: false
   }]

package/skills/brainstorm/soul.md

@@ -62,6 +62,18 @@ The active level is `efficiency.output-level` in `~/.config/session-orchestrator
 - Shape: explain WHY each option is on the table, name the paths you already discarded and why, define unfamiliar terms on first use.
 - Escalation: `expand <topic>` — see § Escalation above.
 
+### Register — how a sentence reads
+
+The budgets above set *how much* you say; the register sets *how*. It is
+defined once, in `skills/session-start/soul.md` § "Register — how a sentence
+reads", and binds here unchanged: the frame ("write for someone who knows this
+project but has not seen what you just saw"), the plain-words test with its
+five worked cases, and its precedence over § "Never traded for brevity" above.
+Read it there. It is not repeated here on purpose — the § Output Levels intro
+sentence already exists in four copies across the four souls with nothing
+checking their parity, and a fifth copied rule would drift the same way. A
+pointer cannot.
+
 ### Companion dials
 
 Same file, same lookup, same fallback-to-default rule:

package/skills/claude-md-drift-check/checker.mjs

@@ -910,11 +910,18 @@ function main() {
   //   kebab(s) = s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
   //
   // WARN (never error) when:
-  //   - learnings.jsonl is present AND no entry's derived key matches the rule's
-  //     `learning-key` (absent learning), OR
+  //   - NEITHER a learnings.jsonl entry NOR a valid `evidence-digest` frontmatter
+  //     scalar is present (the rule's provenance is unresolvable), OR
   //   - the matching entry's `expires_at` < now (expired learning).
-  // When learnings.jsonl is absent, every key counts as absent — warn on each
-  // generated rule's key.
+  //
+  // #1101 — the digest branch. `.orchestrator/metrics/learnings.jsonl` is
+  // GITIGNORED, so in a fresh clone it does not exist and every generated rule
+  // used to warn (measured 2026-08-26: 23 of 23). A rule carrying a valid
+  // `evidence-digest: sha256-v1:<64 hex>` is SELF-CONTAINED — its `## Evidence`
+  // block plus its own `## Provenance` header fields re-derive the seal with no
+  // jsonl lookup — so its provenance is resolvable offline and it must not warn.
+  // The digest is EVIDENCE, not a second pointer; see
+  // `scripts/lib/reconcile/renderer.mjs` § computeEvidenceDigest.
   // The check is silently skipped (no id pushed) when .claude/rules/ is absent
   // or contains no .md files with auto-generated: true.
   if (!args.skipGeneratedRuleStaleness) {
@@ -926,15 +933,17 @@ function main() {
     // Reads the opening --- ... --- block from a markdown file.
     function extractFrontmatterFields(mdContent) {
       const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(stripLeadingRuleHeaderLines(mdContent));
-      if (!m) return { autoGenerated: false, learningKey: null, expiresAt: null };
+      if (!m) return { autoGenerated: false, learningKey: null, expiresAt: null, evidenceDigest: null };
       const block = m[1];
       const autoGenM = /^auto-generated:\s*(.+)$/m.exec(block);
       const learningKeyM = /^learning-key:\s*(.+)$/m.exec(block);
       const expiresAtM = /^expires-at:\s*(.+)$/m.exec(block);
+      const evidenceDigestM = /^evidence-digest:\s*(.+)$/m.exec(block);
       return {
         autoGenerated: autoGenM ? autoGenM[1].trim() === 'true' : false,
         learningKey: learningKeyM ? learningKeyM[1].trim() : null,
         expiresAt: expiresAtM ? expiresAtM[1].trim() : null,
+        evidenceDigest: evidenceDigestM ? evidenceDigestM[1].trim() : null,
       };
     }
 
@@ -955,12 +964,20 @@ function main() {
         relPath: relative(vaultDir, absPath),
         learningKey: fields.learningKey,
         expiresAt: fields.expiresAt,
+        evidenceDigest: fields.evidenceDigest,
       });
     }
 
     // No generated rules found → silently skip (don't push the check id).
     if (generatedRules.length === 0) return;
 
+    // #1101 — a LITERAL COPY of `EVIDENCE_DIGEST_RE` from
+    // `scripts/lib/reconcile/renderer.mjs`. Copied, not imported: this checker
+    // is a standalone skill script, and importing across the skill/script
+    // boundary would add real coupling for one 30-character literal. The two
+    // copies are pinned equal by `tests/lib/reconcile/renderer.test.mjs`.
+    const EVIDENCE_DIGEST_RE = /^sha256-v1:[0-9a-f]{64}$/;
+
     // Slugify function mirroring emitter.mjs `kebab()`.
     const kebab = (s) =>
       String(s)
@@ -1001,26 +1018,37 @@ function main() {
     const nowMs = Date.now();
 
     for (const rule of generatedRules) {
-      const { relPath, learningKey, expiresAt } = rule;
+      const { relPath, learningKey, expiresAt, evidenceDigest } = rule;
 
       // If we cannot evaluate the key (no learning-key frontmatter), skip
       // silently — avoid false positives on malformed rules.
       if (!learningKey) continue;
 
-      if (!learningsPresent || !knownKeys.has(learningKey)) {
-        // Learning is absent from learnings.jsonl (or the file is missing entirely).
+      const hasJsonlEntry = learningsPresent && knownKeys.has(learningKey);
+      const hasValidDigest =
+        typeof evidenceDigest === 'string' && EVIDENCE_DIGEST_RE.test(evidenceDigest);
+
+      if (!hasJsonlEntry && !hasValidDigest) {
+        // NEITHER resolution path is available: the learning is absent from
+        // learnings.jsonl (or the file is missing entirely) AND the rule carries
+        // no self-contained evidence digest, so nothing can vouch for it.
         warnings.push({
           check: 'generated-rule-staleness',
           file: relPath,
           line: 1,
-          message: `Auto-generated rule references learning-key '${learningKey}' which is absent from .orchestrator/metrics/learnings.jsonl`,
+          message: `Auto-generated rule references learning-key '${learningKey}' which is absent from .orchestrator/metrics/learnings.jsonl, and the rule carries no valid evidence-digest to verify it offline`,
           extracted: learningKey,
         });
         continue;
       }
 
-      // Learning exists — check expiry.
-      const storedExpiresAt = knownKeys.get(learningKey);
+      // Provenance resolves — check expiry.
+      // `storedExpiresAt` is only meaningful when the jsonl entry actually
+      // exists. A digest-only rule (fresh clone, or a learning aged out of the
+      // store) is AUTHORITATIVE FOR ITS OWN EXPIRY via frontmatter; reading a
+      // stored value that is not there would make `expiryStr` null and silently
+      // skip the expiry gate for a rule that has a perfectly good `expires-at`.
+      const storedExpiresAt = hasJsonlEntry ? knownKeys.get(learningKey) : null;
       // Prefer the frontmatter expires-at on the rule file; fall back to the
       // stored expires_at from the learning entry (both should agree, but the
       // rule file is authoritative for its own expiry).

package/skills/discovery/SKILL.md

@@ -104,13 +104,13 @@ When the gate above is satisfied, present exactly this AskUserQuestion (AUQ-003
 ```
 AskUserQuestion({
   questions: [{
-    question: "Scope `feature` was requested. How should this run handle feature discovery?",
-    header: "Feature Scope",
+    question: "Scope `feature` was requested. How should this run handle it?",
+    header: "Scope",
     options: [
-      { label: "Grounded scan (Recommended)", description: "Run the evidence-anchored feature probes (intent-drift, stubbed-dead-feature) on the probe→verify→triage rails." },
-      { label: "Also judgment topics", description: "Grounded scan PLUS collect judgment-based product questions (opportunity framing, personas). A follow-up prompt after Phase 5 offers inline synthesis or hand-off to /brainstorm or /plan feature — judgment items never enter the verified-findings pipeline." },
-      { label: "Route out", description: "No scan; hand off to /brainstorm (product ideation) or /grill (assumption stress-test) instead." },
-      { label: "Skip", description: "Drop `feature` from this run's scope set." }
+      { label: "Grounded scan (Recommended)", description: "Every finding is tied to a file and line and is verified before it can become an issue. Cost: two extra probes (intent-drift, stubbed-dead-feature)." },
+      { label: "Also judgment topics", description: "Same scan, plus open product questions (opportunity framing, personas) kept as notes. They never become issues; after Phase 5 you pick where they go." },
+      { label: "Route out", description: "No scan at all. You get a pointer to /brainstorm (product ideation) or /grill (assumption stress-test) instead." },
+      { label: "Skip", description: "Drops `feature` (the probes for half-built and drifted features) from this run; the other scopes still run." }
     ],
     multiSelect: false
   }]
@@ -125,12 +125,12 @@ AskUserQuestion({
 ```
 AskUserQuestion({
   questions: [{
-    question: "Judgment topics were collected alongside the grounded scan. How should they be handled?",
-    header: "Judgment Topics",
+    question: "Where should the collected judgment topics go?",
+    header: "Topics",
     options: [
-      { label: "Inline synthesis (Recommended)", description: "Sketch a lightweight OST/persona pass directly in the report's `### Judgment Topics (non-verified)` appendix — explicitly marked non-verified, no separate skill invocation needed." },
-      { label: "Route to /brainstorm", description: "Hand the collected topics off as pre-filled context to /brainstorm for a full Socratic ideation dialogue." },
-      { label: "Route to /plan feature", description: "Hand the collected topics off as pre-filled context to /plan feature for feature-PRD scoping." }
+      { label: "Inline synthesis (Recommended)", description: "Sketches an outcome/persona pass into `### Judgment Topics (non-verified)` (a report section that never becomes issues). Cost: no second run." },
+      { label: "Route to /brainstorm", description: "Hands the topics to /brainstorm as its opening context, for a full question-and-answer design dialogue." },
+      { label: "Route to /plan feature", description: "Hands the topics to /plan feature as its opening context, for feature-PRD scoping." }
     ],
     multiSelect: false
   }]
@@ -370,14 +370,16 @@ For each Critical or High finding, use AskUserQuestion (on Codex CLI where AskUs
 ```
 AskUserQuestion({
   questions: [{
-    question: "<finding title>\n\n<file_path>:<line_number>\n```\n<matched_text with +/-3 lines context>\n```\n\n<description>\n\nRecommended fix: <recommended_fix>",
-    header: "<severity>",
+    question: "<severity> finding in <file_path> — what should happen with it?",
+    header: "Finding",
     options: [
-      { label: "Create issue (<severity>)", description: "Create a priority::<severity> issue for this finding" },
-      { label: "Adjust priority", description: "Create issue with different priority" },
-      { label: "Dismiss -- intentional", description: "This is by design, skip" },
-      { label: "Dismiss -- false positive", description: "Detection was wrong, skip" }
-    ]
+      { label: "Create issue (<severity>)", description: "Files it as priority::<severity>, so it is tracked outside this session. The code below is copied into the issue body.",
+        preview: "<finding title>\n\n<file_path>:<line_number>\n```\n<matched_text with +/-3 lines context>\n```\n\n<description>\n\nRecommended fix: <recommended_fix>" },
+      { label: "Adjust priority", description: "Same issue, a priority you pick — this question then comes back with the new label." },
+      { label: "Dismiss -- intentional", description: "The code is deliberate. Nothing is filed, and the finding stays only in this run's report." },
+      { label: "Dismiss -- false positive", description: "The probe misread the code. Nothing is filed; worth reporting if the same probe misfires again." }
+    ],
+    multiSelect: false
   }]
 })
 ```
@@ -391,13 +393,15 @@ Group remaining findings by category. For each category with medium/low findings
 ```
 AskUserQuestion({
   questions: [{
-    question: "[N] medium/low findings in [category]:\n\n1. [title] -- [file_path]:[line] ([severity])\n2. [title] -- [file_path]:[line] ([severity])\n...",
-    header: "[Category]",
+    question: "Create issues for all [N] medium/low findings in [category]?",
+    header: "Findings",
     options: [
-      { label: "Accept all (Recommended)", description: "Create issues for all [N] findings" },
-      { label: "Review individually", description: "Walk through each finding one by one" },
-      { label: "Dismiss all", description: "Skip all medium/low findings in this category" }
-    ]
+      { label: "Accept all (Recommended)", description: "Medium and low findings are cheap to file and cheap to close. Cost: [N] issues, roughly one second apart.",
+        preview: "1. [title] -- [file_path]:[line] ([severity])\n2. [title] -- [file_path]:[line] ([severity])\n..." },
+      { label: "Review individually", description: "One question per finding, same options as the critical ones. Cost: [N] more prompts." },
+      { label: "Dismiss all", description: "Nothing is filed for this category. The findings stay in this run's report only." }
+    ],
+    multiSelect: false
   }]
 })
 ```

package/skills/dispatcher/SKILL.md

@@ -113,7 +113,7 @@ const res = claimRepo({ repoRoot: R, sessionId, mode, ttlHours, semanticSessionI
 Or reuse the primitive directly: `acquire({ sessionId, mode, ttlHours, repoRoot, semanticSessionId })` from `scripts/lib/session-lock.mjs`. The claim is a `linkSync` create-or-fail = **atomic**.
 
 - **`ok: true`** → the claim is held. Proceed to Phase 4.
-- **`ok: false`** (race lost / busy — reasons: `active`, `stale-pid-alive`, `stale-pid-dead`, `fs-error`, …) → **exclude R**, re-rank the remaining free candidates (drop R from `free`, re-run Phase 1's rank step), and re-present Phase 2. Loop until a claim succeeds or no free candidate remains (then Phase 5).
+- **`ok: false`** (race lost / busy — reasons: `active`, `stale-heartbeat`, `fs-error`, …) → **exclude R**, re-rank the remaining free candidates (drop R from `free`, re-run Phase 1's rank step), and re-present Phase 2. Loop until a claim succeeds or no free candidate remains (then Phase 5).
 
 Do NOT reinvent the claim — always go through `claimRepo`/`acquire`. The `ok:false` path is the load-bearing concurrency guard: two parallel dispatchers can both recommend R, but only one wins the `linkSync`; the loser must re-rank, never force.
 

package/skills/eli5/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: eli5
+description: Explain a topic like I'm a 5 year old — restate my last output, or a named topic, in plain words without dropping a single fact. Use when the user types /eli5 [topic], or says an answer was too technical, too long, or unclear about what he now has to do.
+model: inherit
+tools: Read, Grep, Glob, Bash
+---
+
+# eli5
+
+Say it again in plain words. Same facts, in the order he needs them.
+
+## The frame
+
+**Write for someone who knows this project but has not seen what you just saw.**
+
+He owns this repo. He is not missing knowledge, he is missing observation — he did not watch the command run or read the file it points at. Write across, not down. `.claude/rules/ask-via-tool.md` § AUQ-006 and `skills/session-start/soul.md` § Register are the canonical statement of this register; apply them, do not restate them.
+
+## What to restate
+
+- `/eli5` — my last substantial output in this conversation. If there is none yet, say so instead of inventing a topic.
+- `/eli5 <topic>` — that topic (`$ARGUMENTS`), grounded in what THIS session already measured: name the file, command, or record it came from. If it was never measured here, say that rather than filling the gap from memory.
+
+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 follow the operator's own language the moment he writes in another one.
+
+## Two limits, and they are the whole skill
+
+**1. Say more simply what actually happens — introduce nothing that does not exist.**
+Test: delete every noun the system does not contain. Sentence still true and complete → it was no analogy. Sentence collapses → describe what actually happens instead.
+✓ "Waiting means the other session finishes first." ✗ "Think of the session as a level crossing."
+
+**2. Simplifying removes words, never facts.** If a path, a number, an error code, an identifier, or an instruction to act disappears, that is data loss, not simplification. The mechanical decider: **could the token you are about to cut ever appear in a `grep`? Then it stays.** `skills/session-start/soul.md` § "Never traded for brevity" outranks every brevity instruction in this file.
+
+## Shape
+
+Line 1 answers the question he actually has: **do I have to do something now, and what happens if I don't?** Then the facts, in the order he needs them — not the order you found them.
+
+This is a terminal, so there is no picture to draw. The second channel is the `preview` field on an `AskUserQuestion` option: when the options differ in something literal — a diff, a title, a config block, a file list — put that text there and he reads the thing instead of a description of it.
+
+## What this is not
+
+- **Not shorter by default.** Eight lines before may be eight lines after. Reorder first; cut only filler.
+- **Not a children's explanation.** The label is a poster, the reader is an expert who was not in the room.
+- **Not a second attempt at the answer.** If the first answer was wrong, fix the answer — `/eli5` restates, it never re-derives.

package/skills/evolve/SKILL.md

@@ -248,8 +248,8 @@ Present extracted patterns to the user for confirmation. Use AskUserQuestion wit
 ```
 AskUserQuestion({
   questions: [{
-    question: "Which learnings should be saved?\n\nExtracted patterns from session history:",
-    header: "Evolve — Confirm Learnings",
+    question: "Which of the patterns extracted from this session's history should be saved?",
+    header: "Speichern?",
     options: [
       {
         label: "[type] subject",
@@ -455,19 +455,18 @@ Use AskUserQuestion with options:
 AskUserQuestion({
   questions: [{
     question: "What would you like to do with your learnings?",
-    header: "Evolve — Review",
+    header: "Learnings",
     options: [
-      { label: "Boost confidence", description: "Select learnings to boost (+0.15)" },
-      { label: "Reduce confidence", description: "Select learnings to reduce (-0.2)" },
-      { label: "Delete specific learnings", description: "Select learnings to remove" },
-      { label: "Extend expiry", description: "Reset expires_at by learning-expiry-days from now" },
-      { label: "Done — no changes", description: "Exit without changes" }
+      { label: "Confidence ändern", description: "Pick the learnings, then the direction: +0.15 or -0.2. Cheapest fix when a learning is merely mis-weighted." },
+      { label: "Ablauf verlängern", description: "Keeps a still-useful learning alive: its expiry date moves to today plus the configured window. Confidence is untouched." },
+      { label: "Delete specific learnings", description: "Takes the selected learnings out of the store. They are archived rather than shredded, but they stop influencing anything." },
+      { label: "Done — no changes", description: "Leaves the store exactly as it is and ends the review. Nothing is written." }
     ]
   }]
 })
 ```
 
-If user selects "Boost confidence", "Reduce confidence", "Delete specific learnings", or "Extend expiry", present a follow-up AskUserQuestion with `multiSelect: true` listing all learnings by `# | type | subject` so the user can select which ones to modify.
+If user selects "Confidence ändern", "Ablauf verlängern", or "Delete specific learnings", present a follow-up AskUserQuestion with `multiSelect: true` listing all learnings by `# | type | subject` so the user can select which ones to modify. For "Confidence ändern" the same follow-up also asks for the direction — **Boost** (+0.15) or **Reduce** (-0.2). Both operations are unchanged; only the point at which the direction is chosen moved, because a single AskUserQuestion accepts at most 4 options and the previous list had 5.
 
 > On Codex CLI where AskUserQuestion is unavailable, present as a numbered Markdown list.
 

package/skills/gitlab-ops/SKILL.md

@@ -9,7 +9,7 @@ model-preference-cursor: claude-sonnet-4-6
 description: >
   Use this skill when performing VCS operations on GitLab or GitHub repositories — creating, updating, or
   closing issues and MRs, applying label taxonomy, running `glab`/`gh` CLI commands, or resolving project
-  IDs dynamically. Acts as the single source of truth for CLI command syntax and label conventions;
+  paths dynamically. Acts as the single source of truth for CLI command syntax and label conventions;
   consuming skills reference this rather than duplicating logic. Triggers: "create a GitLab issue", "list
   open MRs", "apply priority label", "how do I resolve the project ID", "what's the carryover issue
   template". <example>Context: session-end needs to file a carryover issue for an incomplete task. user:
@@ -45,7 +45,7 @@ syntax inline. This skill is the single source of truth for all VCS operations.
 When a skill needs VCS operations, include this reference block in its instructions:
 
 > **VCS Reference:** Detect the VCS platform per the "VCS Auto-Detection" section of the gitlab-ops skill.
-> Use CLI commands per the "Common CLI Commands" section. For cross-project queries, see "Dynamic Project Resolution."
+> Use CLI commands per the "Common CLI Commands" section. For GitLab API operations, see "Canonical Project Identity."
 
 **Canonical commands:** All `glab` and `gh` command syntax — flags, output formats,
 pagination options — is defined in the "Common CLI Commands" section below. Consuming
@@ -57,34 +57,35 @@ command variant not listed there, add it to this file first, then reference it.
 - Any skill-specific *parameters* they pass to commands (e.g., label names, issue templates)
 - They should NOT include raw `glab`/`gh` invocations or detection snippets
 
-## Dynamic Project Resolution
+## Canonical Project Identity
 
-Never hardcode project IDs. Resolve them at runtime — and re-resolve live each session; never cache a project ID across sessions (a stale ID silently targets the wrong project on rename/fork/mirror-drift, and is the root cause behind the close-verification incident documented below).
+GitLab REST endpoints accept a URL-encoded `namespace/project` path. Select the GitLab host and project path explicitly; never derive a numeric project ID from `glab repo view`, search `projects?search=`, or use `:id` placeholders. Those forms can resolve through the ambient working directory or a stale search result and target another project after a rename, fork, or scaffold.
 
-### Current project
+Set the identity once per operation sequence and reuse the encoded identifier without encoding it again:
 
 ```bash
-# GitLab — get numeric project ID
-glab repo view -R <OWNER>/<REPO> --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])"
+GITLAB_HOST="<selected GitLab hostname>"
+GROUP_PATH="<selected group path>"
+PROJECT_NAME="<selected project name>"
+PROJECT_PATH="$GROUP_PATH/$PROJECT_NAME"
+ENCODED_PROJECT_PATH="$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$PROJECT_PATH")"
+```
 
-# GitHub — get owner/name identifier (gh repo takes the repo POSITIONALLY; it rejects -R)
-gh repo view --json nameWithOwner -q '.nameWithOwner'
+For a link target in another project, use the same path-first shape instead of a numeric ID:
+
+```bash
+TARGET_PROJECT_PATH="<target namespace>/<target project>"
+TARGET_ENCODED_PROJECT_PATH="$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$TARGET_PROJECT_PATH")"
 ```
 
-### Cross-project queries
+Pass `--hostname "$GITLAB_HOST"` to every `glab api` call. The endpoint itself then pins the project, including directly after creating a repository when the current directory does not yet identify the new project.
 
-When a skill needs to reference other projects (e.g., from `cross-repos` in Session Config):
+GitHub continues to use an `owner/repo` slug; `gh repo` takes it positionally and rejects `-R`:
 
 ```bash
-# GitLab — resolve project ID by name
-glab api "projects?search=<project-name>" | python3 -c "import json,sys; [print(p['id'], p['path_with_namespace']) for p in json.load(sys.stdin)]"
-
-# GitHub — resolve repo details
-gh api "repos/<owner>/<name>" --jq '.full_name'
+gh repo view --json nameWithOwner -q '.nameWithOwner'
 ```
 
-**Note:** Some API calls require numeric project IDs (GitLab) or `owner/repo` slugs (GitHub). Always resolve dynamically from the project name.
-
 ### Canonical enumeration pattern
 
 To enumerate ALL projects (or issues) in a group, a single page is never the whole result — paginate and guard against silent truncation:
@@ -93,7 +94,7 @@ To enumerate ALL projects (or issues) in a group, a single page is never the who
 # GitLab — paginate a group's projects, following x-next-page until empty
 page=1
 while [ -n "$page" ]; do
-  resp=$(glab api "groups/<group-id>/projects?include_subgroups=true&per_page=100&page=$page" --include)
+  resp=$(glab api --hostname "$GITLAB_HOST" "groups/<group-id>/projects?simple=true&include_subgroups=true&per_page=100&page=$page" --include)
   # parse the response body ($resp) for project ids/paths here, deduping by id.
   # Then advance by reading the `x-next-page` response header — an empty value
   # means this was the last page, so the loop exits (the guard above is what breaks).
@@ -146,13 +147,16 @@ done
 
 ## Issue Linking (`blocks` / `is_blocked_by`)
 
-GitLab's native issue-link types `blocks` and `is_blocked_by` (`glab api -X POST projects/:id/issues/:issue_iid/links -f link_type=blocks|is_blocked_by`) are a **Premium/Ultimate license feature**. On a Free/Core-tier GitLab instance this call returns **HTTP 403** — a license-gate signal, not an auth/permission failure. Do not retry with different credentials or escalate as an auth bug.
+GitLab's native issue-link types `blocks` and `is_blocked_by` (`glab api --silent --hostname "$GITLAB_HOST" -X POST "projects/${ENCODED_PROJECT_PATH}/issues/${ISSUE_IID}/links" -f target_project_id="$TARGET_ENCODED_PROJECT_PATH" -f target_issue_iid="$OTHER_ISSUE_IID" -f link_type="$LINK_TYPE"`) are a **Premium/Ultimate license feature**. Set `LINK_TYPE` to `blocks` or `is_blocked_by`; the target accepts an encoded project path, so no numeric project ID is needed. On a Free/Core-tier GitLab instance this call returns **HTTP 403** — a license-gate signal, not an auth/permission failure. Do not retry with different credentials or escalate as an auth bug.
 
 **Fallback (non-Premium instances):**
 1. **Use `relates_to` instead** — `link_type=relates_to` is available on every GitLab tier (no ordering semantics, just an unscoped relation). Same API shape, only the `link_type` value changes:
    ```bash
-   glab api -X POST "projects/:id/issues/:issue_iid/links" \
-     -f target_project_id=:id -f target_issue_iid=:other_iid -f link_type=relates_to
+   glab api --silent --hostname "$GITLAB_HOST" -X POST \
+     "projects/${ENCODED_PROJECT_PATH}/issues/${ISSUE_IID}/links" \
+     -f target_project_id="$TARGET_ENCODED_PROJECT_PATH" \
+     -f target_issue_iid="$OTHER_ISSUE_IID" \
+     -f link_type=relates_to
    ```
 2. **Document the blocking semantics in the issue body** — since `relates_to` carries no ordering meaning, add an explicit ordering note to both issues, e.g. `⚠ Ordering: erst #<blocker_iid>, dann dieses Issue — blocks-Link nicht verfügbar (non-Premium)`.
 3. **Recognize the 403 as a license signal, not an auth error** — before assuming a token/scope problem, try `relates_to` on the same project pair: if `relates_to` succeeds where `blocks`/`is_blocked_by` 403s, the license gate — not authentication — is the cause.
@@ -187,14 +191,14 @@ glab mr merge -R <OWNER>/<REPO> <MR_IID>                                   # Mer
 glab pipeline list -R <OWNER>/<REPO> --per-page 5                          # Recent pipelines
 glab pipeline status -R <OWNER>/<REPO> <ID>                                # Pipeline details
 
-# API (no --repo exists here — the endpoint path IS the target; pin the host with --hostname)
-glab api "projects/$(glab repo view -R <OWNER>/<REPO> --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")/issues?state=opened&per_page=50"
-glab api "projects/$(glab repo view -R <OWNER>/<REPO> --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")/milestones?state=active"
+# API (no --repo exists here — the encoded endpoint and explicit host identify the target)
+glab api --hostname "$GITLAB_HOST" "projects/${ENCODED_PROJECT_PATH}/issues?state=opened&per_page=50"
+glab api --hostname "$GITLAB_HOST" "projects/${ENCODED_PROJECT_PATH}/milestones?state=active"
 ```
 
 **Label update caveat (PUT-replaces, not additive):** `glab issue update --label` (and the underlying GitLab labels API) PUT-REPLACES the entire label set — it does not add to the existing set. To change a single label you must pass the FULL desired label list, or use the dedicated add/remove operations, which are themselves unreliable across `glab` versions. Preferred safe pattern: use `--label` (adds) together with `--unlabel` (removes) on `glab issue update` when your installed `glab` version supports both; otherwise read the current labels first, compute the full new set, and PUT once. The same PUT-replace semantics apply to `glab mr update --label`.
 
-**Close verification:** after `glab issue close <IID>`, always verify the close actually landed — re-read the issue (`glab issue view <IID>`) and confirm `state: closed` in the output. A stale/wrong project ID or a silent 404 can report local success while closing nothing; a documented incident closed 32 issues into the void this way (project ID pointed at the wrong project — see "Dynamic Project Resolution" above for the re-resolve-each-session rule that prevents it).
+**Close verification:** after `glab issue close <IID>`, always verify the close actually landed — re-read the issue (`glab issue view <IID>`) and confirm `state: closed` in the output. A stale or wrong project path, or a silent 404, can report local success while closing nothing; use the canonical project identity above for API operations rather than resolving a numeric ID.
 
 **Commit-body close-keyword footgun:** GitLab (and GitHub) auto-close an issue when a commit pushed to the default branch contains a close keyword — `close`/`closes`/`closed`/`fix`/`fixes`/`fixed`/`resolve`/`resolves`/`resolved` — followed by `#N` ANYWHERE in the commit body, not just the subject line. This fires even inside a negation ("does NOT close #N") — the platform pattern-matches the keyword + issue reference; it does not parse English negation, so the negation offers no protection. Rule: when a commit body needs to MENTION an issue without closing intent, always use a non-closing reference — `refs #N`, `part of #N`, `siehe #N` — never a close-keyword verb next to the number, negated or not.
 

package/skills/grill/SKILL.md

@@ -66,7 +66,7 @@ Walk the decision tree **one question at a time**. For each branch, in order:
 AskUserQuestion({
   questions: [{
     question: "Your code cancels whole Orders, but the PRD says a customer can cancel one line item. Which is the real model?",
-    header: "Cancellation Scope",
+    header: "Cancel scope",
     options: [
       { label: "Line-item cancellation (Recommended)", description: "Matches the PRD intent. Cost: new partial-refund path + Order stays open after one item is voided." },
       { label: "Whole-order only", description: "Matches today's code. Cost: contradicts the stated user story — re-scope the PRD." },
@@ -118,12 +118,12 @@ Per the user's configured behaviour, the grill ends with a hand-off and an OPTIO
 AskUserQuestion({
   questions: [{
     question: "Grill complete. How do you want to proceed?",
-    header: "Grill Hand-off",
+    header: "Hand-off",
     options: [
-      { label: "Write grill summary + hand off to /plan feature (Recommended)", description: "Persist resolved decisions to docs/specs/, then formalize into a PRD." },
-      { label: "Write grill summary only", description: "Keep the resolved decisions as a reference; no further step now." },
-      { label: "Hand off to /plan feature — no file", description: "Carry the resolved decisions straight into planning; nothing persisted." },
-      { label: "Done — no file, no hand-off", description: "The grilling itself was the value; leave no artifact." }
+      { label: "Summary + /plan feature (Recommended)", description: "Writes the resolved decisions to docs/specs/ (a folder of markdown notes), then hands them to planning. Cost: one file." },
+      { label: "Write grill summary only", description: "Same file, no planning step. The decisions keep, so you can hand them off later." },
+      { label: "Hand off to /plan feature — no file", description: "Carries the decisions straight into planning. They then live only in this conversation." },
+      { label: "Done — no file, no hand-off", description: "The grilling itself was the value. Nothing is written, nothing is handed on." }
     ],
     multiSelect: false
   }]

package/skills/grill/soul.md

@@ -76,6 +76,22 @@ This is the tightest of the orchestrator's budgets by design. A turn is structur
 - 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.
 
+### Register — how a sentence reads
+
+The budgets above set *how much* you say; the register sets *how*. It is
+defined once, in `skills/session-start/soul.md` § "Register — how a sentence
+reads", and binds here unchanged: the frame ("write for someone who knows this
+project but has not seen what you just saw"), the plain-words test with its
+five worked cases, and its precedence over § "Never traded for brevity" above.
+Read it there. It is not repeated here on purpose — the § Output Levels intro
+sentence already exists in four copies across the four souls with nothing
+checking their parity, and a fifth copied rule would drift the same way. A
+pointer cannot.
+
+Note the one place register and adversarial posture meet: a challenge is
+plainer, never softer. "Say it more simply" never becomes "say it less
+sharply" — the contradiction still lands, in shorter words.
+
 ### Companion dials
 
 Same file, same lookup, same fallback-to-default rule: