@ngockhoale/ukit 2.6.6 → 2.6.8

package/src/core/memory/storeV2.js

@@ -0,0 +1,171 @@
+// Memory v2 store — SPEC §3.
+// Single atomic JSON document at <memoryRoot>/v2/records.json
+// ({ schemaVersion: 2, records: [...] }); writes via fileOps.writeJson (tmp+rename).
+// Read ops call ensureMigrated() first so every consumer triggers the lazy
+// v1→v2 migration (SPEC §4); migrate.js is lazy-imported to break the
+// storeV2↔migrate import cycle (runMigration writes via saveRecords).
+
+import fs from 'node:fs/promises';
+import { buildRuntimePaths } from '../runtimePaths.js';
+import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { loadRuntimeConfig } from '../runtimeConfig.js';
+import { createRecord, normalizeRecord } from './records.js';
+
+const SCHEMA_VERSION = 2;
+
+// Per-process memoization for ensureMigrated — one-shot check per projectRoot.
+const migratedRoots = new Set();
+
+async function ensureMigrated(projectRoot) {
+  const key = String(projectRoot);
+  if (migratedRoots.has(key)) return;
+  migratedRoots.add(key); // mark first: a failed/again migration must not loop
+  try {
+    const paths = buildRuntimePaths(projectRoot);
+    let recordsExists = false;
+    try {
+      await fs.access(paths.memoryV2RecordsPath);
+      recordsExists = true;
+    } catch {
+      recordsExists = false;
+    }
+    if (recordsExists) return;
+
+    const config = await loadRuntimeConfig(projectRoot);
+    if (config?.memoryV2?.autoMigrate === false) return;
+
+    const migrate = await import('./migrate.js');
+    if (await migrate.needsMigration(projectRoot)) {
+      await migrate.runMigration(projectRoot);
+    }
+  } catch {
+    // Lazy migration is best-effort: a failed auto-run must not break reads.
+  }
+}
+
+function isRawRecord(input) {
+  return input && typeof input === 'object' && typeof input.id === 'string'
+    && typeof input.status === 'string';
+}
+
+/**
+ * loadRecords(projectRoot) → record[] — tolerant: invalid entries skipped.
+ */
+export async function loadRecords(projectRoot) {
+  await ensureMigrated(projectRoot);
+  const { records } = await readStore(projectRoot);
+  return records;
+}
+
+async function readStore(projectRoot) {
+  const paths = buildRuntimePaths(projectRoot);
+  let doc;
+  try {
+    doc = await readJsonIfExists(paths.memoryV2RecordsPath);
+  } catch {
+    return { records: [], invalidSkipped: 1 };
+  }
+  if (!doc) return { records: [], invalidSkipped: 0 };
+
+  const rawRecords = Array.isArray(doc.records) ? doc.records : [];
+  const records = [];
+  let invalidSkipped = Array.isArray(doc.records) ? 0 : 1;
+  for (const raw of rawRecords) {
+    const normalized = normalizeRecord(raw);
+    if (normalized) records.push(normalized);
+    else invalidSkipped += 1;
+  }
+  return { records, invalidSkipped };
+}
+
+/**
+ * saveRecords(projectRoot, records) → void — atomic write; drops unrecoverable entries.
+ */
+export async function saveRecords(projectRoot, records) {
+  const paths = buildRuntimePaths(projectRoot);
+  const normalized = (Array.isArray(records) ? records : [])
+    .map((raw) => normalizeRecord(raw))
+    .filter(Boolean);
+  await writeJson(paths.memoryV2RecordsPath, {
+    schemaVersion: SCHEMA_VERSION,
+    records: normalized,
+  });
+}
+
+/**
+ * addRecord(projectRoot, recordInput) → record
+ * Accepts either createRecord-style input or a full raw record (normalized).
+ */
+export async function addRecord(projectRoot, recordInput) {
+  const record = isRawRecord(recordInput)
+    ? normalizeRecord(recordInput)
+    : createRecord(recordInput);
+  if (!record) {
+    throw new Error('addRecord: input could not be normalized into a valid record');
+  }
+  const { records } = await readStore(projectRoot);
+  await saveRecords(projectRoot, [...records, record]);
+  return record;
+}
+
+const PATCHABLE_FIELDS = ['type', 'scope', 'text', 'provenance', 'confidence',
+  'valid_until', 'status', 'project_id', 'meta', 'source_fingerprint'];
+
+/**
+ * updateRecord(projectRoot, id, patch) → record | null
+ */
+export async function updateRecord(projectRoot, id, patch = {}) {
+  await ensureMigrated(projectRoot);
+  const { records } = await readStore(projectRoot);
+  const index = records.findIndex((r) => r.id === id);
+  if (index === -1) return null;
+
+  const next = { ...records[index] };
+  for (const field of PATCHABLE_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(patch, field)) {
+      next[field] = patch[field];
+    }
+  }
+  const normalized = normalizeRecord(next);
+  if (!normalized) {
+    throw new Error(`updateRecord: patch produces an invalid record (id ${id})`);
+  }
+  records[index] = normalized;
+  await saveRecords(projectRoot, records);
+  return normalized;
+}
+
+/**
+ * getRecord(projectRoot, id) → record | null
+ */
+export async function getRecord(projectRoot, id) {
+  await ensureMigrated(projectRoot);
+  const { records } = await readStore(projectRoot);
+  return records.find((r) => r.id === id) ?? null;
+}
+
+/**
+ * queryRecords(projectRoot, { type?, scope?, status?, projectId? }) → record[]
+ */
+export async function queryRecords(projectRoot, { type, scope, status, projectId } = {}) {
+  const records = await loadRecords(projectRoot);
+  return records.filter((r) => (type == null || r.type === type)
+    && (scope == null || r.scope === scope)
+    && (status == null || r.status === status)
+    && (projectId == null || r.project_id === projectId));
+}
+
+/**
+ * stats(projectRoot) → { total, byType, byStatus, invalidSkipped }
+ */
+export async function stats(projectRoot) {
+  await ensureMigrated(projectRoot);
+  const { records, invalidSkipped } = await readStore(projectRoot);
+  const byType = {};
+  const byStatus = {};
+  for (const r of records) {
+    byType[r.type] = (byType[r.type] ?? 0) + 1;
+    byStatus[r.status] = (byStatus[r.status] ?? 0) + 1;
+  }
+  return { total: records.length, byType, byStatus, invalidSkipped };
+}

