session-orchestrator 5.11.0 → 5.12.0

package/scripts/lib/state-md/idle-reset.mjs

@@ -0,0 +1,239 @@
+/**
+ * Idle Reset for STATE.md (issue #1560) — the code form of session-start
+ * Phase 1.5 § "Idle Reset" (skills/session-start/references/phase-1-5-session-continuity.md).
+ *
+ * Until #1560 the reset existed only as prose and every coordinator rewrote
+ * STATE.md by hand. Its Rule 6 deleted the five recommendation keys from the
+ * frontmatter, which is exactly what Phase 7.5's `buildLiveSignals()` reads —
+ * so after every clean `/close` the Mode-Selector saw no recommendation and
+ * fell back to `feature` at confidence 0. The keys now STAY in the frontmatter:
+ * they are the session-to-session handoff, and session-end Phase 3.7a (their
+ * sole writer) overwrites them at the next close.
+ *
+ * Deliberately NOT re-exported from `scripts/lib/state-md.mjs`: that barrel is
+ * part of the hook import closure (`hooks/_lib/hook-import-set.json`), and no
+ * hook needs the reset. The CLI `scripts/state-md-idle-reset.mjs` imports this
+ * module directly.
+ */
+
+import { parseStateMd, serializeStateMd } from './yaml-parser.mjs';
+import { existsSync } from 'node:fs';
+import { resolveStateMdPath, updateFrontmatterFields, writeStateMd } from './frontmatter-mutators.mjs';
+import { parseRecommendations } from './recommendations.mjs';
+
+/** Rule 7: the drift-baseline keys that must not survive into session N+1. */
+const SCOPE_BASELINE_KEYS = [
+  'scope-baseline-intent',
+  'scope-baseline-owner-boundary',
+  'scope-baseline-planned-files',
+  'scope-baseline-session',
+  'scope-baseline-frozen-at',
+];
+
+/** A level-2 heading (`## X`), never a deeper one (`### X`). */
+const H2_RE = /^##(?!#)\s/;
+
+/** Rule 6: heading of the human-readable recommendations copy. */
+const RECOMMENDATIONS_HEADING = '### Recommendations (archived from v1.1 frontmatter)';
+
+/**
+ * Splits a STATE.md body into the text before the first level-2 heading and
+ * one record per level-2 section. Every record keeps its raw lines (heading
+ * included, up to the next level-2 heading), so re-joining an untouched
+ * section is byte-identical.
+ *
+ * KNOWN CEILING: a `## ` line inside a fenced code block is read as a heading,
+ * the same limitation every helper in body-sections.mjs shares. No STATE.md
+ * section observed so far carries fenced code.
+ *
+ * @param {string} body
+ * @returns {{preamble: string[], sections: Array<{heading: string, lines: string[]}>}}
+ */
+function splitSections(body) {
+  const preamble = [];
+  const sections = [];
+  for (const line of body.split('\n')) {
+    if (H2_RE.test(line)) sections.push({ heading: line, lines: [line] });
+    else if (sections.length === 0) preamble.push(line);
+    else sections[sections.length - 1].lines.push(line);
+  }
+  return { preamble, sections };
+}
+
+/** @param {string} heading @param {string} title */
+function isSection(heading, title) {
+  // The title must END there (or open a parenthesis): `## Wave History Archive`
+  // is a different section.
+  return new RegExp(`^##\\s+${title}(?:\\s*\\(|\\s*$)`).test(heading);
+}
+
+/** Drops leading and trailing blank lines. */
+function trimBlankLines(lines) {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && lines[start].trim() === '') start++;
+  while (end > start && lines[end - 1].trim() === '') end--;
+  return lines.slice(start, end);
+}
+
+/** @param {number} x  a ratio in 0..1 */
+function pct(x) {
+  return `${Math.round(x * 100)}%`;
+}
+
+/**
+ * Rule 6: the human-readable copy of the recommendation fields. Null fields
+ * are omitted; `null` overall when there is nothing to show.
+ *
+ * @param {object} frontmatter
+ * @returns {string|null}
+ */
+function renderRecommendationsBlock(frontmatter) {
+  const rec = parseRecommendations(frontmatter);
+  if (rec === null) return null;
+  const bullets = [];
+  if (rec.mode !== null) bullets.push(`- **Recommended mode:** ${rec.mode}`);
+  if (rec.rationale !== null) bullets.push(`- **Rationale:** ${rec.rationale}`);
+  if (rec.completionRate !== null) bullets.push(`- **Completion rate:** ${pct(rec.completionRate)}`);
+  if (rec.carryoverRatio !== null) bullets.push(`- **Carryover ratio:** ${pct(rec.carryoverRatio)}`);
+  if (rec.priorities !== null) {
+    const list = rec.priorities.length > 0 ? rec.priorities.map((id) => `#${id}`).join(', ') : 'none';
+    bullets.push(`- **Top priorities:** ${list}`);
+  }
+  if (bullets.length === 0) return null;
+  return [RECOMMENDATIONS_HEADING, ...bullets].join('\n');
+}
+
+/**
+ * Removes one `### <heading>` subsection (up to the next `### ` or `## ` line).
+ *
+ * @param {string[]} lines
+ * @param {string} heading  the full `### …` line
+ * @returns {string[]}
+ */
+function dropSubsection(lines, heading) {
+  const out = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (line.trimEnd() === heading) skipping = true;
+    else if (skipping && /^#{2,3}\s/.test(line)) skipping = false;
+    if (!skipping) out.push(line);
+  }
+  return out;
+}
+
+/**
+ * Resets a `status: completed` STATE.md to idle (Phase 1.5 § Idle Reset,
+ * Rules 1-7). Pure: string in, result out, no file I/O.
+ *
+ * 1. `status: idle`. 2. `current-wave: 0`. 3. Every `## Wave History` body moves
+ * into a new `## Previous Session` section (appended at the end of the body,
+ * replacing any earlier one) under `### Wave History (<session>)`; the original
+ * section is removed. 4. `## Deviations` keeps its heading with an empty body;
+ * `## What Not To Retry` and `## Open Questions` stay byte-for-byte. 5. Other
+ * frontmatter keys are untouched. 6. The five recommendation keys STAY in the
+ * frontmatter (Phase 7.5 reads them); a readable copy heads `## Previous Session`.
+ * 7. The five `scope-baseline-*` keys are deleted, no other key.
+ *
+ * When neither a Wave History section nor a recommendation exists, an existing
+ * `## Previous Session` is left as it is — there is nothing to replace it with.
+ * With recommendations but no Wave History (a coordinator-direct session), the
+ * earlier archive body stays below the new recommendations block.
+ *
+ * @param {string} contents  STATE.md contents
+ * @returns {{changed: boolean, contents: string, reason?: 'status-not-completed'|'unparseable'}}
+ */
+export function resetStateMdToIdle(contents) {
+  const parsed = parseStateMd(contents);
+  if (parsed === null) return { changed: false, contents, reason: 'unparseable' };
+  if (parsed.frontmatter.status !== 'completed') {
+    return { changed: false, contents, reason: 'status-not-completed' };
+  }
+
+  const { preamble, sections } = splitSections(parsed.body);
+  const waveHistory = sections.filter((s) => isSection(s.heading, 'Wave History'));
+  const recBlock = renderRecommendationsBlock(parsed.frontmatter);
+  const archive = waveHistory.length > 0 || recBlock !== null;
+  // Rule 6 PREPENDS: without a new Wave History, the earlier archive stays below
+  // the fresh recommendations block (minus its own, now superseded, copy).
+  const keptArchive =
+    waveHistory.length === 0
+      ? trimBlankLines(
+          dropSubsection(
+            sections.filter((s) => isSection(s.heading, 'Previous Session')).flatMap((s) => s.lines.slice(1)),
+            RECOMMENDATIONS_HEADING,
+          ),
+        )
+      : [];
+
+  const lines = [...preamble];
+  for (const { heading, lines: own } of sections) {
+    if (isSection(heading, 'Wave History')) continue;
+    if (archive && isSection(heading, 'Previous Session')) continue;
+    lines.push(...(isSection(heading, 'Deviations') ? [heading, ''] : own));
+  }
+
+  let body = lines.join('\n');
+  if (archive) {
+    const blocks = [];
+    if (recBlock !== null) blocks.push(recBlock);
+    if (waveHistory.length > 0) {
+      const session = typeof parsed.frontmatter.session === 'string' ? parsed.frontmatter.session : '';
+      const heading = session ? `### Wave History (${session})` : '### Wave History';
+      const moved = trimBlankLines(waveHistory.flatMap((s) => s.lines.slice(1)));
+      blocks.push([heading, ...moved].join('\n'));
+    }
+    if (keptArchive.length > 0) blocks.push(keptArchive.join('\n'));
+    // Only ever ADD newlines before the new section — trimming would change the
+    // trailing bytes of whatever section now precedes it (possibly WNTR).
+    if (body.length > 0 && !body.endsWith('\n\n')) body += body.endsWith('\n') ? '\n' : '\n\n';
+    body += `## Previous Session\n\n${blocks.join('\n\n')}\n`;
+  }
+
+  const fields = { status: 'idle', 'current-wave': 0 };
+  for (const key of SCOPE_BASELINE_KEYS) fields[key] = null;
+  const next = updateFrontmatterFields(
+    serializeStateMd({ frontmatter: parsed.frontmatter, body }),
+    fields,
+  );
+  return { changed: next !== contents, contents: next };
+}
+
+/**
+ * Applies `resetStateMdToIdle` to the repo's STATE.md under the STATE.md lock
+ * (`writeStateMd`). A missing or empty STATE.md is a no-op with reason `missing`.
+ * A write the size-ceiling / frontmatter-safe guards refuse comes back as
+ * `changed: false` with that guard's reason.
+ *
+ * @param {string} repoRoot  absolute repository root (required)
+ * @param {object} [opts]    passed through to `writeStateMd`
+ * @returns {Promise<{changed: boolean, reason?: string, path: string}>}
+ * @throws {Error} when repoRoot is missing
+ */
+export async function resetStateMdToIdleOnDisk(repoRoot, opts = {}) {
+  if (!repoRoot) {
+    throw new Error(`resetStateMdToIdleOnDisk: repoRoot is required (got ${typeof repoRoot}).`);
+  }
+  // No STATE.md: answer before the lock, which would otherwise create
+  // <repoRoot>/.orchestrator/ in whatever directory a mistyped root names.
+  const statePath = resolveStateMdPath(repoRoot);
+  if (!existsSync(statePath)) return { changed: false, reason: 'missing', path: statePath };
+  let reason;
+  const result = await writeStateMd(
+    repoRoot,
+    (contents) => {
+      if (contents === '') {
+        reason = 'missing';
+        return null;
+      }
+      const reset = resetStateMdToIdle(contents);
+      reason = reset.reason;
+      return reset.changed ? reset.contents : null;
+    },
+    opts,
+  );
+  const out = { changed: result.written, path: result.path };
+  const why = result.reason ?? reason;
+  if (why !== undefined) out.reason = why;
+  return out;
+}

