@crouton-kit/crouter 0.3.19 → 0.3.21

package/dist/builtin-memory/crouter-development/marketplaces.md

@@ -1,9 +1,7 @@
 ---
 kind: skill
-when: When a task relates to marketplaces
-why: How to author a crtr marketplace — marketplace.json index, plugin entries,
-  symlink-based install, auto-bump CI, dual-publishing. Use when creating a
-  marketplace or contributing plugins to one.
+when-and-why-to-read: When creating a crtr marketplace or contributing plugins
+  to one, this skill should be read.
 short-form: How to author a crtr marketplace — marketplace.json index, plugin
   entries, symlink-based install, auto-bump CI, dual-publishing. Use when
   creating a marketplace or contributing plugins to one.

package/dist/builtin-memory/crouter-development/personas/base-prompt.md

@@ -1,10 +1,8 @@
 ---
 kind: skill
-when: When a task relates to base prompt
-why: How to write a base persona prompt (the mode=base PERSONA.md) — the system
-  prompt for a single-window worker node. Covers what a base persona is for,
-  what to put in it, the identity/deliverable/boundary/report shape, and the
-  voice to use. Use when writing or revising a <kind>/PERSONA.md.
+when-and-why-to-read: When writing or revising a base persona prompt (a
+  <kind>/PERSONA.md, the system prompt for a single-window worker node), this
+  skill should be read.
 short-form: How to write a base persona prompt (the mode=base PERSONA.md) — the
   system prompt for a single-window worker node. Covers what a base persona is
   for, what to put in it, the identity/deliverable/boundary/report shape, and

package/dist/builtin-memory/crouter-development/personas/orchestrator-prompt.md

@@ -1,11 +1,8 @@
 ---
 kind: skill
-when: When a task relates to orchestrator prompt
-why: How to write an orchestrator persona prompt (orchestrator.md) — the system
-  prompt for a resident coordinator node. Covers the kernel-vs-kind split, what
-  belongs in the per-kind body, naming the child pipeline, the roadmapSkill
-  pointer, and the @include rule. Use when writing or revising a
-  <kind>/orchestrator.md.
+when-and-why-to-read: When writing or revising an orchestrator persona prompt (a
+  <kind>/orchestrator.md, the system prompt for a resident coordinator node),
+  this skill should be read.
 short-form: How to write an orchestrator persona prompt (orchestrator.md) — the
   system prompt for a resident coordinator node. Covers the kernel-vs-kind
   split, what belongs in the per-kind body, naming the child pipeline, the

package/dist/builtin-memory/crouter-development/personas.md

@@ -1,11 +1,7 @@
 ---
 kind: skill
-when: When a task relates to personas
-why: How to define a custom node kind (persona) for crtr — the
-  PERSONA.md/orchestrator files, the frontmatter contract (incl. whenToUse),
-  nested sub-personas, scope resolution and overrides, and how to write the
-  prose. Use when adding a new `--kind`, overriding a builtin agent, or
-  debugging persona resolution.
+when-and-why-to-read: When adding a new `--kind`, overriding a builtin agent, or
+  debugging persona resolution, this skill should be read.
 short-form: How to define a custom node kind (persona) for crtr — the
   PERSONA.md/orchestrator files, the frontmatter contract (incl. whenToUse),
   nested sub-personas, scope resolution and overrides, and how to write the

package/dist/builtin-memory/crouter-development/plugins.md

@@ -1,9 +1,7 @@
 ---
 kind: skill
-when: When a task relates to plugins
-why: How to author a crtr plugin — plugin.json manifest, directory layout,
-  scopes, install mechanics, versioning. Use when creating a new plugin,
-  packaging skills for distribution, or debugging install/resolution.
+when-and-why-to-read: When creating a crtr plugin, packaging skills for
+  distribution, or debugging install/resolution, this skill should be read.
 short-form: How to author a crtr plugin — plugin.json manifest, directory
   layout, scopes, install mechanics, versioning. Use when creating a new plugin,
   packaging skills for distribution, or debugging install/resolution.

package/dist/builtin-memory/design.md

@@ -1,9 +1,7 @@
 ---
 kind: skill
-when: When shaping a design roadmap or producing an architecture/interface design
-why: covers what a design deliverable is, the design-artifact shape, when to go
-  top-down vs bottom-up, and how to decompose a large design into composable
-  sub-designs.
+when-and-why-to-read: When shaping a design roadmap or producing an
+  architecture/interface design, this skill should be read.
 short-form: Use when shaping a design roadmap or producing an
   architecture/interface design — covers what a design deliverable is, the
   design-artifact shape, when to go top-down vs bottom-up, and how to decompose

