session-orchestrator 3.17.0 → 3.20.0

package/scripts/lib/learnings/kebab.mjs

@@ -0,0 +1,128 @@
+/**
+ * learnings/kebab.mjs — the slug primitive behind every `learning_key`, and
+ * {@link learningKeyOf}, the whole-key derivation built on it.
+ *
+ * `learning_key` is not a stored field. It is DERIVED as
+ * `` `${type}/${kebab(title || subject)}` `` and is the logical identity the
+ * whole dedupe/idempotency layer keys on (`reconcile/idempotency.mjs` calls it
+ * "THE logical dedupe key"). That makes this a contract, not a formatting
+ * helper: two callers that derive differently do not produce two ugly slugs,
+ * they FORK the key space — the same learning renders under two identities,
+ * dedupe stops firing, and both halves look correct in isolation.
+ *
+ * Before this module existed there were four copies of `kebab` plus one inline
+ * expression, none exported, none shared (two of the four landed on the same
+ * day, from two different authors, each of whom flagged the duplication in
+ * their own report). They agreed on every reachable input — verified, not
+ * assumed — so consolidating here changed no existing key. See the byte-identity
+ * proof pinned in `tests/scripts/lib/learnings/kebab.test.mjs`.
+ *
+ * Consolidating the primitive left the SECOND half of the problem open, and it
+ * is the half that bites: what each call site FED the primitive. Four sites
+ * derived `${type}/…` verbatim while the writer (`reconcile/emitter.mjs`) alone
+ * derived `${kebab(type)}/…` — a divergence invisible while every live `type`
+ * is kebab-identical, and silent in BOTH directions the moment one is not.
+ * {@link learningKeyOf} exists so there is one derivation to agree with rather
+ * than five to keep in sync.
+ *
+ * ## Why this file lives under `learnings/` and not under `reconcile/`
+ *
+ * Dependency direction, measured rather than presumed (2026-08-13, HEAD
+ * 5d59e62): `grep -rn "from '../learnings/" scripts/lib/reconcile/` reports 6
+ * import edges across 4 files (`eligibility.mjs`, `engine.mjs` ×2,
+ * `emitter.mjs` ×2, `renderer.mjs` — three of them pulling THIS module, three
+ * pulling `learnings/schema.mjs`), and the reverse grep
+ * `from '../reconcile/'` over `scripts/lib/learnings/` reports 0. A primitive
+ * shared by both packages therefore belongs on the `learnings/` side; placing
+ * it under `reconcile/` would invert an edge and introduce a cycle.
+ *
+ * Deliberately NOT re-exported from the `scripts/lib/learnings.mjs` barrel —
+ * `surface.mjs` and `affinity.mjs` set that precedent: consumers import the
+ * leaf directly, so the barrel stays the historical schema/io/filters surface.
+ *
+ * ## What this module is NOT
+ *
+ * Not a general-purpose slugifier. Vault note ids, tag segments, and rule
+ * filenames have their own slug rules with their own length caps and charset
+ * contracts (`vault-mirror/utils.mjs`, `vault-archive.mjs`). Do not route those
+ * through here — a shared slugifier across unrelated identity spaces is how a
+ * cap added for one consumer silently re-keys another.
+ *
+ * Pure, stdlib-only, no imports, no clock, no fs.
+ */
+
+/**
+ * Slugify a string into the stable kebab-case token used for learning keys.
+ *
+ * Lowercases, collapses every run of non-`[a-z0-9]` characters into a single
+ * `-`, and trims leading/trailing `-`.
+ *
+ * Three properties callers depend on:
+ *
+ *   1. **Total** — never throws. Non-string input is coerced via `String()`,
+ *      so `null`/`undefined`/numbers yield `"null"`/`"undefined"`/`"12345"`
+ *      rather than a `TypeError`. Callers pass values typed `unknown` at
+ *      their trust boundary; a throw there would abort a reconcile run.
+ *   2. **Lossy on non-ASCII** — German umlauts and em-dashes in the corpus are
+ *      collapsed to `-` (`"Größe"` → `"gr-e"`), NOT transliterated. Ugly, and
+ *      deliberately frozen: every stamped key in `.claude/rules/*.md` and in
+ *      `.orchestrator/runtime/reconcile-candidates.jsonl` was minted this way.
+ *      Adding transliteration would re-key the entire corpus.
+ *   3. **May return the empty string** — an all-symbol input (`"!!!"`) yields
+ *      `""`. `reconcile/renderer.mjs::deriveSlug` branches on exactly that to
+ *      fall back to its hash suffix, so an "always return something non-empty"
+ *      change here would silently disable that branch.
+ *
+ * @param {unknown} s Value to slugify; coerced with `String()`.
+ * @returns {string} Kebab token; `''` when the input holds no `[a-z0-9]`.
+ */
+export function kebab(s) {
+  return String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * THE derivation of a learning's logical key: `` `${type}/${kebab(title || subject)}` ``.
+ *
+ * One rule, four decisions, each of which was a divergence between call sites
+ * before this function existed:
+ *
+ *   1. **The TYPE half is verbatim (trimmed), never kebab'd.** The subject half
+ *      is prose and must be slugged; the type half is an enum token a reader
+ *      parses BACK OUT of the key — `backfill-learnings-from-vault.mjs` uses
+ *      `learning_key.split('/')[0]` as the reconstructed `type` and
+ *      cross-checks it against the vault note's type. Kebabbing it would make
+ *      that half lossy, which is precisely the fidelity downgrade the backfill
+ *      labels `derived:learning-key-slug (original prose not recoverable)` for
+ *      the subject half. Frontmatter safety does not need it either: the key
+ *      becomes an unquoted `learning-key:` scalar, and `reconcile/renderer.mjs`
+ *      already asserts `LEARNING_KEY_RE` (`/^[a-z0-9/-]+$/`) on the whole value
+ *      before rendering — an unsafe type is REJECTED loudly there rather than
+ *      silently re-keyed here.
+ *   2. **`title` wins over `subject`**, and a whitespace-only `title` falls
+ *      through to `subject` rather than yielding an empty slug.
+ *   3. **`null`, not a throw, for an unkeyable record.** Readers scan corpora
+ *      that contain shape-foreign lines; an unkeyable record simply does not
+ *      participate in key resolution. Writers that need a string check for
+ *      `null` and reject the record with their own auditable reason.
+ *   4. **An empty slug is unkeyable, not a key.** `kebab('!!!')` is `''`, and
+ *      `` `anti-pattern/` `` is not an identity — it is a bucket every
+ *      all-symbol-subject record of that type would collide in.
+ *
+ * @param {unknown} record A learning record (or anything; non-records yield `null`).
+ * @returns {string|null} `` `${type}/${slug}` ``, or `null` when unkeyable.
+ */
+export function learningKeyOf(record) {
+  if (record === null || typeof record !== 'object' || Array.isArray(record)) return null;
+  const rec = /** @type {Record<string, unknown>} */ (record);
+  const type = typeof rec.type === 'string' ? rec.type.trim() : '';
+  const titleOrSubject =
+    (typeof rec.title === 'string' && rec.title.trim() !== '' ? rec.title : '') ||
+    (typeof rec.subject === 'string' && rec.subject.trim() !== '' ? rec.subject : '');
+  if (type === '' || titleOrSubject === '') return null;
+  const slug = kebab(titleOrSubject);
+  if (slug === '') return null;
+  return `${type}/${slug}`;
+}

package/scripts/lib/learnings/schema.mjs

@@ -83,8 +83,13 @@ export const LEARNING_TYPE_REGISTRY = Object.freeze({
   'fragile-file':                Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true  }),
   'effective-sizing':            Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: false }),
   'recurring-issue':             Object.freeze({ ttlDays: 45, agentProposable: true,  ruleConvertible: true  }),