package/src/core/memory/storeV2Loader.js

@@ -0,0 +1,22 @@
+// Lazy/defensive bridge to storeV2.js (owned by TASK-002).
+// Real storeV2.queryRecords performs ensureMigrated auto-migration internally —
+// consumers must never call migration themselves; just call this and treat an
+// empty result as "fall back to the legacy memory path".
+
+/**
+ * loadV2Records(projectRoot) → record[] | []
+ * Returns [] when storeV2 is unavailable, disabled upstream, or the v2 store
+ * holds no records yet. Callers decide fallback.
+ */
+export async function loadV2Records(projectRoot, filter = {}) {
+  try {
+    const storeV2 = await import('./storeV2.js');
+    if (typeof storeV2?.queryRecords !== 'function') {
+      return [];
+    }
+    const records = await storeV2.queryRecords(projectRoot, filter);
+    return Array.isArray(records) ? records : [];
+  } catch {
+    return [];
+  }
+}

package/src/core/projectImportant.js

@@ -2,7 +2,7 @@
  * projectImportant.js (TASK-037)
  *
  * Source-side inspector + deterministic envelope renderer for
- * PROJECT_IMPORTANT.md per docs/PROJECT_IMPORTANT_SPEC.md §3, §4, §5.2, §6,
+ * PROJECT_IMPORTANT.md per docs/archive/specs/PROJECT_IMPORTANT_SPEC.md §3, §4, §5.2, §6,
  * §12.1.
  *
  * Guarantees:

package/src/core/runtimeConfig.js

@@ -157,6 +157,36 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
         cap: 'smart',
       },
     },
+    codeIntel: {
+      enabled: true,
+      router: { enabled: true, defaultMode: 'auto' },
+      budgets: {
+        peek: 500,
+        targeted: 2000,
+        impact: 3000,
+        explore: 4000,
+        deep_flow: 6000,
+        analogy: 4000,
+      },
+      freshness: { guardLevel: 'L0', autoRefresh: false, incremental: true },
+      retriever: {
+        limit: 20,
+        bm25: { k1: 1.2, b: 0.75 },
+        merge: 'rrf',
+        rrfK: 60,
+        weights: { exact: 1.0, symbol: 1.2, bm25: 0.8, semantic: 1.0 },
+      },
+      impact: { defaultDepth: 2, maxDepth: 4, maxNodes: 200 },
+      diagnostics: { enabled: true, timeoutMs: 8000 },
+      providers: { semantic: 'null' },
+    },
+    memoryV2: {
+      enabled: true,
+      autoMigrate: true,
+      episodeTtlDays: 90,
+      promotion: { episodeToRuleRequiresApproval: true },
+      recall: { maxRecords: 8 },
+    },
     memory: {
       enabled: true,
       autoCapture: true,
@@ -354,6 +384,101 @@ export function validateRuntimeConfig(config) {
     }
   }
 
+  if (!isPlainObject(config.codeIntel)) {
+    errors.push('codeIntel must be an object.');
+  } else {
+    const codeIntel = config.codeIntel;
+    pushBooleanError(errors, codeIntel.enabled, 'codeIntel.enabled');
+    if (!isPlainObject(codeIntel.router)) {
+      errors.push('codeIntel.router must be an object.');
+    } else {
+      pushBooleanError(errors, codeIntel.router.enabled, 'codeIntel.router.enabled');
+      const VALID_ROUTER_MODES = new Set(['auto', 'none', 'peek', 'targeted', 'explore', 'impact', 'deep_flow', 'analogy']);
+      if (!VALID_ROUTER_MODES.has(codeIntel.router.defaultMode)) {
+        errors.push(`codeIntel.router.defaultMode must be one of: ${[...VALID_ROUTER_MODES].join(', ')}.`);
+      }
+    }
+    if (!isPlainObject(codeIntel.budgets)) {
+      errors.push('codeIntel.budgets must be an object.');
+    } else {
+      for (const key of ['peek', 'targeted', 'impact', 'explore', 'deep_flow', 'analogy']) {
+        pushPositiveNumberError(errors, codeIntel.budgets[key], `codeIntel.budgets.${key}`);
+      }
+    }
+    if (!isPlainObject(codeIntel.freshness)) {
+      errors.push('codeIntel.freshness must be an object.');
+    } else {
+      const VALID_GUARD_LEVELS = new Set(['L0', 'L1', 'L2', 'L3', 'L4']);
+      if (!VALID_GUARD_LEVELS.has(codeIntel.freshness.guardLevel)) {
+        errors.push(`codeIntel.freshness.guardLevel must be one of: ${[...VALID_GUARD_LEVELS].join(', ')}.`);
+      }
+      pushBooleanError(errors, codeIntel.freshness.autoRefresh, 'codeIntel.freshness.autoRefresh');
+      pushBooleanError(errors, codeIntel.freshness.incremental, 'codeIntel.freshness.incremental');
+    }
+    if (!isPlainObject(codeIntel.retriever)) {
+      errors.push('codeIntel.retriever must be an object.');
+    } else {
+      pushPositiveNumberError(errors, codeIntel.retriever.limit, 'codeIntel.retriever.limit');
+      if (!isPlainObject(codeIntel.retriever.bm25)) {
+        errors.push('codeIntel.retriever.bm25 must be an object.');
+      } else {
+        pushPositiveNumberError(errors, codeIntel.retriever.bm25.k1, 'codeIntel.retriever.bm25.k1');
+        pushPositiveNumberError(errors, codeIntel.retriever.bm25.b, 'codeIntel.retriever.bm25.b');
+      }
+      const VALID_RETRIEVER_MERGES = new Set(['rrf', 'concat']);
+      if (!VALID_RETRIEVER_MERGES.has(codeIntel.retriever.merge)) {
+        errors.push(`codeIntel.retriever.merge must be one of: ${[...VALID_RETRIEVER_MERGES].join(', ')}.`);
+      }
+      pushPositiveNumberError(errors, codeIntel.retriever.rrfK, 'codeIntel.retriever.rrfK');
+      if (!isPlainObject(codeIntel.retriever.weights)) {
+        errors.push('codeIntel.retriever.weights must be an object.');
+      } else {
+        for (const lane of ['exact', 'symbol', 'bm25', 'semantic']) {
+          if (typeof codeIntel.retriever.weights[lane] !== 'number' || Number.isNaN(codeIntel.retriever.weights[lane])) {
+            errors.push(`codeIntel.retriever.weights.${lane} must be a number.`);
+          }
+        }
+      }
+    }
+    if (!isPlainObject(codeIntel.impact)) {
+      errors.push('codeIntel.impact must be an object.');
+    } else {
+      pushPositiveNumberError(errors, codeIntel.impact.defaultDepth, 'codeIntel.impact.defaultDepth');
+      pushPositiveNumberError(errors, codeIntel.impact.maxDepth, 'codeIntel.impact.maxDepth');
+      pushPositiveNumberError(errors, codeIntel.impact.maxNodes, 'codeIntel.impact.maxNodes');
+    }
+    if (!isPlainObject(codeIntel.diagnostics)) {
+      errors.push('codeIntel.diagnostics must be an object.');
+    } else {
+      pushBooleanError(errors, codeIntel.diagnostics.enabled, 'codeIntel.diagnostics.enabled');
+      pushPositiveNumberError(errors, codeIntel.diagnostics.timeoutMs, 'codeIntel.diagnostics.timeoutMs');
+    }
+    if (!isPlainObject(codeIntel.providers)) {
+      errors.push('codeIntel.providers must be an object.');
+    } else {
+      pushNonEmptyStringError(errors, codeIntel.providers.semantic, 'codeIntel.providers.semantic');
+    }
+  }
+
+  if (!isPlainObject(config.memoryV2)) {
+    errors.push('memoryV2 must be an object.');
+  } else {
+    const memoryV2 = config.memoryV2;
+    pushBooleanError(errors, memoryV2.enabled, 'memoryV2.enabled');
+    pushBooleanError(errors, memoryV2.autoMigrate, 'memoryV2.autoMigrate');
+    pushPositiveNumberError(errors, memoryV2.episodeTtlDays, 'memoryV2.episodeTtlDays');
+    if (!isPlainObject(memoryV2.promotion)) {
+      errors.push('memoryV2.promotion must be an object.');
+    } else {
+      pushBooleanError(errors, memoryV2.promotion.episodeToRuleRequiresApproval, 'memoryV2.promotion.episodeToRuleRequiresApproval');
+    }
+    if (!isPlainObject(memoryV2.recall)) {
+      errors.push('memoryV2.recall must be an object.');
+    } else {
+      pushPositiveNumberError(errors, memoryV2.recall.maxRecords, 'memoryV2.recall.maxRecords');
+    }
+  }
+
   if (!isPlainObject(config.memory)) {
     errors.push('memory must be an object.');
   } else {

package/src/core/runtimePaths.js

@@ -4,6 +4,7 @@ export function buildRuntimePaths(projectRoot) {
   const runtimeRoot = path.join(projectRoot, '.ukit');
   const storageRoot = path.join(runtimeRoot, 'storage');
   const memoryRoot = path.join(storageRoot, 'memory');
+  const memoryV2Dir = path.join(memoryRoot, 'v2');
   const cacheRoot = path.join(storageRoot, 'cache');
 
   return {
@@ -11,6 +12,8 @@ export function buildRuntimePaths(projectRoot) {
     storageRoot,
     cacheRoot,
     memoryRoot,
+    memoryV2Dir,
+    memoryV2RecordsPath: path.join(memoryV2Dir, 'records.json'),
     teeCacheDir: path.join(cacheRoot, 'tee'),
     configPath: path.join(storageRoot, 'config.json'),
     promptCachePath: path.join(cacheRoot, 'prompt-cache.json'),

package/src/core/uninstall.js

@@ -16,7 +16,7 @@ import { PROJECT_IMPORTANT_FILENAME } from './projectImportant.js';
 // tracked/followed. Before any destructive uninstall step a regular source gets a
 // raw-byte backup beside it at the project root (never under .claude/.ukit/.codex/
 // .omp — those may be deleted): `<name>.ukit-backup`, then `.ukit-backup.1`, `.2`, …
-// via bounded exclusive-create collision walk. See docs/PROJECT_IMPORTANT_SPEC.md §15.
+// via bounded exclusive-create collision walk. See docs/archive/specs/PROJECT_IMPORTANT_SPEC.md §15.
 const IMPORTANT_BACKUP_SUFFIX = '.ukit-backup';
 const IMPORTANT_BACKUP_COLLISION_LIMIT = 100;
 

package/src/index/taskRouting.js

@@ -14,6 +14,34 @@ import {
 
 const MAX_ACTIVE_ROUTE_SKILLS = 2;
 
+// Declared complexity→docs mapping (DOC-201 FR-001). Canonical declaration lives in
+// manifests/documentation.yaml `context_layers`; this constant is the routing-side copy
+// (the router must not read the registry at runtime — zero new deps). Keep in sync.
+// `queued-task` is omitted v1: docs/TASKS.md does not exist in every repo (SPEC §14).
+// `shared-simple` mirrors the non-trivial layer to match deriveContextMode's FULL lane.
+const CONTEXT_LAYER_DOCS = {
+  taskTypes: {
+    trivial: [],
+    simple: ['docs/MEMORY.md'],
+    'non-trivial': ['docs/MEMORY.md', 'docs/PROJECT.md', 'docs/CODE_MAP.md'],
+    'shared-simple': ['docs/MEMORY.md', 'docs/PROJECT.md', 'docs/CODE_MAP.md'],
+  },
+  intents: {
+    'open-ended': ['docs/STATUS.md'],
+    'open-ended-status': ['docs/STATUS.md'],
+    handoff: ['docs/AI_HANDOFF/INDEX.md'],
+  },
+};
+const CONTEXT_DOCS_MAX = 4;
+
+function deriveContextDocs({ taskType = null, intentMode = null } = {}) {
+  const docs = [
+    ...(CONTEXT_LAYER_DOCS.taskTypes[taskType] ?? []),
+    ...(CONTEXT_LAYER_DOCS.intents[intentMode] ?? []),
+  ];
+  return unique(docs).slice(0, CONTEXT_DOCS_MAX);
+}
+
 export async function deriveTaskRoute({
   rootDir = process.cwd(),
   promptText = '',
@@ -206,6 +234,7 @@ export function buildRouteSummary({
   nextAction = null,
   handoffBudget = null,
   worklogBudget = null,
+  contextDocs = null,
 } = {}) {
   const autonomyLevel = routingContext.autonomyLevel ?? 'balanced';
   const delegationRecommendation = deriveDelegationRecommendation({
@@ -264,10 +293,19 @@ export function buildRouteSummary({
   );
   const nextActionCommand = compactHelperLane ? null : nextAction?.command ?? null;
   const handoffFile = routingContext.intentMode === 'handoff' ? 'docs/AI_HANDOFF/ACTIVE.md' : null;
+  // DOC-201 FR-002: resolved context-layer docs (declared in manifests/documentation.yaml).
+  // Explicit override wins; otherwise derive from taskType + intentMode.
+  const resolvedContextDocs = ((Array.isArray(contextDocs) ? contextDocs : null)
+    ?? deriveContextDocs({ taskType, intentMode: routingContext.intentMode ?? null }))
+    .slice(0, CONTEXT_DOCS_MAX);
+  const docsSegment = resolvedContextDocs.length > 0
+    ? `docs=[${resolvedContextDocs.slice(0, CONTEXT_DOCS_MAX).map((p) => path.posix.basename(String(p).replaceAll('\\', '/'))).join(',')}]`
+    : null;
   const summaryLine = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
     handoffFile ? `handoff=${handoffFile}` : null,
     formatCompactSegment('targets', primaryTargets),
+    docsSegment,
     formatCompactSegment('tests', relatedTests),
     formatCompactSegment('styles', styleFiles),
     editGuardHint ? `editGuard=${editGuardHint}` : null,
@@ -303,6 +341,7 @@ export function buildRouteSummary({
     nextActionCommand,
     helperHint,
     contextMode,
+    contextDocs: resolvedContextDocs,
     line: summaryLine || 'task=unknown',
   };
 }

package/src/render/instructionRenderer.js

@@ -0,0 +1,226 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+
+import { renderTemplateString } from './renderTemplate.js';
+
+/**
+ * Deterministic core/overlay renderer for the five instruction-contract
+ * outputs (SPEC §8.1, FR-004..FR-007). Pure functions; disk access only in
+ * renderInstructionsFromDisk / checkRenderedInstructions.
+ *
+ * Emission rules (byte-exact):
+ *   h1 + '\n' + banner + '\n\n' + blocks.join('') [+ trailer] [+ '\n']
+ * where each `## ` block is `## <heading>` + the raw body slice — the body
+ * keeps its leading AND trailing whitespace, so concatenation reproduces
+ * the source bytes exactly; the reserved
+ * `__preamble__` block is the source's leading non-## text verbatim.
+ */
+
+export const PREAMBLE_KEY = '__preamble__';
+
+const SECTION_HEADING_RE = /^## (.+)$/gm;
+const LEFTOVER_TOKEN_RE = /\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/;
+
+/**
+ * Split markdown into a Map<heading, body> at `## ` boundaries.
+ * `### ` and deeper stay inside the enclosing body. Leading non-## text lands
+ * under the reserved `__preamble__` key (absent when the file starts with `## `).
+ * Throws on a duplicate `## ` heading, naming it.
+ */
+export function parseSections(markdown) {
+  const sections = new Map();
+  const matches = [...markdown.matchAll(SECTION_HEADING_RE)];
+  const first = matches[0];
+
+  const preamble = first ? markdown.slice(0, first.index) : markdown;
+  if (preamble.trim().length > 0) {
+    // Raw slice kept verbatim: its trailing newline(s) are the separator
+    // before the first ## section (e.g. the RULES.md preamble block).
+    sections.set(PREAMBLE_KEY, preamble);
+  }
+
+  for (let i = 0; i < matches.length; i++) {
+    const m = matches[i];
+    const heading = m[1].trimEnd();
+    if (sections.has(heading)) {
+      throw new Error(`duplicate ## heading in source: ${heading}`);
+    }
+    const bodyStart = m.index + m[0].length;
+    const bodyEnd = i + 1 < matches.length ? matches[i + 1].index : markdown.length;
+    // Raw slice up to (not including) the next `## ` heading — leading AND
+    // trailing whitespace are byte-meaningful (marker line vs blank line
+    // under the heading; multi-blank separators between sections).
+    sections.set(heading, markdown.slice(bodyStart, bodyEnd));
+  }
+
+  return sections;
+}
+
+/**
+ * Render one layout output. `outputSpec` = layout.outputs[i];
+ * `sources` = { <sourceName>: Map<heading, body> }; `vars` = flat/nested
+ * variables applied when `outputSpec.resolve_vars` is true.
+ * Reserved specifiers: heading '__preamble__' emits the source's leading
+ * non-## block verbatim (no `## ` prefix); heading '*' expands to every
+ * `## ` section of that source in file order.
+ */
+export function renderOutput(outputSpec, sources, vars = {}) {
+  if (!Array.isArray(outputSpec.sections) || outputSpec.sections.length === 0) {
+    throw new Error(`output ${outputSpec.target}: sections must be a non-empty list`);
+  }
+
+  const blocks = [];
+  for (const ref of outputSpec.sections) {
+    const source = sources.get(ref.from);
+    if (!source) {
+      throw new Error(`output ${outputSpec.target}: unknown source '${ref.from}'`);
+    }
+    if (ref.heading === '*') {
+      for (const [heading, body] of source) {
+        if (heading === PREAMBLE_KEY) continue;
+        blocks.push(`## ${heading}${body}`);
+      }
+      continue;
+    }
+    if (ref.heading === PREAMBLE_KEY) {
+      if (!source.has(PREAMBLE_KEY)) {
+        throw new Error(
+          `output ${outputSpec.target}: source '${ref.from}' has no __preamble__ block`,
+        );
+      }
+      blocks.push(source.get(PREAMBLE_KEY));
+      continue;
+    }
+    if (!source.has(ref.heading)) {
+      throw new Error(
+        `output ${outputSpec.target}: heading '${ref.heading}' missing from source '${ref.from}'`,
+      );
+    }
+    blocks.push(`## ${ref.heading}${source.get(ref.heading)}`);
+  }
+
+  let out = `${outputSpec.h1}\n${outputSpec.banner}\n\n${blocks.join('')}`;
+  if (outputSpec.trailer !== undefined && outputSpec.trailer !== null && outputSpec.trailer !== '') {
+    if (!out.endsWith('\n')) out += '\n';
+    out += `${outputSpec.trailer}`;
+  }
+  if (!out.endsWith('\n')) out += '\n';
+
+  if (outputSpec.resolve_vars) {
+    out = renderTemplateString(out, vars);
+    const leftover = out.match(LEFTOVER_TOKEN_RE);
+    if (leftover) {
+      throw new Error(
+        `output ${outputSpec.target}: unresolved template variable '{{${leftover[1]}}}'`,
+      );
+    }
+  }
+  return out;
+}
+
+/**
+ * Render every output in `layout` from `sourceTexts` ({name: markdown}).
+ * Source names are looked up as `sources.get(ref.from)`; overlay sources are
+ * named `overlay:<file-stem>` by convention in renderInstructionsFromDisk.
+ * `varsByResolve` supplies variables to outputs with resolve_vars: true.
+ * FR-006 strictness: a `## ` section in any source referenced by zero outputs
+ * throws, naming the heading.
+ */
+export function renderAll(layout, sourceTexts, varsByResolve = {}) {
+  if (!layout || !Array.isArray(layout.outputs) || layout.outputs.length === 0) {
+    throw new Error('layout.outputs must be a non-empty list');
+  }
+
+  const sources = new Map(
+    Object.entries(sourceTexts).map(([name, text]) => [name, parseSections(text)]),
+  );
+
+  // Referenced-heading accounting for the unreferenced-section check.
+  const referenced = new Map(); // sourceName -> Set<heading>
+  const mark = (from, heading) => {
+    if (!referenced.has(from)) referenced.set(from, new Set());
+    referenced.get(from).add(heading);
+  };
+  for (const spec of layout.outputs) {
+    for (const ref of spec.sections || []) {
+      if (ref.heading === '*') {
+        const source = sources.get(ref.from);
+        if (!source) throw new Error(`unknown source '${ref.from}' referenced by '*'`);
+        for (const heading of source.keys()) {
+          if (heading !== PREAMBLE_KEY) mark(ref.from, heading);
+        }
+      } else if (ref.heading !== PREAMBLE_KEY) {
+        mark(ref.from, ref.heading);
+      }
+    }
+  }
+  for (const [name, source] of sources) {
+    for (const heading of source.keys()) {
+      if (heading === PREAMBLE_KEY) continue;
+      if (!referenced.get(name) || !referenced.get(name).has(heading)) {
+        throw new Error(`source '${name}': ## section '${heading}' referenced by zero outputs`);
+      }
+    }
+  }
+
+  const rendered = new Map();
+  for (const spec of layout.outputs) {
+    const vars = spec.resolve_vars ? varsByResolve : {};
+    rendered.set(spec.target, renderOutput(spec, sources, vars));
+  }
+  return rendered;
+}
+
+const SOURCE_FILES = {
+  core: 'templates/instructions/core.md',
+  'overlay:claude': 'templates/instructions/overlays/claude.md',
+  'overlay:agents': 'templates/instructions/overlays/agents.md',
+  'overlay:omp-rules': 'templates/instructions/overlays/omp-rules.md',
+  'overlay:repo': 'templates/instructions/overlays/repo.md',
+};
+
+/**
+ * Read layout + sources + repo-vars + package.json version from disk, render
+ * all outputs, and (write=true) write each target. Returns Map<target, content>.
+ */
+export async function renderInstructionsFromDisk({ repoRoot, write = true } = {}) {
+  const abs = (p) => path.join(repoRoot, p);
+  const layout = YAML.parse(
+    fs.readFileSync(abs('templates/instructions/layout.yaml'), 'utf8'),
+  );
+  const repoVars =
+    YAML.parse(fs.readFileSync(abs('templates/instructions/repo-vars.yaml'), 'utf8')) || {};
+  const pkg = JSON.parse(fs.readFileSync(abs('package.json'), 'utf8'));
+
+  const sourceTexts = {};
+  for (const [name, rel] of Object.entries(SOURCE_FILES)) {
+    sourceTexts[name] = fs.readFileSync(abs(rel), 'utf8');
+  }
+
+  const vars = { ...repoVars, ukit: { ...(repoVars.ukit || {}), version: pkg.version } };
+  const rendered = renderAll(layout, sourceTexts, vars);
+
+  if (write) {
+    for (const [target, content] of rendered) {
+      fs.writeFileSync(abs(target), content);
+    }
+  }
+  return rendered;
+}
+
+/**
+ * → string[] of drifted target paths (empty = clean). Drift means rendered
+ * bytes differ from disk bytes, or the target is missing.
+ */
+export async function checkRenderedInstructions({ repoRoot } = {}) {
+  const rendered = await renderInstructionsFromDisk({ repoRoot, write: false });
+  const drift = [];
+  for (const [target, content] of rendered) {
+    const file = path.join(repoRoot, target);
+    if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== content) {
+      drift.push(target);
+    }
+  }
+  return drift;
+}