@geraldmaron/construct 1.5.0 → 1.5.2

package/lib/orchestration/research-evidence-gate.mjs

@@ -0,0 +1,104 @@
+/**
+ * lib/orchestration/research-evidence-gate.mjs — deterministic evidence gate for
+ * research task output.
+ *
+ * The cx-researcher persona forbids fabrication and mandates honest
+ * insufficient-evidence, but that is honor-system enforcement (a persona prompt)
+ * — a weak model, including any free-tier host model, ignores it and ships a
+ * confident answer with no sources (construct-6yo6o: a Free-Models-Router session
+ * fabricated a whole "research" answer, zero citations, every web fetch failed).
+ *
+ * The deterministic backstop applies wherever a research task's output is
+ * finalized (provider AND host backends), independent of model tier — validating
+ * the OUTPUT, never the choice of model, so the user's free-model choice is
+ * honored (no paid escalation). Complements findUnverifiedCitations (which flags
+ * a cited URL absent from governed webEvidence) by catching the opposite gap: an
+ * answer that cites NOTHING of the evidence kind its own research mode requires.
+ *
+ * A substantial research answer that carries no citation of its expected kind is
+ * unverifiable and is flagged degraded rather than presented as done. It stays a
+ * signal, not a hard failure: the task still completes (the output exists), but a
+ * surface can see it was never grounded. An honestly short or self-declared
+ * insufficient-evidence answer is never penalized — that is the behavior the
+ * persona asks for.
+ */
+
+const RESEARCH_ROLES = new Set(['researcher', 'cx-researcher']);
+
+// Shorter answers are too brief to be a load-bearing research claim — an honest
+// "insufficient evidence" reply falls here and must pass untouched.
+const SUBSTANTIVE_MIN_CHARS = 500;
+
+const CODEBASE_HINTS = /\b(codebase|repo|repository|source code|source file|implementation|the code|this file|which function|call site|grep|trace (the|through)|execution path)\b/i;
+const UX_HINTS = /\b(user research|ux research|usability|interview|transcript|user journey|friction points?|jobs.to.be.done|personas?)\b/i;
+
+// An answer that declares its own limits is honest degradation, not fabrication,
+// and passes at any length.
+const SELF_DEGRADED = /insufficient evidence|could not (reach|verify|access|retrieve|confirm)|no (live )?web access|unable to (verify|reach|retrieve)|\[unverified\]|no verifiable sources?|without (live |web )?access/i;
+
+const URL_RE = /\bhttps?:\/\/[^\s)\]<>"']+/g;
+const DOI_ARXIV_RE = /\b(?:doi:\s*10\.\d{4,}|arxiv:\s*\d{4}\.\d{4,})/gi;
+const FILELINE_RE = /\b[\w./-]+\.[a-z0-9]{1,6}:\d+\b/gi;
+const TRANSCRIPT_RE = /\b(?:transcript|recording|interview|participant|session)\b[^.\n]{0,60}(?:\d{4}-\d{2}|#\d+|P\d+|\.(?:txt|md|vtt|srt|json))/gi;
+
+function countMatches(text, re) {
+  const m = String(text).match(re);
+  return m ? m.length : 0;
+}
+
+/**
+ * Infer which evidence kind a research request expects. Codebase questions cite
+ * file:line, user/UX questions cite transcripts, everything else cites external
+ * verifiable sources (URLs / DOIs / arXiv ids).
+ */
+export function inferEvidenceKind(request = '') {
+  const text = String(request || '');
+  if (CODEBASE_HINTS.test(text)) return 'codebase';
+  if (UX_HINTS.test(text)) return 'ux';
+  return 'external';
+}
+
+function countEvidenceForKind(output, kind) {
+  if (kind === 'codebase') return countMatches(output, FILELINE_RE);
+  if (kind === 'ux') return countMatches(output, TRANSCRIPT_RE);
+  return countMatches(output, URL_RE) + countMatches(output, DOI_ARXIV_RE);
+}
+
+const KIND_REMEDIATION = {
+  external: 'cite at least one verifiable primary source (a fetched URL, DOI, or arXiv id)',
+  codebase: 'cite at least one file:line reference from a read you performed',
+  ux: 'cite at least one transcript, recording, or participant reference',
+};
+
+/**
+ * Gate a research task's output on evidence presence.
+ *
+ * @param {{output?: string, role?: string, request?: string}} params
+ * @returns {{applicable: boolean, ok: boolean, kind: string|null, citationCount: number, reason: string|null}}
+ */
+export function gateResearchEvidence({ output = '', role = '', request = '' } = {}) {
+  const normalizedRole = String(role || '').replace(/^cx-/, '');
+  if (!RESEARCH_ROLES.has(normalizedRole) && !RESEARCH_ROLES.has(String(role || ''))) {
+    return { applicable: false, ok: true, kind: null, citationCount: 0, reason: null };
+  }
+
+  const text = String(output || '');
+  const kind = inferEvidenceKind(request);
+
+  if (text.trim().length < SUBSTANTIVE_MIN_CHARS || SELF_DEGRADED.test(text)) {
+    return { applicable: true, ok: true, kind, citationCount: countEvidenceForKind(text, kind), reason: null };
+  }
+
+  const citationCount = countEvidenceForKind(text, kind);
+  if (citationCount > 0) {
+    return { applicable: true, ok: true, kind, citationCount, reason: null };
+  }
+
+  return {
+    applicable: true,
+    ok: false,
+    kind,
+    citationCount: 0,
+    reason: `${kind}-research output carries no verifiable citation — ${KIND_REMEDIATION[kind]}, or return insufficient-evidence instead of an unsourced answer`,
+  };
+}

package/lib/orchestration/runtime.mjs

@@ -59,9 +59,11 @@ import { resolveRunStore, projectKey } from './store.mjs';
 import { resolveTraceStore } from './trace-store.mjs';
 import { runTaskViaProvider, materializeTaskPrompt, INLINE, PROVIDER, HOST, WORKER_BACKEND_SET } from './worker.mjs';
 import { roleHoldsWebCapability } from './web-capability.mjs';
+import { gateResearchEvidence } from './research-evidence-gate.mjs';
 import { emitRunEvent, isCancelRequested, clearCancel } from './events.mjs';
 import { getDeploymentMode } from '../deployment-mode.mjs';
 import { resolveTenantContext } from '../tenant/context.mjs';
+import { resolveContextBindings } from './context-bindings.mjs';
 
 export const WORKER_BACKENDS = WORKER_BACKEND_SET;
 export const DEFAULT_WORKER_BACKEND = INLINE;
@@ -203,10 +205,16 @@ export async function planRun(request = {}, { env = process.env, cwd = process.c
   const {
     request: text = '', workflowType = null, requestedStrategy = 'auto', useConstruct = true,
     host = null, hostModel = null, hostProvider = null, fileCount = 0, moduleCount = 0,
-    workerBackend: explicitWorkerBackend = null,
+    workerBackend: explicitWorkerBackend = null, contextTargets = null,
   } = request;
 
   const { config, configWarnings } = loadConfigWithWarnings(cwd, env);
+
+  // Context-target bindings (B4) are validated here, before any task is built or
+  // any run record is saved, so an unknown id fails the whole plan closed rather
+  // than persisting a run bound to context it cannot reach. Omission resolves to
+  // an empty list and leaves today's implicit source resolution untouched.
+  const contextBindings = resolveContextBindings(contextTargets, { config, env, cwd });
   const { store, warnings: storeWarnings, degraded: storeDegraded, degradedReason: storeDegradedReason } = resolveRunStore({ config, env, cwd });
   if (storeDegraded) {
     process.stderr.write(`[construct] orchestration store degraded (${storeDegradedReason ?? 'unknown'}): ${storeWarnings.join('; ')}\n`);
@@ -261,6 +269,9 @@ export async function planRun(request = {}, { env = process.env, cwd = process.c
     warnings: [...(execData.warnings || []), ...storeWarnings, ...configWarnings],
     semantics: RUNTIME_SEMANTICS,
     executionSemantics: execData.semantics,
+    // Only present when the run was given explicit context targets, so a run
+    // without them stays byte-identical to a pre-B4 record (R1/AC3).
+    ...(contextBindings.length ? { contextBindings } : {}),
   };
 
   await store.saveRun(run);
@@ -289,6 +300,23 @@ function prepareTaskInline(task) {
   if (roleHoldsWebCapability(task.role)) task.webCapability = 'prepare-only';
 }
 
+// Deterministic evidence gate on a finalized research task, applied to both the
+// provider and host backends so the model tier is irrelevant. A substantial
+// cx-researcher answer with no citation of its expected kind is marked degraded
+// (evidenceGate.ok=false) rather than presented as verified — the persona's
+// no-fabrication contract is honor-system, so the gate is the enforcement.
+
+function applyResearchEvidenceGate(task, run) {
+  const verdict = gateResearchEvidence({
+    output: task.output,
+    role: task.role,
+    request: run?.request?.summary || run?.request || '',
+  });
+  if (!verdict.applicable) return;
+  task.evidenceGate = { ok: verdict.ok, kind: verdict.kind, citationCount: verdict.citationCount };
+  if (!verdict.ok) task.evidenceGate.reason = verdict.reason;
+}
+
 // The provider backend executes one task against the configured model. A failed
 // task is recorded (status `failed`, task.error) and does not abort the run, so
 // one specialist failure cannot lose the work of the others.
@@ -305,6 +333,7 @@ async function executeTaskViaProvider(task, run, env, fetchImpl, chainOfThought,
     task.executor = `provider:${result.provider}:${result.model}`;
     task.status = 'done';
     task.finishedAt = new Date().toISOString();
+    applyResearchEvidenceGate(task, run);
 
     // Web-capable execution records which grant mode reached (or did not reach) the web
     // and the F08-governed evidence gathered, so a host never has to infer it (ADR-0050).
@@ -695,6 +724,7 @@ export async function submitHostTaskResult(cwd, runId, taskId, result = {}, { en
   task.status = 'done';
   task.finishedAt = new Date().toISOString();
   task.executionState = 'executed';
+  applyResearchEvidenceGate(task, run);
   // Host-reported, never independently verified — the distinguishing marker a
   // reader needs so this never looks like a construct-verified provider
   // execution (which carries no provenanceSource field at all).
@@ -807,10 +837,14 @@ export function hostAdapterMetadata(run) {
       // a host-reported one.
       ...(t.provenanceSource ? { provenanceSource: t.provenanceSource } : {}),
       ...(t.hostPrompt ? { hostPrompt: t.hostPrompt } : {}),
+      ...(t.evidenceGate ? { evidenceGate: t.evidenceGate } : {}),
     })),
     warnings: run.warnings || [],
     semantics: run.semantics,
     executionSemantics: run.executionSemantics,
+    // Resolved context-target bindings (B4): a typed absence for a run planned
+    // without them, so an inspecting host never infers bindings that weren't set.
+    contextBindings: run.contextBindings ?? [],
   };
 }
 

package/lib/orchestration/worker.mjs

@@ -143,6 +143,15 @@ function classifyWorkerProvider(provider, model) {
   const p = (provider || '').toLowerCase();
   if (p === 'github-copilot' || /^github-copilot\//.test(model || '')) return 'github-copilot';
   if (p === 'openai') return 'openai';
+
+  // A model served through OpenRouter carries an explicit `openrouter/` slug (or
+  // the caller names openrouter), so it dispatches to OpenRouter even when the
+  // underlying family is Anthropic/Claude — the prefix wins over the isAnthropic
+  // substring heuristic, symmetric with how `openai/*` slugs stay on OpenRouter
+  // unless provider is explicitly `openai`. Without this, openrouter/anthropic/
+  // claude-* misroutes to the direct Anthropic endpoint (construct-olpf).
+
+  if (/^openrouter\//.test(model || '') || p.startsWith('openrouter')) return 'openrouter';
   if (isAnthropic(provider, model)) return 'anthropic';
   return 'openrouter';
 }

package/lib/providers/directory/index.mjs

@@ -10,14 +10,18 @@
  *
  * Config (per call):
  *   - root: absolute or relative path to the directory root (required)
- *   - include: array of minimatch glob patterns (optional, defaults to ["**\/*"])
- *   - exclude: array of minimatch glob patterns to filter out (optional)
+ *   - include: array of glob patterns (optional, defaults to ["**\/*"])
+ *   - exclude: array of glob patterns to filter out (optional)
  *   - maxFileKB: integer max file size in KB (default 1024, max 10240)
+ *
+ * Glob support is the in-tree subset (ADR-0001, lib/rules-delivery.mjs):
+ * `**\/` spans directories, `*` stays within a segment, and a pattern without
+ * a slash matches basenames (`*.md` matches nested files).
  */
 
 import { existsSync, statSync, readdirSync, readFileSync } from 'node:fs';
 import { resolve, relative, isAbsolute } from 'node:path';
-import { minimatch } from 'minimatch';
+import { globToRegExp } from '../../rules-delivery.mjs';
 
 /**
  * Verify that path is within root and not a symlink escape.
@@ -74,6 +78,14 @@ function resolvePath(root, candidate) {
   return { ok: true, path: resolved, root: rootPath };
 }
 
+// A pattern without a slash tests the basename so `*.md` matches nested files,
+// mirroring the matchBase behavior read() and search() have always documented.
+
+function compileMatchers(patterns) {
+  const compiled = patterns.map((pat) => ({ re: globToRegExp(pat), baseOnly: !pat.includes('/') }));
+  return (relativePath, name) => compiled.some(({ re, baseOnly }) => re.test(baseOnly ? name : relativePath));
+}
+
 /**
  * Walk directory recursively, matching include/exclude globs.
  */
@@ -82,6 +94,9 @@ function walkDir(dirPath, { include = ['**/*'], exclude = [] }) {
   const stat = statSync(dirPath);
   if (!stat.isDirectory()) return results;
 
+  const includes = compileMatchers(include);
+  const excludes = compileMatchers(exclude);
+
   function walk(dir, prefix = '') {
     let entries;
     try {
@@ -97,10 +112,7 @@ function walkDir(dirPath, { include = ['**/*'], exclude = [] }) {
       if (entry.isDirectory()) {
         walk(fullPath, relativePath);
       } else if (entry.isFile()) {
-        const matches = include.some((pat) => minimatch(relativePath, pat, { matchBase: true }));
-        const excludes = exclude.some((pat) => minimatch(relativePath, pat, { matchBase: true }));
-
-        if (matches && !excludes) {
+        if (includes(relativePath, entry.name) && !excludes(relativePath, entry.name)) {
           results.push({ path: fullPath, relativePath, name: entry.name });
         }
       }

package/lib/setup.mjs

@@ -26,6 +26,7 @@ import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 
 import { ensureUserConfigDir, getUserEnvPath, writeEnvValues } from './env-config.mjs';
+import { MODEL_TIERS } from './model-tiers.mjs';
 import { migrateLegacyModelConfig, migrateLegacyCredentialConfig } from './config/legacy-config-migration.mjs';
 import { configDir, stateDir, doctorRoot } from './config/xdg.mjs';
 import { DEFAULT_WORKSPACE_PATH, WORKSPACE_DOCS_LANES } from './embed/config.mjs';
@@ -536,7 +537,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
         const { applyToEnv } = await import('./model-router.mjs');
         const selections = await selectCheapestForAllTiers({ env: process.env });
         const applied = {};
-        for (const tier of ['reasoning', 'standard', 'fast']) {
+        for (const tier of MODEL_TIERS) {
           if (selections[tier]?.modelId) applied[tier] = selections[tier].modelId;
         }
         if (Object.keys(applied).length > 0) {

package/lib/sources/content-roots.mjs

@@ -0,0 +1,147 @@
+/**
+ * lib/sources/content-roots.mjs — resolve content-capable source targets to
+ * on-disk roots for multi-root knowledge corpus builders (bead construct-760c.2).
+ *
+ * A target contributes a filesystem content root when its provider manifest
+ * declares content capability and the concrete content exists on disk:
+ *   - directory targets — the manifest selector declares `existsAs: 'directory'`,
+ *     so the tilde-expanded path IS the root (no cache, always local).
+ *   - corpus targets — the manifest declares a `content` descriptor and the
+ *     selector opts into corpus mode (github: content.mode === 'corpus'); the
+ *     root is the state-root repo cache populated by `construct sources sync`.
+ *     A corpus target with no cache yet resolves to nothing (nothing to index).
+ *
+ * Capability is keyed off manifest descriptors, never a hardcoded provider name,
+ * matching the registry pattern in lib/config/source-target-registry.mjs. Adding
+ * a future git-hosted content provider means declaring its manifest `content`
+ * block, not editing this file.
+ *
+ * Every root carries an `origin` — {targetId, provider, projectKey, ref} — which
+ * the corpus builders stamp onto each chunk (adding per-file `relPath`) so
+ * cross-project retrieval can attribute and filter results by source project.
+ * The host project itself is the reserved origin: targetId null, projectKey
+ * `self`. `--projects=self` selects it.
+ */
+
+import { statSync } from 'node:fs';
+import path from 'node:path';
+
+import { getSourceTargetDescriptor } from '../config/source-target-registry.mjs';
+import { expandTilde, resolveEffectiveSourceTargetsFromConfig } from '../config/source-targets.mjs';
+import { isCorpusTarget, corpusCacheDir, corpusFreshness } from './repo-cache.mjs';
+
+export const SELF_PROJECT_KEY = 'self';
+
+function isDirectoryTarget(target) {
+  const descriptor = getSourceTargetDescriptor(target?.provider);
+  return descriptor?.selector?.existsAs === 'directory';
+}
+
+/**
+ * Does this target declare any content capability at all (directory or corpus)?
+ * Expands `--projects=all` to the content-eligible target set.
+ */
+export function isContentCapableTarget(target) {
+  return isDirectoryTarget(target) || isCorpusTarget(target);
+}
+
+function directoryRoot(target) {
+  const descriptor = getSourceTargetDescriptor(target.provider);
+  const raw = target.selector?.[descriptor.selector.field];
+  if (!raw) return null;
+  const dir = expandTilde(String(raw));
+  try {
+    if (!statSync(dir).isDirectory()) return null;
+  } catch {
+    return null;
+  }
+  return { dir, ref: null };
+}
+
+function corpusRoot(target, projectRoot) {
+  const freshness = corpusFreshness(target, { projectRoot });
+  if (!freshness.cached) return null;
+  return { dir: corpusCacheDir(target, { projectRoot }), ref: freshness.ref ?? null };
+}
+
+/**
+ * Resolve content-capable targets to concrete on-disk roots. Targets whose
+ * content is not present (a directory that vanished, a corpus never synced) are
+ * silently omitted — there is nothing to index — so callers get only roots they
+ * can actually walk.
+ *
+ * @param {object[]} targets      effective source targets (post-merge)
+ * @param {object} [opts]
+ * @param {string} [opts.projectRoot]
+ * @returns {{dir: string, origin: {targetId: string, provider: string, projectKey: string, ref: string|null}}[]}
+ */
+export function resolveContentRoots(targets = [], { projectRoot = process.cwd() } = {}) {
+  const roots = [];
+  for (const target of targets) {
+    let resolved = null;
+    if (isDirectoryTarget(target)) resolved = directoryRoot(target);
+    else if (isCorpusTarget(target)) resolved = corpusRoot(target, projectRoot);
+    if (!resolved) continue;
+    roots.push({
+      dir: resolved.dir,
+      origin: {
+        targetId: target.id,
+        provider: target.provider,
+        projectKey: target.id,
+        ref: resolved.ref,
+      },
+    });
+  }
+  return roots;
+}
+
+/**
+ * Convenience wrapper: resolve content roots straight from a loaded project
+ * config (merging in legacy env targets exactly as the rest of the pipeline does).
+ */
+export function resolveContentRootsFromConfig(config, { projectRoot = process.cwd(), env = process.env } = {}) {
+  const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
+  return resolveContentRoots(targets, { projectRoot });
+}
+
+/**
+ * Expand a `--projects=` / `projects` filter spec into the set of origin
+ * targetIds it selects. Accepts a CSV string or an array. Semantics:
+ *   - `all`  → every content-capable target id (host not included).
+ *   - `self` → the reserved host project key.
+ *   - a target id → that id, which must exist and be content-capable.
+ * An unknown or non-content-capable id is a hard error (never a silent empty
+ * result), per R3.
+ *
+ * @returns {{ ids: Set<string>, includeSelf: boolean }}
+ * @throws {Error} on an unknown id, with a message listing the known ids.
+ */
+export function expandProjectsFilter(spec, targets = []) {
+  const tokens = (Array.isArray(spec) ? spec : String(spec ?? '').split(','))
+    .map((s) => String(s).trim())
+    .filter(Boolean);
+
+  const contentTargets = targets.filter(isContentCapableTarget);
+  const knownById = new Map(contentTargets.map((t) => [t.id, t]));
+
+  const ids = new Set();
+  let includeSelf = false;
+
+  for (const token of tokens) {
+    if (token === 'all') {
+      for (const t of contentTargets) ids.add(t.id);
+      continue;
+    }
+    if (token === SELF_PROJECT_KEY) {
+      includeSelf = true;
+      continue;
+    }
+    if (!knownById.has(token)) {
+      const known = [SELF_PROJECT_KEY, 'all', ...knownById.keys()];
+      throw new Error(`unknown project "${token}" — known projects: ${known.join(', ')}`);
+    }
+    ids.add(token);
+  }
+
+  return { ids, includeSelf };
+}

package/lib/sources/repo-cache.mjs

@@ -0,0 +1,142 @@
+/**
+ * lib/sources/repo-cache.mjs — local content cache for corpus source targets.
+ *
+ * A source target opts into a full-content corpus by declaring its provider
+ * manifest's `content` descriptor shape in the selector (github: `content:
+ * {mode:"corpus", ref?}`). Eligibility is keyed off that manifest `content`
+ * descriptor, never a hardcoded `provider === 'github'` check, so any future
+ * git-hosted provider that declares a `content` block gets caching for free
+ * (bead construct-760c.1 R5).
+ *
+ * The checkout lives only under the ADR-0066 machine state root
+ * (`~/.construct/projects/<key>/context-repos/<targetId>/`, resolved through
+ * lib/state-root.mjs) — never in the project tree, so `construct init` never
+ * scaffolds it. A sibling `<targetId>.meta.json` records the remote, ref,
+ * resolved HEAD, sync mode, and last-fetch timestamp for freshness/TTL
+ * reporting. The first sync clones shallow (`--depth 1`); every subsequent
+ * sync fetches into the existing `.git` (incremental, re-run-safe — R4).
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { resolveStateDir, resolveStatePath } from '../state-root.mjs';
+import { getSourceTargetDescriptor, renderTemplate } from '../config/source-target-registry.mjs';
+
+export const DEFAULT_CORPUS_TTL_MS = 24 * 60 * 60 * 1000;
+
+function contentDescriptor(target) {
+  const descriptor = getSourceTargetDescriptor(target?.provider);
+  return descriptor?.content ? { descriptor, content: descriptor.content } : null;
+}
+
+/**
+ * Is this target opted into corpus caching? True only when its provider
+ * manifest declares a `content` descriptor and the target's selector sets that
+ * descriptor's mode field to the corpus value.
+ */
+export function isCorpusTarget(target) {
+  const found = contentDescriptor(target);
+  if (!found) return false;
+  const block = target.selector?.[found.content.field];
+  return !!block && block[found.content.modeField] === found.content.modeValue;
+}
+
+/**
+ * Resolve the git remote URL for a corpus target: an explicit `remote` in the
+ * content selector — a local `file://` bare repo, say — wins over the
+ * manifest's `remoteTemplate` rendered from the selector value.
+ */
+export function resolveCorpusRemote(target) {
+  const found = contentDescriptor(target);
+  if (!found) return null;
+  const { descriptor, content } = found;
+  const block = target.selector?.[content.field] ?? {};
+  if (content.remoteField && block[content.remoteField]) return String(block[content.remoteField]);
+  const value = target.selector?.[descriptor.selector.field];
+  if (!value || !content.remoteTemplate) return null;
+  return renderTemplate(content.remoteTemplate, { value });
+}
+
+function corpusRef(target) {
+  const found = contentDescriptor(target);
+  const block = target.selector?.[found.content.field] ?? {};
+  return block[found.content.refField] || found.content.defaultRef;
+}
+
+export function corpusCacheDir(target, { projectRoot = process.cwd(), ensureDir = false } = {}) {
+  return resolveStateDir(projectRoot, 'context-repos', target.id, { ensureDir });
+}
+
+function metaPathFor(target, projectRoot, { ensureDir = false } = {}) {
+  return resolveStatePath(projectRoot, 'context-repos', `${target.id}.meta.json`, { ensureDir });
+}
+
+export function readCorpusMeta(target, { projectRoot = process.cwd() } = {}) {
+  try {
+    return JSON.parse(fs.readFileSync(metaPathFor(target, projectRoot), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Freshness view for a corpus target: whether a cache exists, its last-fetch
+ * timestamp, and whether it is older than `ttlMs`. Drives `sources list`.
+ */
+export function corpusFreshness(target, { projectRoot = process.cwd(), ttlMs = DEFAULT_CORPUS_TTL_MS, now = Date.now() } = {}) {
+  const dir = corpusCacheDir(target, { projectRoot });
+  const cached = fs.existsSync(path.join(dir, '.git'));
+  const meta = readCorpusMeta(target, { projectRoot });
+  const lastFetch = meta?.lastFetch ?? null;
+  const ageMs = lastFetch ? now - Date.parse(lastFetch) : null;
+  const stale = ageMs == null ? cached : ageMs > ttlMs;
+  return { cached, lastFetch, ageMs, stale, ref: meta?.ref ?? corpusRef(target), head: meta?.head ?? null, dir };
+}
+
+/**
+ * Clone (first run) or fetch (subsequent runs) a corpus target's content into
+ * its state-root cache and record freshness metadata. Incremental and
+ * re-run-safe: an existing `.git` takes the fetch path, so objects are reused
+ * rather than re-cloned. `git` is injectable purely for testing; production
+ * uses the real git binary via execFileSync.
+ */
+export function syncCorpusTarget(target, { projectRoot = process.cwd(), git = runGit, now = () => new Date().toISOString() } = {}) {
+  if (!isCorpusTarget(target)) {
+    throw new Error(`target ${target.id} is not a corpus target`);
+  }
+  const remote = resolveCorpusRemote(target);
+  if (!remote) throw new Error(`target ${target.id} has no resolvable corpus remote`);
+  const ref = corpusRef(target);
+  const dir = corpusCacheDir(target, { projectRoot });
+  const gitDir = path.join(dir, '.git');
+
+  let mode;
+  if (fs.existsSync(gitDir)) {
+    git(['-C', dir, 'fetch', '--depth', '1', 'origin', ref]);
+    git(['-C', dir, 'checkout', '-f', 'FETCH_HEAD']);
+    mode = 'fetch';
+  } else {
+    fs.mkdirSync(dir, { recursive: true });
+    git(['clone', '--depth', '1', '--branch', ref, remote, dir]);
+    mode = 'clone';
+  }
+
+  const head = git(['-C', dir, 'rev-parse', 'HEAD']).trim();
+  const meta = {
+    targetId: target.id,
+    provider: target.provider,
+    remote,
+    ref,
+    head,
+    mode,
+    lastFetch: now(),
+  };
+  fs.writeFileSync(metaPathFor(target, projectRoot, { ensureDir: true }), `${JSON.stringify(meta, null, 2)}\n`);
+  return { ...meta, dir };
+}
+
+function runGit(args) {
+  return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}

package/lib/template-registry.mjs

@@ -54,6 +54,7 @@ export const TEMPLATE_OWNERSHIP_EXEMPTIONS = new Set([
   'construct_guide',
   'onboarding',
   'memo',
+  'adhoc',
   'skill-artifact',
   'persona-artifact',
   'customer-profile',
@@ -69,4 +70,5 @@ export const TEMPLATE_OWNERSHIP_EXEMPTIONS = new Set([
   'prd-platform',
   'prd-business',
   'README',
+  'strategy-comparison',
 ]);

package/lib/test-corpus-inventory.mjs

@@ -80,6 +80,7 @@ export function defaultCorpusInventoryPath(rootDir = process.cwd()) {
 }
 
 function listTestFiles(testsDir) {
+  if (!fs.existsSync(testsDir)) return [];
   const files = [];
   const walk = (dir) => {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {