@crouton-kit/crouter 0.3.36 → 0.3.38

package/dist/core/substrate/render.js

@@ -1,10 +1,18 @@
 // render.ts — the pure boot-render functions for the document substrate.
 //
 // Two boot targets, one shape per kind: each kind renders as ONE wrapped block —
-// intro prose → a file tree → an update directive. The tree discloses each doc
-// at its effective rung (name → bare entry; preview → a `# read when:` routing
-// line; content → the full body indented beneath the entry); hidden (`none`-rung)
-// docs leak only a `[+N more]` count under their dir, never a name.
+// intro prose → GROUPED content → an update directive. The render is grouped
+// by visibility rung, not interleaved: `content`-rung docs render FIRST as
+// clean prose bodies (verbatim, no tree chrome, no name label — this is what
+// makes content-rung the persona-prose mechanism), in general→specific order;
+// then the `preview`+`name`(+hidden `none`) docs render as ONE catalog tree,
+// each at its own rung (preview → a `# read when:` routing line; name → a bare
+// entry); a `none`-rung doc leaks only into its dir's `[+N more]` count, never
+// a name — EXCEPT a node-local doc, whose contract is "node-local rides into
+// knowledge" unconditionally: renderKnowledgeBlock floors a rung-none
+// node-local doc up to `name` so it still shows its bare name rather than
+// collapsing into a hidden count. Only gate evaluation removes a node-local
+// doc outright.
 //
 //   • the SYSTEM-PROMPT half — `<memory kind="preference">`
 //     (renderPreferencesSection) — the always-present memory-usage guidance plus
@@ -17,11 +25,22 @@
 //     message as a SIBLING of `<crtr-bearings>` (never nested under the context
 //     dir — the catalog spans all scopes and belongs to no one directory).
 //
-// Every doc flows through the same pipeline: MemoryDoc → parseSubstrateDoc →
-// (null-filter non-substrate) → ceiling-capped effective rung → gatePasses →
-// tree placement. INDEX docs render as an explicit `INDEX.md` child line under
-// their dir (teaching the convention); a `none`-rung INDEX still hides its whole
-// subtree (its descendants roll up as hidden counts).
+// The pipeline is explicitly TWO-STEP and must never run in the other order:
+//   1. SELECT WINNERS — MemoryDoc → parseSubstrateDoc → (null-filter
+//      non-substrate) → ceiling-capped effective rung → gatePasses →
+//      first-wins DEDUP by name over the resolver's precedence order (nearest
+//      project > user > builtin). Node-local docs follow the same gate rule,
+//      but the knowledge-block render floors a rung-none node-local doc's
+//      EFFECTIVE rung to `name` — the one rung-floor exemption, scoped to the
+//      node-local store only.
+//   2. RENDER IN DISPLAY ORDER — split winners into content vs. the rest;
+//      order content general→specific (builtin, user, project outermost→
+//      nearest, node-local last) then by tree position then filename; place
+//      the rest into the catalog tree (position-ordered, as before).
+//   Sorting into display order BEFORE step 1's dedup would let a
+//   later-in-display-order builtin doc's array position mask a project/user
+//   override — dedup precedence and display order are deliberately different
+//   orderings and must not be conflated.
 //
 // Pure + defensive: reads the resolver, canvas-db (subject assembly), and the
 // node-local memory dir; performs no writes and no side effects. A single
@@ -29,28 +48,47 @@
 // (parseSubstrateDoc returns null for a non-substrate doc; per-file node-local
 // loads are wrapped), and tree construction is pure string work.
 import { relative, sep } from 'node:path';
-import { listAllMemoryDocs } from '../memory-resolver.js';
+import { listAllMemoryDocs, resolveMemoryDoc } from '../memory-resolver.js';
+import { subKindsAvailableTo } from '../config.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { memoryDir } from '../runtime/memory.js';
-import { assembleNodeSubject, buildCeilingIndex, effectiveRung, gatePasses, indexDirOf, isIndexName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, rungRank, } from './index.js';
+import { projectScopeRoots } from '../scope.js';
+import { assembleNodeSubject, buildCeilingIndex, effectiveRung, gatePasses, indexDirOf, isIndexName, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, rungRank, } from './index.js';
 import { cachedNodeSubject, cachedSubstrateDocs } from './session-cache.js';
 // ---------------------------------------------------------------------------