-  'workflow-pattern':            Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: false }),
-  'proven-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: false }),
+  // workflow-pattern / proven-pattern: flipped ruleConvertible false->true
+  // (issue #900) — the real corpus census showed a large volume of live
+  // `workflow-pattern`/`proven-pattern` records (post type-alias-normalization,
+  // see LEARNING_TYPE_ALIASES below) that carried usable file_paths but were
+  // structurally unconvertible before this flip.
+  'workflow-pattern':            Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
+  'proven-pattern':              Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
   'anti-pattern':                Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: true  }),
   'autopilot-effectiveness':     Object.freeze({ ttlDays: 90, agentProposable: true,  ruleConvertible: false }),
   // autonomy-verdict (#683): repo/scope readiness synthesis from autopilot
@@ -106,6 +111,30 @@ export const LEARNING_TYPE_REGISTRY = Object.freeze({
   'stagnation-class-frequency':  Object.freeze({ ttlDays: 60, agentProposable: false, ruleConvertible: true  }),
 });
 
+/**
+ * Free-form producer-dialect type names -> their canonical
+ * {@link LEARNING_TYPE_REGISTRY} counterpart (issue #900). The real corpus
+ * accumulated learnings stamped with type names that were never registered
+ * (`gotcha`, `pattern`, ...) — these are semantically the SAME classes as
+ * two registered types, just written with a different literal. Applied by
+ * {@link normalizeDialects} on both the read funnel (`normalizeLearning`)
+ * and the write/migration funnel (`migrateLegacyLearning`), so every
+ * downstream consumer (TTL derivation, `CONVERT_TYPES` / `PROPOSAL_TYPES`
+ * membership, reconcile eligibility) sees one canonical type space —
+ * mirrors the existing `files` -> `file_paths` dialect-normalization
+ * pattern one level up (type name instead of field name).
+ *
+ * INVARIANT (guarded by a test): no alias KEY may collide with a
+ * `LEARNING_TYPE_REGISTRY` key — a collision would silently rewrite an
+ * already-canonical type into a different one.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const LEARNING_TYPE_ALIASES = Object.freeze({
+  gotcha: 'anti-pattern',
+  pattern: 'proven-pattern',
+});
+
 /**
  * Per-type TTL policy (in days) for `expires_at` derivation. Derived from
  * {@link LEARNING_TYPE_REGISTRY} — see parent module documentation for tier
@@ -275,7 +304,10 @@ const _warnedSessionIdConflict = new Set();
  * session_id/source_session conflict (see below); idempotent; never throws;
  * non-objects (and arrays) pass through unchanged. Does NOT mutate its input.
  *
- * Dialect rules (Epic #723 B2 — census 2026-07-02):
+ * Dialect rules (Epic #723 B2 — census 2026-07-02; type-alias rule added
+ * issue #900):
+ *   - `type`         → canonical type — resolved via {@link LEARNING_TYPE_ALIASES}
+ *                      (e.g. `gotcha` → `anti-pattern`, `pattern` → `proven-pattern`).
  *   - `files`        → `file_paths`  — verbatim value move; an empty array is
  *                      preserved as an empty `file_paths`; a canonical
  *                      `file_paths` already present wins (legacy `files` dropped).
@@ -310,6 +342,14 @@ export function normalizeDialects(entry, { reserializeTimestamps = true } = {})
 
   const out = { ...entry };
 
+  // type alias resolution (#900) — canonicalize free-form producer type names
+  // (e.g. `gotcha`, `pattern`) to their LEARNING_TYPE_REGISTRY counterpart so
+  // every downstream consumer (TTL derivation, CONVERT_TYPES / PROPOSAL_TYPES
+  // membership, reconcile eligibility) sees one canonical type space.
+  if (typeof out.type === 'string' && out.type in LEARNING_TYPE_ALIASES) {
+    out.type = LEARNING_TYPE_ALIASES[out.type];
+  }
+
   // files → file_paths (verbatim value move; canonical wins; empty array kept).
   if ('files' in out) {
     if (!('file_paths' in out)) {