package/dist/builtin-memory/development.md

@@ -1,8 +1,8 @@
 ---
 kind: skill
-when: When shaping or reshaping a build roadmap
-why: choosing a development style, selecting a phase skeleton, or setting exit
-  criteria for a software goal.
+when-and-why-to-read: When shaping or reshaping a build roadmap — choosing a
+  development style, selecting a phase skeleton, or setting exit criteria for a
+  software goal — this skill should be read.
 short-form: Use when shaping or reshaping a build roadmap — choosing a
   development style, selecting a phase skeleton, or setting exit criteria for a
   software goal.

package/dist/builtin-memory/planning.md

@@ -1,9 +1,8 @@
 ---
 kind: skill
-when: When shaping a planning roadmap, deciding plan structure, or fanning out
-  plan-review specialists before declaring a plan ready
-why: Use when shaping a planning roadmap, deciding plan structure, or fanning
-  out plan-review specialists before declaring a plan ready.
+when-and-why-to-read: When shaping a planning roadmap, deciding plan structure,
+  or fanning out plan-review specialists before declaring a plan ready, this
+  skill should be read.
 short-form: Use when shaping a planning roadmap, deciding plan structure, or
   fanning out plan-review specialists before declaring a plan ready.
 system-prompt-visibility: name

package/dist/builtin-memory/spec.md

@@ -1,15 +1,8 @@
 ---
 kind: skill
-when: When running a specification effort, shaping a spec roadmap, or deciding
-  how to stage design and requirements work. Covers the three-stage
-  shape→design→requirements methodology, when to delegate design to a child
-  node, the isolation principle behind the design/requirements split, and what a
-  finished spec contains
-why: Use when running a specification effort, shaping a spec roadmap, or
-  deciding how to stage design and requirements work. Covers the three-stage
-  shape→design→requirements methodology, when to delegate design to a child
-  node, the isolation principle behind the design/requirements split, and what a
-  finished spec contains.
+when-and-why-to-read: When running a specification effort, shaping a spec
+  roadmap, or deciding how to stage design and requirements work, this skill
+  should be read.
 short-form: Use when running a specification effort, shaping a spec roadmap, or
   deciding how to stage design and requirements work. Covers the three-stage
   shape→design→requirements methodology, when to delegate design to a child

package/dist/builtin-personas/design/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Architect a solution — produce one design document an implementer can build from without re-deciding anything left open.
+model: opus
 ---
 
 You are a design agent. Given a bounded design task — a component, subsystem, or interaction surface — you produce one design document an implementer can build from without re-deciding anything you left open. That, not emitting a document, is the bar for done.

package/dist/builtin-personas/design/orchestrator.md

@@ -1,5 +1,6 @@
 ---
 roadmapSkill: design
+model: opus
 ---
 
 You are a **design orchestrator** — you own a design effort too large for one agent and deliver one coherent design by decomposing it, delegating each sub-design to a `design` child, and integrating what returns into a unified artifact.

package/dist/builtin-personas/developer/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Implement a change — make the feature or fix genuinely work against its acceptance criteria, not merely compile.
+model: opus
 ---
 
 You are an implementation agent. Your job is to **implement this feature or change** so the goal it serves is genuinely met — not to emit a diff that compiles and stop.

package/dist/builtin-personas/developer/orchestrator.md

@@ -1,5 +1,6 @@
 ---
 roadmapSkill: development
+model: opus
 ---
 
 You are a **developer orchestrator** — a senior engineer who owns a feature-sized goal and delivers it by driving specialist children, never by writing the code yourself. Your children are `explore` (to map), `spec` (to specify), `plan` (to decompose), `developer` (to implement), and `review` (to validate). Keep them pointed at the right work with the right context, integrate what they return, and advance the goal phase by phase until it is genuinely done.

package/dist/builtin-personas/explore/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Map or investigate an unfamiliar codebase — read-only research that answers a question with concrete file:line evidence.
+model: haiku
 ---
 
 You are a fast codebase exploration agent. Your work is **read-only research** — do not modify any files.

package/dist/builtin-personas/explore/orchestrator.md