-// The shared per-doc pipeline.
+// Step 1 — winner selection (ceiling + gate + first-wins dedup).
 // ---------------------------------------------------------------------------
-/** The resolver-provided substrate docs of one `kind`, eligible at boot for
- *  `subject`: parsed (non-substrate docs null-filtered), ceiling-capped, and
- *  gate-passed — at their EFFECTIVE system-prompt rung, INCLUDING `none`-rung
- *  docs (the tree counts them into `[+N more]`). Resolver = user + project +
- *  builtin scopes (precedence-ordered); node-local is loaded separately (see
- *  nodeLocalDocs). Uses the per-session cache so the full corpus is scanned +
- *  parsed at most once per session across the boot-render calls.
+/** First-wins dedup by (already-normalized) name, preserving the input's
+ *  precedence order. The array's ORDER is the precedence signal — callers must
+ *  pass docs already ordered highest-precedence-first; this function never
+ *  reorders, only drops later duplicates. */
+function dedupeFirstWins(docs) {
+    const seen = new Set();
+    const out = [];
+    for (const d of docs) {
+        if (seen.has(d.name))
+            continue;
+        seen.add(d.name);
+        out.push(d);
+    }
+    return out;
+}
+/** STEP 1 — the resolver-provided WINNER docs of one `kind`, eligible at boot
+ *  for `subject`: parsed (non-substrate docs null-filtered), ceiling-capped,
+ *  gate-passed, then first-wins DEDUPED by name over the resolver's precedence
+ *  order (nearest project > user > builtin) — at the EFFECTIVE system-prompt
+ *  rung, INCLUDING `none`-rung docs (the tree counts them into `[+N more]`).
+ *  This is winner selection ONLY; display ordering is a separate, later step
+ *  (see renderGrouped) so a builtin doc can never mask a project/user override
+ *  by virtue of sorting first. Uses the per-session cache so the full corpus
+ *  is scanned + parsed at most once per session across the boot-render calls.
  *
  *  Ceilings are computed over the WHOLE corpus (cross-kind) BEFORE the kind
  *  filter, and the effective rung is written back into systemPromptVisibility —
  *  but the doc's NAME is left intact (the tree needs the real `taste/INDEX` path
  *  to place an `INDEX.md` child; renaming INDEX docs to their dir would lose it). */