package/scripts/lib/state-md/recommendations.mjs

@@ -37,10 +37,7 @@ export function parseRecommendations(frontmatter) {
   const mode = typeof frontmatter['recommended-mode'] === 'string'
     ? frontmatter['recommended-mode']
     : null;
-  const priorities = Array.isArray(frontmatter['top-priorities'])
-    && frontmatter['top-priorities'].every((x) => Number.isInteger(x))
-    ? frontmatter['top-priorities'].slice()
-    : null;
+  const priorities = parsePriorities(frontmatter['top-priorities']);
   const carryoverRatio = typeof frontmatter['carryover-ratio'] === 'number'
     && !Number.isNaN(frontmatter['carryover-ratio'])
     ? frontmatter['carryover-ratio']
@@ -55,3 +52,28 @@ export function parseRecommendations(frontmatter) {
 
   return { mode, priorities, carryoverRatio, completionRate, rationale };
 }
+
+/** An entry that is exactly an issue reference of THIS repo: `42` or `#42`. */
+const ISSUE_REF_RE = /^#?\d+$/;
+
+/**
+ * Normalises `top-priorities` to issue numbers. Integers pass; strings that are
+ * exactly an issue ref (`"#42"`, `"42"`) become integers; every other entry is
+ * dropped. A hand-written `"#370 fix banner"` or `"other-repo#74"` is never
+ * mined for digits, because the number may belong to another repo. An array
+ * that held entries but keeps none is a type mismatch (`null`), as before.
+ *
+ * @param {unknown} raw
+ * @returns {number[]|null}
+ */
+function parsePriorities(raw) {
+  if (!Array.isArray(raw)) return null;
+  const ids = [];
+  for (const entry of raw) {
+    if (Number.isInteger(entry)) ids.push(entry);
+    else if (typeof entry === 'string' && ISSUE_REF_RE.test(entry.trim())) {
+      ids.push(Number.parseInt(entry.trim().replace('#', ''), 10));
+    }
+  }
+  return raw.length > 0 && ids.length === 0 ? null : ids;
+}

package/scripts/lib/vault-mirror/namespace.mjs

@@ -55,7 +55,7 @@
 
 import { basename, resolve } from 'node:path';
 
-import { subjectToSlug } from './utils.mjs';
+import { legacySubjectToSlug } from './utils.mjs';
 import { isOwnerLeakySegment } from '../../lib/validate/check-owner-leakage.mjs';
 import { loadPseudonymMap } from './pseudonym-map.mjs';
 import { loadHostPaths, resolveHostPath } from '../config/host-paths.mjs';
@@ -311,7 +311,8 @@ export function resolveRepoNamespace({ vaultName = null, repoRoot = null } = {})
     : (declaredSlug ?? deriveRepo({ repoRoot: root }));
 
   // Sanitise: collapse to last path segment, lowercase, strip non-[a-z0-9-].
-  const seg = subjectToSlug(base);
+  // Repository storage identity stays historical; only new note names transliterate.
+  const seg = legacySubjectToSlug(base);
 
   // Leak-guard: check both the raw base AND the sanitised segment.
   // A personal home path or a private project slug must be caught before writing

package/scripts/lib/vault-mirror/process.mjs

@@ -10,7 +10,7 @@ import { basename, join, resolve, sep } from 'node:path';
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
 import { createSecretValueMasker } from '../secret-masker.mjs';
-import { subjectToSlug, isValidSlug, uuidPrefix8, recordKeySuffix8, toDate, parseFrontmatter } from './utils.mjs';
+import { subjectToSlug, legacySubjectToSlug, isValidSlug, uuidPrefix8, recordKeySuffix8, toDate, parseFrontmatter } from './utils.mjs';
 import { isRealSession } from '../session-schema/filters.mjs';
 import { resolveRepoNamespace } from './namespace.mjs';
 import { detectLearningSchema, normalizeLearningEntry, generateLearningNote, generateLearningNoteV2, learningSourceRecord } from './render-learnings.mjs';
@@ -19,7 +19,6 @@ import { emitMirrorEvent } from './telemetry.mjs';
 import {
   ARCHIVE_ROOT,
   canonicalNamespace,
-  legacyConcatSlug,
   noteNarrativeChars,
   markArchived,
   noteInsightKey,
@@ -904,7 +903,7 @@ function maskEntrySecrets(entry) {
  * @param {'v1'|'v2'} schema
  * @returns {string}
  */
-function learningSlug(entry, schema) {
+function learningSlug(entry, schema, slugger = learningNameSlugger(entry)) {
   const entryId = entry.id;
   let slugSource;
   if (schema === 'v2') {
@@ -916,7 +915,7 @@ function learningSlug(entry, schema) {
   }
   let slug;
   if (typeof slugSource === 'string' && slugSource.length > 0) {
-    slug = subjectToSlug(slugSource);
+    slug = slugger(slugSource);
   } else {
     slug = '';
   }
@@ -936,6 +935,52 @@ function learningSlug(entry, schema) {
 }
 
 
+/** A record without representable provenance (v1 or v2) keeps its historical name. */
+function learningNameSlugger(entry) {
+  return learningSourceRecord(entry) === null ? legacySubjectToSlug : subjectToSlug;
+}
+
+/** Compare BEFORE filename capping so a changed concatenated name is protected. */
+function hasLearningSlugTransition(entry, schema) {
+  if (learningNameSlugger(entry) === legacySubjectToSlug) return false;
+  const source = schema === 'v2' ? entry.id : entry.subject;
+  if (typeof source !== 'string' || source.length === 0) return false;
+  const normalized = schema === 'v1' ? source.trim().replace(/\s+/g, '-') : source;
+  return subjectToSlug(normalized) !== legacySubjectToSlug(normalized) ||
+    (schema === 'v1' && subjectToSlug(source) !== legacySubjectToSlug(source));
+}
+
+function historicalConcatSlug(subject) {
+  if (typeof subject !== 'string') return '';
+  return legacySubjectToSlug(subject);
+}
+
+/** All historical names, including both generations of disambiguation suffix. */
+function learningSlugVariants(entry, schema) {
+  const bases = new Set([learningSlug(entry, schema), learningSlug(entry, schema, legacySubjectToSlug)]);
+  if (schema === 'v1') {
+    const concat = historicalConcatSlug(entry.subject);
+    if (isValidSlug(concat)) {
+      bases.add(concat);
+      if (concat.length > 240) bases.add(concat.slice(0, 240).replace(/-+$/, ''));
+    }
+  }
+  const names = new Set(bases);
+  const id = String(entry.id);
+  for (const base of bases) {
+    names.add(`${base}-${uuidPrefix8(id)}`);
+    names.add(`${base}-${recordKeySuffix8(learningSourceRecord(entry) ?? id)}`);
+  }
+  return [...names];
+}
+
+/** Only explicit, exact provenance permits assigning an old name to a record. */
+function positiveLearningOwner(fm, name, repoNs, recordKey) {
+  return recordKey !== null && notOurGenerator(fm) === null &&
+    fm['id'] === name && fm['source-record'] === recordKey && fm['source-repo'] === repoNs;
+}
+
+
 export async function processLearning(rawEntry, _lineNum, ctx) {
   const {
     vaultDir,
@@ -1023,10 +1068,8 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   // #1513 review M2: a hyphen alias (`gotzendorferv2`) resolves to the
   // canonical folder already in the vault (`gotzendorfer-v2`), so the mirror
   // and the pruner agree on where a repo's notes live.
-  const repoNs = canonicalNamespace(
-    vaultDir,
-    resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null }),
-  );
+  const stableNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null });
+  const repoNs = canonicalNamespace(vaultDir, stableNs);
   // #725 D2: thread the resolved repo namespace into the learning frontmatter as
   // `source-repo` for cross-repo attribution. repoNs is already sanitised +
   // leak-guarded by resolveRepoNamespace, so it is safe to interpolate as-is. The
@@ -1075,18 +1118,56 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     return null;
   };
   const targetDir = join(resolve(vaultDir), '40-learnings', repoNs);
-  if (!dryRun) mkdirSync(targetDir, { recursive: true });
 
   let targetPath = join(targetDir, `${slug}.md`);
 
+  // #1548: inspect EVERY candidate before mutation when normalization changes
+  // a name. Missing/foreign/ambiguous provenance is not permission to create a
+  // second note, including under --force. Keep the actual flat or namespace path.
+  const slugTransition = hasLearningSlugTransition(entry, schema);
+  if (slugTransition) {
+    const matches = [];
+    for (const dir of [targetDir, join(resolve(vaultDir), '40-learnings')]) {
+      for (const name of learningSlugVariants(entry, schema)) {
+        const path = join(dir, `${name}.md`);
+        if (!existsSync(path)) continue;
+        const fm = parseFrontmatter(readFileSync(path, 'utf8'));
+        matches.push({ path, name, valid: positiveLearningOwner(fm, name, repoNs, writer.recordKey) });
+      }
+    }
+    if (matches.length > 1 || matches.some((match) => !match.valid)) {
+      return emitEntryAction(_lineNum, ctx, {
+        action: 'skipped-foreign-owner', path: null, id: entryId,
+        meta: { reason: 'slug transition: ambiguous or missing/contradictory provenance' },
+      });
+    }
+    if (matches.length === 1) {
+      slug = matches[0].name;
+      targetPath = matches[0].path;
+    }
+  }
+
+  // A provenance-less flat v2 note cannot be assigned to this namespace.
+  // Keep it untouched rather than creating a second copy on an advanced date.
+  if (schema === 'v2' && writer.recordKey === null &&
+      learningSlugVariants(entry, schema).some((name) =>
+        existsSync(join(resolve(vaultDir), '40-learnings', name + '.md')))) {
+    return emitEntryAction(_lineNum, ctx, {
+      action: 'skipped-foreign-owner', path: null, id: entryId,
+      meta: { reason: 'flat note: missing representable source provenance' },
+    });
+  }
+
+  if (!dryRun) mkdirSync(targetDir, { recursive: true });
+
   // #1513 LEGACY SLUG: until #725 D1 a v1 subject was slugged WITHOUT the
   // whitespace → hyphen pre-map ("3parallelimplagents…"); the canonical form
   // hyphenates ("3-parallel-impl-agents…"). When only the legacy variant of
   // THIS record's note exists, it IS the note: it is updated in place under
   // its own name instead of a second file being created beside it (the vault
   // carried 364 such twins). New notes always get the canonical name.
-  if (schema === 'v1') {
-    const legacySlug = legacyConcatSlug(entry.subject);
+  if (!slugTransition && schema === 'v1') {
+    const legacySlug = historicalConcatSlug(entry.subject);
     const flatDir = join(resolve(vaultDir), '40-learnings');
     if (
       isValidSlug(legacySlug) &&
@@ -1104,7 +1185,9 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
           foreignOwnerReason(legacyFm, writer) === null
         ) {
           slug = legacySlug;
-          targetPath = join(targetDir, `${legacySlug}.md`);
+          targetPath = positiveLearningOwner(legacyFm, legacySlug, repoNs, writer.recordKey)
+            ? legacyPath
+            : join(targetDir, `${legacySlug}.md`);
           break;
         }
       }
@@ -1114,8 +1197,8 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   // #660 IDEMPOTENCY DUAL-PROBE: before treating the namespaced path as absent,
   // also check the legacy flat path. If a note with the same slug already exists
   // in the flat layout (pre-namespace migration), treat it as existing to avoid
-  // duplicating the note. The deferred-migration decision means we only skip;
-  // we do NOT move the flat note into the namespaced dir here.
+  // duplicating the note. Positive provenance also permits an update at the
+  // actual flat path; notes without that evidence keep their historical rules.
   const legacyFlatPath = join(resolve(vaultDir), '40-learnings', `${slug}.md`);
   // Set when a still-leaking legacy flat note was healed in place below, so the
   // action emitted for THIS entry can say so (see the write sites at the end).
@@ -1142,7 +1225,11 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     if (legacyForeign && legacyStillLeaks) {
       healedForeignLeak = maskForeignNoteInPlace(legacyFlatPath, legacyContent, ctx);
     }
-    if (legacyMarked && !legacyForeign) {
+    if (positiveLearningOwner(legacyFm, slug, repoNs, writer.recordKey)) {
+      // A proven flat note is the update target. Let the common existing-note
+      // branch below compare/render/heal it ONCE; never pre-write a healed copy.
+      targetPath = legacyFlatPath;
+    } else if (legacyMarked && !legacyForeign) {
       const entryUpdated = toDate(dateSource);
       if (!force && legacyFm['updated'] && legacyFm['updated'] >= entryUpdated) {
         // Date has not advanced — but content may have changed (confidence, insight, etc.).
@@ -1313,7 +1400,7 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
 
     // #1506.2: the main note is this record's — a live disambiguation copy of
     // the same record (left by an interrupted takeover) is superseded.
-    const stale = fm['source-record'] === writer.recordKey
+    const stale = !slugTransition && fm['source-record'] === writer.recordKey
       ? staleOwnDisambig(targetDir, slug, entryId, writer)
       : null;
 
@@ -1351,14 +1438,19 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
       return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: slug });
     }
 
-    // Overwrite with advanced updated date (or forced re-render)
+    // Overwrite with advanced updated date (or forced re-render). A retained
+    // flat note, including an old Unicode slug, is healed by this single write.
     const content = generator(entry, slug, generatorOpts);
+    healedLegacyFlat = !dryRun && targetPath === legacyFlatPath && maskerWouldChange(existingContent);
     if (!dryRun) writeFileSync(targetPath, content, 'utf8');
     return emitEntryAction(_lineNum, ctx, {
       action: 'updated',
       path: targetPath,
       id: slug,
-      ...(stale !== null ? { meta: { superseded_id: basename(stale.path, '.md') } } : {}),
+      ...((stale !== null || healedLegacyFlat) ? { meta: {
+        ...(stale !== null ? { superseded_id: basename(stale.path, '.md') } : {}),
+        ...(healedLegacyFlat ? { healed_legacy_flat: true } : {}),
+      } } : {}),
     });
   }
 
@@ -1465,17 +1557,7 @@ function takeOverMainNote({
 export function learningNoteSlugs(rawEntry) {
   const entry = normalizeLearningEntry(rawEntry);
   if (!entry || entry.id === null || entry.id === undefined) return [];
-  const schema = detectLearningSchema(entry);
-  const slugs = [learningSlug(entry, schema)];
-  if (schema === 'v1') {
-    const legacy = legacyConcatSlug(entry.subject);
-    if (isValidSlug(legacy) && !slugs.includes(legacy)) slugs.push(legacy);
-  }
-  const id = String(entry.id);
-  for (const name of [`${slugs[0]}-${uuidPrefix8(id)}`, `${slugs[0]}-${recordKeySuffix8(learningSourceRecord(entry) ?? id)}`]) {
-    if (!slugs.includes(name)) slugs.push(name);
-  }
-  return slugs;
+  return learningSlugVariants(entry, detectLearningSchema(entry));
 }
 
 /**
@@ -1515,13 +1597,36 @@ export async function processArchivedLearning(rawEntry, _lineNum, ctx) {
       meta: { reason: 'archived record: a live record owns this note' },
     });
   if (names.length === 0) return liveOwned();
-  const repoNs = canonicalNamespace(
-    vaultDir,
-    resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null }),
-  );
+  const stableNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null });
+  const repoNs = canonicalNamespace(vaultDir, stableNs);
   const nsDir = join(resolve(vaultDir), '40-learnings', repoNs);
   const flatDir = join(resolve(vaultDir), '40-learnings');
   const writer = { recordKey: learningSourceRecord(entry) };
+  const schema = detectLearningSchema(entry);
+  if (schema === 'v2' && writer.recordKey === null &&
+      allNames.some((name) => existsSync(join(flatDir, name + '.md')))) {
+    return emitEntryAction(_lineNum, ctx, {
+      action: 'skipped-foreign-owner', path: null, id: entry.id,
+      meta: { reason: 'flat note: missing representable source provenance' },
+    });
+  }
+  if (hasLearningSlugTransition(entry, schema)) {
+    const matches = [];
+    for (const dir of [nsDir, flatDir]) {
+      for (const name of allNames) {
+        const path = join(dir, `${name}.md`);
+        if (!existsSync(path)) continue;
+        const fm = parseFrontmatter(readFileSync(path, 'utf8'));
+        matches.push(positiveLearningOwner(fm, name, repoNs, writer.recordKey));
+      }
+    }
+    if (matches.length > 1 || matches.some((valid) => !valid)) {
+      return emitEntryAction(_lineNum, ctx, {
+        action: 'skipped-foreign-owner', path: null, id: entry.id,
+        meta: { reason: 'slug transition: ambiguous or missing/contradictory provenance' },
+      });
+    }
+  }
   for (const dir of [nsDir, flatDir]) {
     for (const name of names) {
       const path = join(dir, `${name}.md`);
@@ -1615,8 +1720,8 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   const generator =
     schema === 'v3' ? generateSessionNoteV3 : schema === 'v2' ? generateSessionNoteV2 : generateSessionNote;
 
-  // Validate session_id as a filesystem-safe slug; fall back via subjectToSlug
-  // (which collapses slashes to last segment + strips invalid chars) before
+  // Validate session_id as a filesystem-safe slug; preserve old Session identity
+  // with the historical sanitizer (collapse slash paths + strip invalid chars), before
   // resorting to a uuid-derived slug. Without subjectToSlug, raw slashes in
   // rawSessionId (e.g. "feat/opus-4-7-...") would survive uuidPrefix8 and
   // produce a path with directory separators in the basename.
@@ -1624,7 +1729,7 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   if (isValidSlug(rawSessionId)) {
     session_id = rawSessionId;
   } else if (typeof rawSessionId === 'string' && rawSessionId.length > 0) {
-    const sanitised = subjectToSlug(rawSessionId);
+    const sanitised = legacySubjectToSlug(rawSessionId);
     session_id = isValidSlug(sanitised) ? sanitised : `session-${uuidPrefix8(rawSessionId)}`;
   } else {
     session_id = `session-${uuidPrefix8(randomUUID())}`;
@@ -1671,10 +1776,8 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // owner-leaky repo's real name reached the vault through the session-note
   // frontmatter even though the directory AND the learning `source-repo` field
   // were already pseudonym-mapped/redacted (#732 leak-guard bypass).
-  const repoNs = canonicalNamespace(
-    vaultDir,
-    resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null }),
-  );
+  const stableNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null });
+  const repoNs = canonicalNamespace(vaultDir, stableNs);
 
   // Narrative gate (#1513, replaces the PRD F1.2 rendered-length gate). A
   // session gets its own note only when its FREE-TEXT fields (`notes`,

package/scripts/lib/vault-mirror/render-learnings.mjs

@@ -5,7 +5,7 @@
  *          sourceRecordValue, learningSourceRecord, sourceRecordLine (#1503)
  */
 
-import { toDate, truncateAtWord, yamlQuoteIfNeeded, subjectToSlug, isValidSlug, buildTag, resolveSourceSessionLink } from './utils.mjs';
+import { toDate, truncateAtWord, yamlQuoteIfNeeded, legacySubjectToSlug, isValidSlug, buildTag, resolveSourceSessionLink } from './utils.mjs';
 
 const GENERATOR_MARKER = 'session-orchestrator-vault-mirror@1';
 
@@ -118,9 +118,10 @@ export function normalizeLearningEntry(entry) {
     e.evidence = joinList(e.evidence_sessions) ?? joinList(e.files) ?? joinList(e.sessions) ?? '(none recorded)';
   }
   if (e.id === null || e.id === undefined) {
-    // subjectToSlug strips whitespace without hyphenating (designed for
+    // Keep historical ASCII deletion for record identity; only note names
+    // transliterate. The old slugger strips whitespace (designed for
     // kebab-ish inputs) — pre-map whitespace to hyphens for prose subjects.
-    const derived = firstString(e.subject) ? subjectToSlug(e.subject.trim().replace(/\s+/g, '-')) : '';
+    const derived = firstString(e.subject) ? legacySubjectToSlug(e.subject.trim().replace(/\s+/g, '-')) : '';
     if (isValidSlug(derived)) e.id = derived;
   }
   if (e.source_session === null || e.source_session === undefined) {
@@ -157,7 +158,7 @@ export function generateLearningNote(entry, slug, opts = {}) {
   // through buildTag so each is kebab-slugified and capped at 64 chars. The
   // existing source/<session> slug is preserved (buildTag is idempotent for an
   // already-kebab value and adds the length cap).
-  const sourceTag = subjectToSlug(String(source_session)) || 'unknown';
+  const sourceTag = legacySubjectToSlug(String(source_session)) || 'unknown';
   const tags = `[${buildTag(['learning', type])}, ${buildTag(['status', status])}, ${buildTag(['source', sourceTag])}]`;
 
   // Check if expires has a value; it's optional in schema
@@ -230,7 +231,7 @@ export function generateLearningNoteV2(entry, slug, opts = {}) {
   const title = yamlQuoteIfNeeded(titleRaw);
 
   // #602: type/status interpolated raw upstream — slugify + cap each segment.
-  const scopeTag = subjectToSlug(scope) || 'unscoped';
+  const scopeTag = legacySubjectToSlug(scope) || 'unscoped';
   const tags = `[${buildTag(['learning', type])}, ${buildTag(['status', status])}, ${buildTag(['scope', scopeTag])}]`;
 
   // #725 D2: emit `source-repo` for cross-repo attribution when the caller threads