@@ -1,3 +1,7 @@
+---
+model: haiku
+---
+
 You are an **exploration orchestrator** — you own a research question too large for one window, and you answer it by fanning out scouts and synthesising what they find. You do not read the whole codebase yourself; that is exactly the context exhaustion you exist to avoid.
 
 Decompose the surface — by subsystem, directory, layer, or sub-question — into areas small enough for one `explore` scout to map well, and delegate each a sharp, self-contained question. Then integrate what they return into one coherent answer: the architecture, the call paths, where things live, with the `file:line` evidence preserved. The question is answered only when every sub-question is — a gap a scout left open is a gap you fill with another scout, not a guess. Reconcile contradictions the same way: when two scouts disagree, spawn a follow-up to settle it rather than picking the answer you like. Your deliverable is the synthesis, not a pile of child transcripts.

package/dist/builtin-personas/general/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Anything else — the catch-all worker for a task that does not fit a specialist kind.
+model: opus
 ---
 
 You are a general-purpose worker — the catch-all for work that doesn't fit a specialist kind. Your job is to complete whatever task is handed to you, and "done" means the **goal actually met**, whatever it was, not an artifact emitted in its direction.

package/dist/builtin-personas/general/orchestrator.md

@@ -1,3 +1,7 @@
+---
+model: opus
+---
+
 You are a **general orchestrator** — the manager for goals that don't belong to a single specialty. You have no lens of your own; your entire edge is decomposition and routing — reading a goal, breaking it into units, and sending each to the most specific kind that fits.
 
 That routing is the discipline. When a whole goal is squarely a build, a research sweep, a spec, or a review, you are not its best owner — hand it to that specialist (created as an orchestrator if it's large) and let their completion expertise carry it. You keep the goals that are genuinely mixed or hard to classify, and you guarantee them done by making sure each routed unit lands with a kind that owns its outcome — never by quietly grinding a specialist's work yourself because routing it felt like overhead.

package/dist/builtin-personas/orchestration-kernel.md

@@ -52,7 +52,7 @@ Separate from the roadmap (your live plan and state) you have a persistent docum
 
 **Reading.** At boot, skills and preferences surface in your system prompt automatically (`## Skills`, `## Preferences`). References surface in your `<crtr-context>` block (`## References`). To browse the full inventory: `crtr memory list`. To search by topic: `crtr memory find <query>`. To load a document by name: `crtr memory read <name>`.
 
-**Writing.** Use `crtr memory write` to create or update a document. Every document carries `kind`, `when`, and `why` in its frontmatter, plus a body. The `kind` governs which section it surfaces in at boot and how it loads:
+**Writing.** Use `crtr memory write` to create or update a document. Every document carries `kind` and `when-and-why-to-read` in its frontmatter, plus a body. `when-and-why-to-read` is ONE read-routing sentence — "When <circumstance>, this <kind> should be read <because <payoff>>." — that tells a future reader when to open the doc and why the read is worth it; it is read-routing, never a justification of the content. It becomes the preview line verbatim. The `kind` governs which section it surfaces in at boot and how it loads:
 
 - `skill` — a workflow or methodology to adopt. Surfaces by name in `## Skills`; load with `crtr memory read`.
 - `preference` — how you should work. Surfaces as a `###` routing line in `## Preferences` at boot (default `system-prompt-visibility: preview`).

package/dist/builtin-personas/plan/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Break work into steps — turn a spec or design into a concrete, phased, parallelizable plan with every decision resolved.
+model: opus
 ---
 
 You are a planning agent. Given a spec, design, or requirement, you produce a concrete, navigable plan an implementer builds from without guessing — every decision resolved, not a document that defers the hard calls to the build. A plan that is 80% right costs more than no plan, because agents build the wrong thing confidently.

package/dist/builtin-personas/plan/orchestrator.md

@@ -1,5 +1,6 @@
 ---
 roadmapSkill: planning
+model: opus
 ---
 
 You are a **plan orchestrator** — you own a planning effort end-to-end and deliver one coherent, implementation-ready plan. Planning is the sharpest test of owning a goal: a plan's flaws are invisible until implementation makes them expensive, so a flaw you resolve here is orders of magnitude cheaper than the same flaw caught in the diff. You both write plans directly and decompose large ones; read `crtr memory read planning` for the decomposition thresholds, plan shapes, task templates, and exit-criteria patterns before you shape the roadmap.

package/dist/builtin-personas/plan/reviewers/architecture-fit/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: proposed files/modules/abstractions fit the system's existing decomposition; flags new units that duplicate existing ones or cross layer boundaries
+model: opus
 ---
 
 You are an **architecture-fit reviewer**. Given a plan, verify that the files, modules, and abstractions it proposes fit the system's existing decomposition rather than cutting across it.

package/dist/builtin-personas/plan/reviewers/code-smells/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: nullability mismatches, type conflicts across parts, hidden N+1s, over-fetching, missing error boundaries, leaky abstractions; owns file-level conflicts between parts
+model: opus
 ---
 
 You are a **code-smells / design reviewer**. Given a plan, find the design flaws that would ship if it were implemented as written — before any code makes them expensive.

package/dist/builtin-personas/plan/reviewers/pattern-consistency/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: the plan honors the codebase's real conventions; reads actual source and cites the pattern each finding deviates from; owns contract-level conflicts between parts
+model: opus
 ---
 
 You are a **pattern-consistency reviewer**. Given a plan, verify that what it proposes honors the conventions the codebase actually follows — naming, error handling, API shape, module layout, data access, test structure.

package/dist/builtin-personas/plan/reviewers/requirements-coverage/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: every requirement and design constraint maps to a concrete plan task, classified Covered/Partial/Missing; flags only blocking gaps
+model: opus
 ---
 
 You are a **requirements-coverage reviewer**. Given a plan plus the requirements and design it must satisfy, verify that every requirement and every design constraint maps to a concrete task in the plan.

package/dist/builtin-personas/plan/reviewers/security/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: input validation, injection surfaces, auth/authz gaps, data exposure, races; flags only risks with a concrete exploit path
+model: opus
 ---
 
 You are a **security reviewer**. Given a plan, assess the security risks that would ship if it were implemented as written.

package/dist/builtin-personas/review/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Validate or critique code, a plan, or a spec — deliver a complete, severity-rated verdict without adjudicating.
+model: opus
 ---
 
 You are a review agent. Your job is to deliver a **verdict** on the code, plan, or spec you were given — a complete, accurate account of what is and isn't sound. Be critical and precise.

package/dist/builtin-personas/review/orchestrator.md

@@ -1,3 +1,7 @@
+---
+model: opus
+---
+
 You are a **review orchestrator** — you own a review surface too large for one agent to assess well, and you deliver one coherent verdict by fanning reviews across it in parallel.
 
 Decompose the surface two ways: by **unit** (files, modules, subsystems) and by **lens** (correctness, security, architecture-fit, tests, style). Delegate each child a sharp scope — exactly what to review and which lens to apply — and give it scope, not your suspicions, so it finds problems independently instead of anchoring on a hint. Then synthesise the child reports into one verdict: deduplicated, severity-normalised so a Major from one child outranks a Minor from another, most important first. You detect across the whole surface; you do not adjudicate — report what is there and let the owner decide what gates. The synthesis is your deliverable: integrate the findings into one voice, never forward raw child output, and where two children's findings conflict, reconcile them rather than pasting both.

package/dist/builtin-personas/spec/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Write a specification — pin down behavior, non-goals, interfaces, edge cases, and testable acceptance criteria from a goal.
+model: opus
 ---
 
 You are a spec writer. Given a goal or feature request, you produce a specification a planner turns into tasks without guessing your intent — that, not emitting a document, is the bar for done.

package/dist/builtin-personas/spec/orchestrator.md

@@ -1,5 +1,6 @@
 ---
 roadmapSkill: spec
+model: opus
 ---
 
 You are a **spec orchestrator** — you own a specification effort and deliver a spec a planner turns into tasks with zero guessing. You reach that through three gated stages: **SHAPE** (clarify intent with the human until the goal is unambiguous), **DESIGN** (produce the blueprint), and **REQUIREMENTS** (derive precise, testable requirements from the finished design). This is one of the few kinds where human engagement is load-bearing — Shape is interactive, and the human gates each stage before the next begins. You drive and decide; the human answers questions and signs off the artifact each stage produces.

package/dist/commands/human/queue.js

@@ -8,6 +8,7 @@ import { transition } from '../../core/runtime/lifecycle.js';
 import { appendInbox } from '../../core/feed/inbox.js';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { inbox, scanInbox, parseDeck, deckPath, responsePath, isResolved, atomicWriteJson, ask, launchReview, readJson, display, } from '@crouton-kit/humanloop';
 import { killPane } from './shared.js';
 // ---------------------------------------------------------------------------
@@ -176,8 +177,8 @@ export const humanCancel = defineLeaf({
         return { canceled: true, job_id: jobId };
     },
     render: (r) => r['canceled'] === true
-        ? `<canceled job_id="${r['job_id']}"/>`
-        : `<cancel-noop job_id="${r['job_id']}">${r['reason'] ?? 'nothing to cancel'}</cancel-noop>`,
+        ? `Canceled human interaction ${r['job_id']} — its TUI pane is closed and subscribers were notified no answer is coming.`
+        : `Nothing to cancel for ${r['job_id']} — ${r['reason'] ?? 'nothing to cancel'}.`,
 });
 // ---------------------------------------------------------------------------
 // _run (hidden worker; not listed in branch help)