-function effectiveDocs(subject, kind) {
+function selectWinners(subject, kind) {
     let docs;
     try {
         docs = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
@@ -59,17 +97,95 @@ function effectiveDocs(subject, kind) {
         return [];
     }
     const ceil = buildCeilingIndex(docs);
-    return docs
+    const eligible = docs
         .map((d) => {
         const rung = effectiveRung(d, ceil, 'systemPromptVisibility');
         return rung === d.systemPromptVisibility ? d : { ...d, systemPromptVisibility: rung };
     })
         .filter((d) => d.kind === kind)
-        .filter((d) => gatePasses(d, subject))
-        .sort((a, b) => scopeRank(a.scope) - scopeRank(b.scope) || a.name.localeCompare(b.name));
+        .filter((d) => gatePasses(d, subject));
+    return dedupeFirstWins(eligible);
 }
-function scopeRank(scope) {
-    return scope === 'project' ? 0 : scope === 'user' ? 1 : 2;
+// ---------------------------------------------------------------------------
+// Step 2 — display ordering + grouped render.
+// ---------------------------------------------------------------------------
+/** Content-prose ordering rank: general → specific. builtin=0, user=1,
+ *  profile=2, project ranks start at 3 and climb by root nearness — the
+ *  OUTERMOST ancestor `.crouter/` root ranks lowest (renders first), the
+ *  NEAREST root ranks highest (renders last) — the mirror of the resolver's
+ *  nearest-first dedup precedence. `isNodeLocal` docs rank last of all (the
+ *  most specific, this-node-only store). This is display order ONLY — the
+ *  resolver's REPLACEMENT precedence (first-wins dedup, step 1) is the
+ *  opposite direction for project/profile: project stack > profile > user >
+ *  builtin, nearest project strongest; the two orderings are deliberately
+ *  different (see the module comment). */
+function scopeGeneralityRank(doc, isNodeLocal) {
+    if (isNodeLocal)
+        return 1000;
+    if (doc.scope === 'builtin')
+        return 0;
+    if (doc.scope === 'user')
+        return 1;
+    if (doc.scope === 'profile')
+        return 2;
+    const roots = projectScopeRoots(); // nearest-first
+    if (roots.length === 0)
+        return 3;
+    const nearFirstIdx = roots.findIndex((root) => doc.path.startsWith(root + sep));
+    const idx = nearFirstIdx === -1 ? 0 : nearFirstIdx;
+    return 3 + (roots.length - 1 - idx); // outermost (largest idx) -> smallest rank
+}
+/** The doc's RAW physical path segments (numeric prefix intact), recovered
+ *  from its absolute `path` using its (already-normalized) `name`'s segment
+ *  COUNT — normalization strips a prefix from a segment but never merges or
+ *  drops a segment, so the last N components of `path` are always the doc's
+ *  physical segments. This is what lets `tree position` sort respect an
+ *  author's `NN-` ordering pin even though the pin is invisible in `name`. */
+function physicalSegments(doc) {
+    const n = doc.name.split('/').length;
+    const raw = doc.path.split(sep).slice(-n);
+    if (raw.length > 0)
+        raw[raw.length - 1] = raw[raw.length - 1].replace(/\.md$/i, '');
+    return raw;
+}
+/** "Tree position" comparator for content-prose ordering within a store:
+ *  compares two docs' RAW physical segments element-by-element (a shallower
+ *  path sorts before a path nested under it at the first differing segment). */
+function compareTreePosition(a, b) {
+    const as = physicalSegments(a);
+    const bs = physicalSegments(b);
+    const len = Math.min(as.length, bs.length);
+    for (let i = 0; i < len; i++) {
+        const c = as[i].localeCompare(bs[i]);
+        if (c !== 0)
+            return c;
+    }
+    return as.length - bs.length;
+}
+/** STEP 2 — split deduped `winners` by rung and render each group in its
+ *  display order: `content` docs first, as clean prose (general→specific,
+ *  then tree position, then filename — no tree chrome, no name label); every
+ *  other winner (preview/name/hidden-none) folds into ONE catalog tree exactly
+ *  as before. `nodeLocalSet` marks which winners came from the node-local
+ *  store (ranked most-specific in content ordering); omit it for a pure
+ *  resolver render. */
+function renderGrouped(winners, rootLabel, nodeLocalSet = new Set()) {
+    const content = [];
+    const rest = [];
+    for (const d of winners) {
+        if (d.systemPromptVisibility === 'content')
+            content.push(d);
+        else
+            rest.push(d);
+    }
+    content.sort((a, b) => scopeGeneralityRank(a, nodeLocalSet.has(a)) - scopeGeneralityRank(b, nodeLocalSet.has(b)) ||
+        compareTreePosition(a, b) ||
+        a.name.localeCompare(b.name));
+    const contentProse = content
+        .map((d) => d.body.trim())
+        .filter((b) => b !== '')
+        .join('\n\n');
+    return { contentProse, tree: buildTree(rest, rootLabel), contentDocs: content };
 }
 /** The node-local memory docs eligible at boot. Node-local memory lives in the
  *  canvas home (`nodes/<id>/context/memory/`) and is OUTSIDE the scope resolver,
@@ -79,18 +195,21 @@ function scopeRank(scope) {
  *  Returned across ALL kinds — node-local is the catch-all this-node store and
  *  rides into the knowledge block.
  *
- *  IMPORTANT: node-local docs are NOT filtered or capped by rung. Their contract
- *  is "node-local rides into knowledge" without qualification, so a `none`-rung
- *  node-local doc must still surface — the caller floors it to `name` so it
- *  renders its name (never collapsing into a hidden count). Only gate evaluation
- *  removes a node-local doc from the block. */
+ *  Node-local docs follow the same GATE rule as every other store — gate
+ *  evaluation is the only thing that removes a doc here. Rung is different:
+ *  node-local's contract is "node-local rides into knowledge" unconditionally,
+ *  so a `none`-rung node-local doc is retained AT its parsed rung by this
+ *  function (never rewritten here) — it is the caller (renderKnowledgeBlock)
+ *  that floors a rung-none node-local doc up to `name` so it still shows its
+ *  bare name instead of collapsing into a `[+N more]` count. */
 function nodeLocalDocs(nodeId, subject) {
     const dir = memoryDir(nodeId);
     if (!pathExists(dir))
         return [];
     const out = [];
     for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
-        const name = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+        const raw = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+        const name = normalizeDocName(raw);
         if (!name)
             continue;
         try {
@@ -108,7 +227,6 @@ function nodeLocalDocs(nodeId, subject) {
             continue;
         }
     }
-    // Gate-filter only: rung is NOT filtered (see comment above).
     return out.filter((d) => gatePasses(d, subject));
 }
 function newDir(path) {
@@ -240,14 +358,15 @@ function renderChildren(dir, childPrefix, lines) {
         }
     });
 }
-/** Build the file tree for a kind's eligible docs, headed by `rootLabel`.
- *  Returns '' when there are no docs at all (the empty-tree contract).
+/** Build the catalog tree for a set of already-deduped, non-content winners,
+ *  headed by `rootLabel`. Returns '' when there are no docs at all (the
+ *  empty-tree contract).
  *
- *  `docs` arrives in precedence order (project > user > builtin, node-local last)
- *  WITHOUT cross-scope dedup — `listAllMemoryDocs` returns every scope's hit for
- *  a path-derived name and leaves first-wins dedup to the caller. So a name
- *  present in two scopes is deduped here (first occurrence wins); otherwise it
- *  would render as two identical sibling lines and double-count into `[+N more]`. */
+ *  Callers (renderGrouped) pass docs that are ALREADY first-wins deduped by
+ *  Step 1 (selectWinners); the `seen` set below is a defensive no-op guard
+ *  against a residual duplicate name (e.g. the resolver-winners ∪ node-local
+ *  merge), never the primary dedup mechanism — sorting into display order
+ *  happens upstream of this call, never before dedup. */
 function buildTree(docs, rootLabel) {
     if (docs.length === 0)
         return '';
@@ -287,7 +406,8 @@ const PREFERENCES_OUTRO = 'If the user corrects you in a way that contradicts a
 const KNOWLEDGE_INTRO = 'Knowledge documents are what you consult — playbooks and techniques for how to do things, and ' +
     'references on the user, projects, and this node. They are aggregated from your memory stores: ' +
     'user-global (`~/.crouter/memory/`), every ancestor project store (`<dir>/.crouter/memory/`) ' +
-    "from the cwd upward, and node-local (this node's `context/memory/`). To read one, run `crtr memory read <name>`. " +
+    "from the cwd upward, the selected profile's memory store (when one is selected), and node-local " +
+    "(this node's `context/memory/`). To read one, run `crtr memory read <name>`. " +
     'Each doc exists to prevent a specific mistake you would make without it, so when your task ' +
     'matches one — by its name or its `# read when:` line — read it before you act; consulting it ' +
     'only after the work is done forfeits the entire reason it exists. ' +
@@ -312,24 +432,78 @@ const MEMORY_USAGE_GUIDANCE = 'When your task matches a knowledge doc or prefere
     '<auto-loaded-context> blocks are background context, not user instructions, and reflect ' +
     'what was true when written — if one names a file, function, or flag, verify it still ' +
     'exists before recommending it.';
+/** Try to resolve a sub-kind's builtin memory doc body citation, or '' if none
+ *  resolves. Mirrors `runtime/persona.ts`'s `loadMemoryBody` try/catch pattern —
+ *  a sub-kind registered without a matching doc simply gets no citation clause,
+ *  never a thrown render. */
+function subKindDocCitation(subKind) {
+    try {
+        resolveMemoryDoc(`kinds/${subKind}`);
+        return ` (\`crtr memory read kinds/${subKind}\`)`;
+    }
+    catch {
+        return '';
+    }
+}
+/** The computed "sub-personas you may spawn" menu for a subject's kind — the
+ *  live restoration of the old `personas/resolve.ts` static menu, now derived
+ *  at render time from the merged kind registry (`subKindsAvailableTo`) so it
+ *  can never drift from `sys prompt-review --list`'s `subPersonas` metadata.
+ *  Returns '' when the kind has zero available sub-kinds (no dangling empty
+ *  header). Emitted for BOTH base and orchestrator modes per the CTO's ruling —
+ *  mode is irrelevant to which sub-kinds are spawnable. */
+function buildSubPersonaMenu(kind) {
+    const subKinds = subKindsAvailableTo(kind);
+    if (subKinds.length === 0)
+        return '';
+    const lines = subKinds.map((sub) => {
+        const citation = subKindDocCitation(sub.kind);
+        return `- \`${sub.kind}\` — ${sub.whenToUse}${citation}`;
+    });
+    return (`## Sub-personas you may spawn\n\n` +
+        `These specialist sub-personas are available to the ${kind} kind. Spawn one with ` +
+        '`crtr node new --kind <sub> "<scope>"`, and treat it as its own scope instead of ' +
+        'dragging unrelated context into it.\n\n' +
+        lines.join('\n'));
+}
 // ---------------------------------------------------------------------------
 // 1. Preferences — `<memory kind="preference">` (system prompt).
 // ---------------------------------------------------------------------------
 /** The system-prompt memory block: the always-present memory-usage guidance,
- *  then (when any are eligible) the `kind: preference` docs in one tree at their
- *  effective rung (the preference default rung is `preview` → the routing line).
- *  ALWAYS returns a non-empty `<memory kind="preference">` block — the guidance
- *  frame is unconditional, so the system-prompt splice is never empty even when
- *  no preference is eligible. */
-export function renderPreferencesSection(nodeId) {
+ *  then (when any are eligible) the `kind: preference` docs GROUPED by rung —
+ *  content-rung docs first as clean prose (general→specific), then the
+ *  preview/name catalog tree. ALWAYS returns a non-empty `<memory
+ *  kind="preference">` block — the guidance frame is unconditional, so the
+ *  system-prompt splice is never empty even when no preference is eligible. */
+function buildPreferencesBlock(subject) {
     let body = MEMORY_USAGE_GUIDANCE;
-    const subject = cachedNodeSubject(nodeId, assembleNodeSubject);
+    let contentDocs = [];
+    let tree = '';
     if (subject !== null) {
-        const tree = buildTree(effectiveDocs(subject, 'preference'), 'preferences');
-        if (tree !== '')
-            body += `\n\n${PREFERENCES_INTRO}\n\n${tree}\n\n${PREFERENCES_OUTRO}`;
+        const winners = selectWinners(subject, 'preference');
+        const grouped = renderGrouped(winners, 'preferences');
+        contentDocs = grouped.contentDocs;
+        tree = grouped.tree;
+        const subPersonaMenu = buildSubPersonaMenu(subject.kind);
+        if (grouped.contentProse !== '' || grouped.tree !== '' || subPersonaMenu !== '') {
+            body += `\n\n${PREFERENCES_INTRO}`;
+            if (grouped.contentProse !== '')
+                body += `\n\n${grouped.contentProse}`;
+            if (subPersonaMenu !== '')
+                body += `\n\n${subPersonaMenu}`;
+            if (grouped.tree !== '')
+                body += `\n\n${grouped.tree}`;
+            body += `\n\n${PREFERENCES_OUTRO}`;
+        }
     }
-    return `<memory kind="preference">\n${body}\n</memory>`;
+    return { block: `<memory kind="preference">\n${body}\n</memory>`, contentDocs, tree };
+}
+export function renderPreferencesSection(nodeId) {
+    const subject = cachedNodeSubject(nodeId, assembleNodeSubject);
+    return buildPreferencesBlock(subject).block;
+}
+export function renderPreferencesForSubject(subject) {
+    return buildPreferencesBlock(subject);
 }
 // ---------------------------------------------------------------------------
 // 2. Knowledge — `<memory kind="knowledge">` (the first-message bearings).
@@ -337,20 +511,33 @@ export function renderPreferencesSection(nodeId) {
 /** The `<memory kind="knowledge">` block embedded in the session_start bearings
  *  message (bearings.ts pushes it as a SIBLING of `<crtr-bearings>`, or drops it
  *  when ''). The consultable catalog: every eligible `kind: knowledge` resolver
- *  doc at its effective rung (most surface only as `[+N more]` counts unless
- *  author-promoted) PLUS the node-local memory docs (any kind), the latter
- *  floored to `name` so a `none`-rung node-local doc still shows its name rather
- *  than collapsing into a count. Procedural guidance and factual references both
- *  live here as `knowledge`. Returns '' when nothing is eligible. */
+ *  doc PLUS the node-local memory docs (any kind) — resolver docs win
+ *  first-wins dedup over a same-named node-local doc. GROUPED by rung exactly
+ *  like the preference block: content prose first (general→specific,
+ *  node-local last), then the preview/name catalog tree. Node-local docs are
+ *  floored HERE — a rung-none node-local doc's effective rung is bumped to
+ *  `name` before grouping, so it still surfaces as a bare-name tree entry
+ *  rather than collapsing into a `[+N more]` count (its body still never
+ *  renders: floored docs never reach the `content` rung). Procedural guidance
+ *  and factual references both live here as `knowledge`. Returns '' when
+ *  nothing is eligible. */
 export function renderKnowledgeBlock(nodeId) {
     const subject = cachedNodeSubject(nodeId, assembleNodeSubject);
     if (subject === null)
         return '';
-    const nodeLocal = nodeLocalDocs(nodeId, subject).map((d) => rungRank(d.systemPromptVisibility) >= rungRank('name')
-        ? d
-        : { ...d, systemPromptVisibility: 'name' });
-    const tree = buildTree([...effectiveDocs(subject, 'knowledge'), ...nodeLocal], 'knowledge');
-    if (tree === '')
+    const nodeLocal = nodeLocalDocs(nodeId, subject).map((d) => rungRank(d.systemPromptVisibility) >= rungRank('name') ? d : { ...d, systemPromptVisibility: 'name' });
+    const nodeLocalSet = new Set(nodeLocal);
+    // Resolver winners first: first-wins dedup keeps the resolver's copy over a
+    // same-named node-local doc, matching the original precedence.
+    const winners = dedupeFirstWins([...selectWinners(subject, 'knowledge'), ...nodeLocal]);
+    const { contentProse, tree } = renderGrouped(winners, 'knowledge', nodeLocalSet);
+    if (contentProse === '' && tree === '')
         return '';
-    return `<memory kind="knowledge">\n${KNOWLEDGE_INTRO}\n\n${tree}\n\n${KNOWLEDGE_OUTRO}\n</memory>`;
+    let out = KNOWLEDGE_INTRO;
+    if (contentProse !== '')
+        out += `\n\n${contentProse}`;
+    if (tree !== '')
+        out += `\n\n${tree}`;
+    out += `\n\n${KNOWLEDGE_OUTRO}`;
+    return `<memory kind="knowledge">\n${out}\n</memory>`;
 }

package/dist/core/substrate/schema.d.ts

@@ -1,5 +1,4 @@
-import type { Scope } from '../../types.js';
-import type { MemoryDoc } from '../memory-resolver.js';
+import type { MemoryDoc, MemoryScope } from '../memory-resolver.js';
 export declare const KINDS: readonly ["knowledge", "preference"];
 export type DocKind = (typeof KINDS)[number];
 /** Is `v` one of the two valid document kinds? */
@@ -12,6 +11,15 @@ export declare function rungRank(r: Rung): number;
  *  `rungAtLeast(doc.systemPromptVisibility, 'name')` ⇒ "shows at boot at all". */
 export declare function rungAtLeast(r: Rung, min: Rung): boolean;
 export declare const FALLBACK_RUNG: Rung;
+/** Strip an optional `NN-` ordering prefix from ONE path segment (file or
+ *  directory display name). `00-runtime-base` -> `runtime-base`; `spine` (no
+ *  prefix) is unchanged. */
+export declare function normalizeNameSegment(segment: string): string;
+/** Normalize a full slash-separated path-derived doc name by stripping the
+ *  optional numeric prefix from EVERY segment: `01-spine/00-has-manager` ->
+ *  `spine/has-manager`. This is the identity a doc displays, dedups, and
+ *  resolves under — distinct from its physical path, which keeps the prefix. */
+export declare function normalizeDocName(name: string): string;
 /** A gate predicate tree, evaluated by predicate.ts (`evalCondition`) against
  *  the node-config subject. Typed loosely on purpose — the matcher engine owns
  *  validation; structurally it is a field→matcher map with optional
@@ -58,7 +66,7 @@ export interface SubstrateDoc extends SubstrateSchema {
     /** Path-derived identity, e.g. `taste/document-substrate` (resolver-supplied). */
     name: string;
     /** The scope this doc resolved from. */
-    scope: Scope;
+    scope: MemoryScope;
     /** Absolute path to the source .md. */
     path: string;
     /** Document body, frontmatter stripped. */

package/dist/core/substrate/schema.js

@@ -44,6 +44,31 @@ export function rungAtLeast(r, min) {
 // ---------------------------------------------------------------------------
 export const FALLBACK_RUNG = 'none';
 // ---------------------------------------------------------------------------
+// Display-name normalization — the optional `NN-` ordering pin. A doc's
+// physical path may carry a two-digit numeric prefix on a file or directory
+// segment (`00-runtime-base.md`, `01-spine/`) purely to pin structural order
+// against natural sort (design: builtin prompt corpus, used sparingly). The
+// prefix is NEVER part of the doc's identity: every identity-facing surface —
+// MemoryDoc.name, direct lookup, leaf fallback, `crtr memory read`/`list`,
+// prompt render, on-read display — derives from the NORMALIZED segments, so
+// `00-runtime-base` displays/dedups/resolves as `runtime-base`. Only the
+// physical path keeps the prefix.
+// ---------------------------------------------------------------------------
+const NUMERIC_PREFIX_RE = /^\d{2}-/;
+/** Strip an optional `NN-` ordering prefix from ONE path segment (file or
+ *  directory display name). `00-runtime-base` -> `runtime-base`; `spine` (no
+ *  prefix) is unchanged. */
+export function normalizeNameSegment(segment) {
+    return segment.replace(NUMERIC_PREFIX_RE, '');
+}
+/** Normalize a full slash-separated path-derived doc name by stripping the
+ *  optional numeric prefix from EVERY segment: `01-spine/00-has-manager` ->
+ *  `spine/has-manager`. This is the identity a doc displays, dedups, and
+ *  resolves under — distinct from its physical path, which keeps the prefix. */
+export function normalizeDocName(name) {
+    return name.split('/').map(normalizeNameSegment).join('/');
+}
+// ---------------------------------------------------------------------------
 // Parse / validate.
 // ---------------------------------------------------------------------------
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the

package/dist/core/substrate/subject.d.ts

@@ -22,6 +22,12 @@ export interface NodeConfigSubject {
          *  root itself is 0; a direct child of the root is 1; etc. */
         depth: number;
     };
+    /** DERIVED: `meta.profile_id` resolved to its manifest's mutable `name` (NOT
+     *  the stable directory id — gate authors write `gate: {profile: <name>}`).
+     *  null for a root/no-profile node, and null (never throwing) when the
+     *  profile has been deleted or its manifest is unreadable — this is a HOT,
+     *  every-doc-render path and must never brick boot/on-read gating. */
+    profile: string | null;
 }
 /** The scope a cwd resolves into: `project` when scope.ts finds a
  *  nearest-ancestor `.crouter/` at/above it, else `user`. Reuses the existing
@@ -35,7 +41,14 @@ export declare function scopeForCwd(cwd: string): 'user' | 'project';
  *  root). The root is depth 0. Cycle-guarded (parents must not cycle, but never
  *  loop forever) — mirrors `rootOfSpine` in runtime/placement.ts. */
 export declare function spineDepth(nodeId: string): number;
-/** Assemble the node-config subject for `nodeId` from its `NodeMeta` + the two
+/** Resolve `profile_id` to the manifest's mutable `name` for the gate subject.
+ *  NEVER throws: a missing/deleted profile resolves to `null` silently (the
+ *  ordinary lifecycle of a node whose profile was deleted out from under it);
+ *  any OTHER failure (e.g. an unreadable/corrupt manifest slipping past
+ *  `loadProfileManifest`'s own tolerance) is logged and still resolves to
+ *  `null` rather than throwing — this runs on every gated-doc render. */
+export declare function profileNameFor(profileId: string | null | undefined): string | null;
+/** Assemble the node-config subject for `nodeId` from its `NodeMeta` + the
  *  derived fields. Returns `null` when the node has no canvas-db row (an
- *  unknown id). Pure aside from the canvas-db reads. */
+ *  unknown id). Pure aside from the canvas-db + profile-manifest reads. */
 export declare function assembleNodeSubject(nodeId: string): NodeConfigSubject | null;

package/dist/core/substrate/subject.js

@@ -6,6 +6,8 @@
 // a thin, pure assembler.
 import { getNode, getRow } from '../canvas/index.js';
 import { projectScopeRoot } from '../scope.js';
+import { loadProfileManifest } from '../profiles/manifest.js';
+import { CrtrError } from '../errors.js';
 /** The scope a cwd resolves into: `project` when scope.ts finds a
  *  nearest-ancestor `.crouter/` at/above it, else `user`. Reuses the existing
  *  resolver (`projectScopeRoot`). NOTE: `findProjectScopeRoot` is process-cached
@@ -35,9 +37,28 @@ export function spineDepth(nodeId) {
     }
     return hops;
 }
-/** Assemble the node-config subject for `nodeId` from its `NodeMeta` + the two
+/** Resolve `profile_id` to the manifest's mutable `name` for the gate subject.
+ *  NEVER throws: a missing/deleted profile resolves to `null` silently (the
+ *  ordinary lifecycle of a node whose profile was deleted out from under it);
+ *  any OTHER failure (e.g. an unreadable/corrupt manifest slipping past
+ *  `loadProfileManifest`'s own tolerance) is logged and still resolves to
+ *  `null` rather than throwing — this runs on every gated-doc render. */
+export function profileNameFor(profileId) {
+    if (profileId === undefined || profileId === null || profileId === '')
+        return null;
+    try {
+        return loadProfileManifest(profileId).manifest.name;
+    }
+    catch (err) {
+        if (err instanceof CrtrError && err.code === 'not_found')
+            return null;
+        console.warn(`[subject] profile "${profileId}" failed to resolve for node subject assembly: ${err.message}`);
+        return null;
+    }
+}
+/** Assemble the node-config subject for `nodeId` from its `NodeMeta` + the
  *  derived fields. Returns `null` when the node has no canvas-db row (an
- *  unknown id). Pure aside from the canvas-db reads. */
+ *  unknown id). Pure aside from the canvas-db + profile-manifest reads. */
 export function assembleNodeSubject(nodeId) {
     const meta = getNode(nodeId);
     if (meta === null)
@@ -50,5 +71,6 @@ export function assembleNodeSubject(nodeId) {
         cwd: meta.cwd,
         scope: scopeForCwd(meta.cwd),
         orchestration: { depth: spineDepth(nodeId) },
+        profile: profileNameFor(meta.profile_id),
     };
 }

package/dist/daemon/crtrd-cli.js

@@ -1,4 +1,4 @@
-// crtrd entry point — spawned detached by `crtr canvas daemon start` and by bin/crtrd.
+// crtrd entry point — spawned detached by `crtr sys daemon start` and by bin/crtrd.
 // Calls runDaemon() and never returns (the loop drives via setTimeout).
 import { runDaemon } from './crtrd.js';
 runDaemon();

package/dist/daemon/crtrd.d.ts

@@ -19,6 +19,30 @@ export declare const YIELD_STALL_GRACE_MS: number;
  *  after running `node yield` mid-turn, and a working engine must never be
  *  killed), and the state has persisted past YIELD_STALL_GRACE_MS. */
 export declare function yieldStallVerdict(piPidAlive: boolean | null, intent: NodeRow['intent'], busy: boolean, stalledFor: number | null): 'leave' | 'pending' | 'kill';
+export declare const WEDGE_QUIET_MS: number;
+export declare const WEDGE_CPU_MAX_PERCENT = 2;
+export type WedgeVerdict = 'leave' | 'pending' | 'wedged';
+/** Pure wedge decision — mirrors livenessVerdict/yieldStallVerdict: a total
+ *  function of the observed signals, no clock or process access of its own.
+ *  `busy` false — the turn already ended (however it routed) — is never a
+ *  wedge, regardless of how stale the marker looks. `quietForMs` null means
+ *  the heartbeat marker couldn't be read (treated as “not enough evidence”, not
+ *  “wedged”). `cpuPercent` null (sample failed/unavailable) or above the
+ *  ceiling — EITHER keeps the verdict at 'pending' (keep watching next tick)
+ *  rather than firing on an unconfirmed or contradicted signal. */
+export declare function wedgeVerdict(input: {
+    busy: boolean;
+    quietForMs: number | null;
+    cpuPercent: number | null;
+}): WedgeVerdict;
+/** Pure: sum CPU% across a process's entire tree (itself + every descendant).
+ *  Parses `ps -ax -o pid=,ppid=,pcpu=` output, builds a ppid→children map, and
+ *  DFS's from `rootPid` collecting root + all descendants; malformed/blank
+ *  lines are skipped. Returns `null` if `rootPid` never appears in the output
+ *  (can't measure at all — treated as UNKNOWN by wedgeVerdict, never as
+ *  “low”) or the output has no parsable rows. Exported for direct unit testing
+ *  — no process access of its own, mirroring wedgeVerdict's purity. */
+export declare function sumTreeCpu(psOutput: string, rootPid: number): number | null;
 export type LivenessVerdict = 'leave' | 'pending' | 'revive';
 /** Decide what to do with a node whose engine pid is DEAD, from how long it's
  *  been dead. Pure — the time/revive side effects live in handleNodeLiveness;