@@ -243,6 +244,16 @@ export const humanRun = defineLeaf({
                 catch {
                     /* render pane is best-effort; the review itself must not die */
                 }
+                // Dock the render pane BESIDE this worker pane. tmux resolves an
+                // untargeted split-window against the attached client's current window
+                // (which wins over $TMUX_PANE), so the pane can land in whatever window
+                // the user happens to be looking at — away from the editor. move-pane
+                // with explicit src/dst is deterministic: raw source and rendered doc
+                // always sit side by side.
+                const selfPane = process.env['TMUX_PANE'];
+                if (renderPane !== undefined && selfPane !== undefined && selfPane !== '') {
+                    spawnSync('tmux', ['move-pane', '-h', '-s', renderPane, '-t', selfPane], { stdio: 'ignore' });
+                }
                 if (renderPane !== undefined) {
                     const rcPath = join(dir, 'run.json');
                     const cur = readJson(rcPath);

package/dist/commands/memory/__tests__/lint-schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/memory/__tests__/lint-schema.test.js

@@ -0,0 +1,29 @@
+// Bug-regression: guards the hard cut that merged the substrate's `when`/`why`
+// frontmatter pair into the single `when-and-why-to-read` read-routing field.
+// The CTO ruling (taste/why-field-means-why-to-read) requires the migration be
+// a hard cut: an old-shape doc must FAIL at `crtr memory lint`, never be read at
+// runtime. `lintSubstrateSchema` is that enforcement seam — these lock it.
+//
+// Run: node --import tsx/esm --test src/commands/memory/__tests__/lint-schema.test.ts
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { lintSubstrateSchema } from '../lint.js';
+const ROUTING = 'When you are X, this reference should be read because Y';
+test('lint rejects a doc still carrying the retired `when` key', () => {
+    const err = lintSubstrateSchema({ kind: 'reference', when: 'when X' });
+    assert.ok(err !== null, 'old-shape `when` must produce a finding');
+    assert.match(err, /when-and-why-to-read/, 'the message points at the new field');
+});
+test('lint rejects a doc still carrying the retired `why` key', () => {
+    const err = lintSubstrateSchema({ kind: 'reference', why: 'because Y' });
+    assert.ok(err !== null, 'old-shape `why` must produce a finding');
+    assert.match(err, /when-and-why-to-read/, 'the message points at the new field');
+});
+test('lint rejects a substrate doc missing the merged routing field', () => {
+    const err = lintSubstrateSchema({ kind: 'reference' });
+    assert.ok(err !== null, 'a substrate doc must carry when-and-why-to-read');
+    assert.match(err, /when-and-why-to-read/);
+});
+test('lint accepts the merged new-shape frontmatter', () => {
+    assert.equal(lintSubstrateSchema({ kind: 'reference', 'when-and-why-to-read': ROUTING }), null);
+});

package/dist/commands/memory/find.js

@@ -12,8 +12,7 @@ function substrateUnit(d) {
         kind: d.kind,
         scope: d.scope,
         path: d.path,
-        when: d.when,
-        why: d.why,
+        routing: d.whenAndWhyToRead,
         shortForm: d.shortForm,
         loadBody: () => d.body,
     };
@@ -26,10 +25,9 @@ function skillUnit(s) {
         kind: 'skill',
         scope: s.scope,
         path: s.path,
-        // A skill's description plays the when+why role; keywords ride along so the
-        // ranker weighs them too. short_form surfaces the description as the hook.
-        when: [desc, keywords].filter((x) => x).join(' '),
-        why: '',
+        // A skill's description plays the read-routing role; keywords ride along so
+        // the ranker weighs them too. short_form surfaces the description as the hook.
+        routing: [desc, keywords].filter((x) => x).join(' '),
         shortForm: desc,
         loadBody: () => parseFrontmatter(readText(s.path)).body,
     };
@@ -80,12 +78,12 @@ function candidates(kindFilter) {
 export const findLeaf = defineLeaf({
     name: 'find',
     description: 'relevance search across memory documents',
-    whenToUse: 'you do not yet know which document applies and need to discover what is stored — ranks documents by relevance, weighted over name, when, why, and short-form (add --body to also weigh body text). Searches the full scope set regardless of any visibility gate. Use --grep instead when you need an exact regex or literal-string match across document bodies rather than a ranked topic match.',
+    whenToUse: 'you do not yet know which document applies and need to discover what is stored — ranks documents by relevance, weighted over name, the read-routing line, and short-form (add --body to also weigh body text). Searches the full scope set regardless of any visibility gate. Use --grep instead when you need an exact regex or literal-string match across document bodies rather than a ranked topic match.',
     help: {
         name: 'memory find',
-        summary: 'relevance search across memory documents, weighted over name/when/why/short-form (and body with --body)',
+        summary: 'relevance search across memory documents, weighted over name/routing-line/short-form (and body with --body)',
         params: [
-            { kind: 'positional', name: 'query', required: true, constraint: 'With ranked search (default): whitespace-separated terms, matched case-insensitively and weighted over name, when, why, and short-form (plus body with --body); documents matching more/stronger fields rank higher. With --grep: an ECMAScript regex applied to each document body line.' },
+            { kind: 'positional', name: 'query', required: true, constraint: 'With ranked search (default): whitespace-separated terms, matched case-insensitively and weighted over name, the read-routing line, and short-form (plus body with --body); documents matching more/stronger fields rank higher. With --grep: an ECMAScript regex applied to each document body line.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Filter to a single kind. Default: all kinds.' },
             { kind: 'flag', name: 'grep', type: 'bool', required: false, constraint: 'Treat the query as an ECMAScript regex and match it against document bodies, instead of weighted relevance ranking. Mutually exclusive with --body.' },
             { kind: 'flag', name: 'body', type: 'bool', required: false, constraint: 'Also weigh document body text in the relevance ranking (in addition to name/when/why/short-form). Ignored under --grep, which always scans bodies.' },
@@ -134,7 +132,7 @@ export const findLeaf = defineLeaf({
                 follow_up: 'Read a document in full with `crtr memory read <name>`. Drop --grep for a ranked topic search.',
             };
         }
-        // --- ranked mode: weighted relevance over name/when/why/short-form(+body) ---
+        // --- ranked mode: weighted relevance over name/routing-line/short-form(+body) ---
         const terms = query
             .toLowerCase()
             .split(/\s+/)
@@ -144,18 +142,15 @@ export const findLeaf = defineLeaf({
         const hits = [];
         for (const u of units) {
             const nameLc = u.name.toLowerCase();
-            const whenLc = u.when.toLowerCase();
-            const whyLc = u.why.toLowerCase();
+            const routingLc = u.routing.toLowerCase();
             const shortLc = u.shortForm.toLowerCase();
             const bodyLc = weighBody ? u.loadBody().toLowerCase() : null;
             let score = 0;
             for (const term of terms) {
                 if (nameLc.includes(term))
                     score += 10;
-                if (whenLc.includes(term))
+                if (routingLc.includes(term))
                     score += 5;
-                if (whyLc.includes(term))
-                    score += 4;
                 if (shortLc.includes(term))
                     score += 3;
                 if (bodyLc !== null && bodyLc.includes(term))

package/dist/commands/memory/lint.d.ts

@@ -1 +1,8 @@
+/** Schema checks for a doc living in a substrate memory dir: a memory store
+ *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring
+ *  error here (elsewhere it just means "not a substrate doc"). Rung and gate
+ *  values are checked RAW — the runtime parser silently falls back to kind
+ *  defaults / inert gates, which is exactly the silent tolerance this lint
+ *  exists to catch at authoring time. */
+export declare function lintSubstrateSchema(fm: Record<string, unknown> | null): string | null;
 export declare const lintLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/lint.js

@@ -24,12 +24,21 @@ const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
  *  values are checked RAW — the runtime parser silently falls back to kind
  *  defaults / inert gates, which is exactly the silent tolerance this lint
  *  exists to catch at authoring time. */
-function lintSubstrateSchema(fm) {
+export function lintSubstrateSchema(fm) {
     if (fm === null)
         return 'missing frontmatter: a memory store doc requires `kind: skill|reference|preference`';
     if (!isDocKind(fm.kind)) {
         return `invalid kind: ${JSON.stringify(fm.kind)} (expected skill|reference|preference)`;
     }
+    // The retired `when`/`why` pair was merged into one read-routing field. The
+    // hard cut is enforced HERE: an old-shape doc must fail, never be silently
+    // read at runtime.
+    if ('when' in fm || 'why' in fm) {
+        return 'retired `when`/`why` keys: merge them into one `when-and-why-to-read` line — "When <circumstance>, this <kind> should be read <because <payoff>>."';
+    }
+    if (typeof fm['when-and-why-to-read'] !== 'string' || fm['when-and-why-to-read'].trim() === '') {
+        return 'missing `when-and-why-to-read`: one read-routing line — "When <circumstance>, this <kind> should be read <because <payoff>>."';
+    }
     for (const field of RUNG_FIELDS) {
         const v = fm[field];
         if (v !== undefined && (typeof v !== 'string' || !VALID_RUNGS.includes(v))) {

package/dist/commands/memory/shared.js

@@ -91,8 +91,7 @@ export function coerceAppliesTo(raw) {
 // first in this order; any preserved-on-update extras append after.
 const FRONTMATTER_ORDER = [
     'kind',
-    'when',
-    'why',
+    'when-and-why-to-read',
     'short-form',
     'system-prompt-visibility',
     'file-read-visibility',

package/dist/commands/memory/write.js

@@ -13,8 +13,7 @@ export const writeLeaf = defineLeaf({
         params: [
             { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived identity (e.g. `topic` or `area/topic`) → memory/<name>.md at the resolved scope. Updated in place if it already exists, otherwise created.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: true, constraint: 'Document kind.' },
-            { kind: 'flag', name: 'when', type: 'string', required: false, constraint: 'Frontmatter whenText — a short string describing when this document should be read.' },
-            { kind: 'flag', name: 'why', type: 'string', required: false, constraint: 'Frontmatter whyText — a short string describing why this document matters.' },
+            { kind: 'flag', name: 'when-and-why-to-read', type: 'string', required: false, constraint: 'The read-routing line, authored as ONE sentence: "When <circumstance>, this <kind> should be read <because <payoff>>." It states WHEN to read this doc and WHY the read is worth it — read-routing, NEVER a justification of why the content should be obeyed. Rendered verbatim as the preview. Required when creating.' },
             { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form — a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
             { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help.' },
             { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document surfaces when it is read off disk.' },
@@ -44,11 +43,10 @@ export const writeLeaf = defineLeaf({
         const { scope, memoryDir } = resolveWriteTarget(scopeArg);
         const path = memoryFilePath(memoryDir, name);
         const created = !pathExists(path);
-        // CREATE requires the two prose fields that compose the generated preview
-        // routing line — without them every preview renders the degenerate
-        // '", read this <kind>. ."'. UPDATE inherits them from the existing doc.
-        if (created && (input['when'] === undefined || input['why'] === undefined)) {
-            throw usage(`creating ${name} requires --when and --why (they compose the preview routing line "{when}, read this ${kind}. {why}.")`);
+        // CREATE requires the read-routing line that becomes the preview — without
+        // it every preview renders empty. UPDATE inherits it from the existing doc.
+        if (created && input['whenAndWhyToRead'] === undefined) {
+            throw usage(`creating ${name} requires --when-and-why-to-read: one read-routing sentence "When <circumstance>, this ${kind} should be read <because <payoff>>." (rendered verbatim as the preview).`);
         }
         // In-place update: start from the existing frontmatter (preserving fields
         // not passed this time), then overlay the provided ones. Create: start clean.
@@ -62,8 +60,7 @@ export const writeLeaf = defineLeaf({
             if (value !== undefined)
                 frontmatter[key] = value;
         };
-        setIf('when', input['when']);
-        setIf('why', input['why']);
+        setIf('when-and-why-to-read', input['whenAndWhyToRead']);
         setIf('short-form', input['shortForm']);
         setIf('system-prompt-visibility', input['systemPromptVisibility']);
         setIf('file-read-visibility', input['fileReadVisibility']);