@geraldmaron/construct 1.5.0 → 1.5.2

package/lib/artifact-manifest-overlay.mjs

@@ -0,0 +1,273 @@
+/**
+ * lib/artifact-manifest-overlay.mjs — project/user tier overlays and the
+ * sanctioned `adhoc` type for the artifact capability manifest.
+ *
+ * The builtin manifest (specialists/artifact-manifest.json) is the shipped
+ * source of truth and is never modified. A user may extend the registered
+ * document classes two ways without touching the builtin:
+ *
+ *   - Register a custom type with `construct templates register <type>`, which
+ *     writes a project-tier overlay entry here and a matching template file
+ *     under .construct/templates/docs/<type>.md.
+ *   - Author a one-off `adhoc` artifact, a code-level sanctioned type injected
+ *     at load time so it resolves with zero prior registration.
+ *
+ * Overlays merge over the builtin by the same three-tier precedence the
+ * extension loader uses (builtin < user < project), deep-merged per type so an
+ * overlay may tweak a single field. The sanctioned adhoc entry sits below the
+ * builtin so a builtin type of the same name would always win.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Project-local config dir, mirroring lib/extensions/loader.mjs (project tier
+// = <rootDir>/.cx/). Kept as a local constant so this module has no dependency
+// on the config-dir consolidation that postdates staging.
+
+const PROJECT_CONFIG_DIR = '.cx';
+
+function configPath(projectRoot, ...segments) {
+  return path.join(projectRoot, PROJECT_CONFIG_DIR, ...segments);
+}
+
+export const ADHOC_TYPE = 'adhoc';
+export const OVERLAY_FILENAME = 'artifact-manifest.overlay.json';
+
+// The adhoc type is instructions-driven: no fixed structure, so its release
+// gate keeps the quality checks (structural lint runs against an empty section
+// set, citation discipline, a one-paragraph prose floor) while leaving the
+// document shape free-form. Free-form structure, not free-form quality.
+
+export const SANCTIONED_ARTIFACTS = Object.freeze({
+  [ADHOC_TYPE]: {
+    template: 'templates/docs/adhoc.md',
+    documentClass: ADHOC_TYPE,
+    description: 'Sanctioned one-off artifact: structure follows the supplied instructions, quality gates still apply.',
+    primaryOwners: ['cx-product-manager', 'cx-operations'],
+    toneDefault: 'direct',
+    toneAllowed: ['direct', 'executive-concise', 'friendly'],
+    aliases: ['ad-hoc', 'free-form', 'freeform'],
+    structureRequirements: [],
+    visualRequirements: [],
+    researchProfile: null,
+    outputDir: 'docs/adhoc',
+    releaseGate: {
+      structuralLint: true,
+      citationLint: true,
+      proseMinimum: 1,
+      requiredReviewers: [],
+      optionalReviewers: [],
+    },
+  },
+});
+
+function homeFromEnv(homeDir) {
+  return homeDir ?? (process.env.HOME || process.env.USERPROFILE || '');
+}
+
+/**
+ * Canonical overlay file paths for the user and project tiers.
+ *
+ * @param {{ cwd?: string, homeDir?: string }} [opts]
+ * @returns {{ user: string|null, project: string }}
+ */
+export function overlayPaths({ cwd = process.cwd(), homeDir } = {}) {
+  const home = homeFromEnv(homeDir);
+  return {
+    user: home ? path.join(home, '.config', 'construct', OVERLAY_FILENAME) : null,
+    project: configPath(cwd, OVERLAY_FILENAME),
+  };
+}
+
+function readOverlayArtifacts(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return parsed && typeof parsed.artifacts === 'object' && parsed.artifacts ? parsed.artifacts : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// Deep-merge per artifact type so an overlay entry may override a single field
+// (e.g. outputDir) without restating the whole entry. Arrays replace wholesale
+// — a caller redefining structureRequirements means the full new list.
+
+function mergeEntry(base, next) {
+  if (!isPlainObject(base)) return structuredClone(next);
+  if (!isPlainObject(next)) return structuredClone(next);
+  const out = { ...base };
+  for (const [key, value] of Object.entries(next)) {
+    out[key] = isPlainObject(value) && isPlainObject(out[key]) ? mergeEntry(out[key], value) : structuredClone(value);
+  }
+  return out;
+}
+
+function mergeArtifactLayers(...layers) {
+  const merged = {};
+  for (const layer of layers) {
+    if (!isPlainObject(layer)) continue;
+    for (const [type, entry] of Object.entries(layer)) {
+      merged[type] = mergeEntry(merged[type], entry);
+    }
+  }
+  return merged;
+}
+
+/**
+ * Merge the sanctioned, user-overlay, and project-overlay artifact maps onto a
+ * builtin manifest's artifacts, returning a new manifest object. The builtin
+ * top-level fields (version, description, workflowDefaults) are preserved.
+ *
+ * @param {object} builtinManifest
+ * @param {{ cwd?: string, homeDir?: string }} [opts]
+ * @returns {object}
+ */
+export function applyArtifactOverlays(builtinManifest, { cwd = process.cwd(), homeDir } = {}) {
+  const paths = overlayPaths({ cwd, homeDir });
+  const userArtifacts = readOverlayArtifacts(paths.user);
+  const projectArtifacts = readOverlayArtifacts(paths.project);
+  const artifacts = mergeArtifactLayers(
+    SANCTIONED_ARTIFACTS,
+    builtinManifest.artifacts ?? {},
+    userArtifacts,
+    projectArtifacts,
+  );
+  return { ...builtinManifest, artifacts };
+}
+
+/**
+ * A cheap signature over the overlay files so the manifest cache invalidates
+ * when a user registers a type or edits an overlay within one long-running
+ * process (the MCP server). Missing files contribute a stable zero.
+ *
+ * @param {{ cwd?: string, homeDir?: string }} [opts]
+ * @returns {string}
+ */
+export function overlaySignature({ cwd = process.cwd(), homeDir } = {}) {
+  const { user, project } = overlayPaths({ cwd, homeDir });
+  return [user, project]
+    .map((p) => {
+      if (!p) return 'x:0';
+      try {
+        const stat = fs.statSync(p);
+        return `${p}:${stat.mtimeMs}`;
+      } catch {
+        return `${p}:0`;
+      }
+    })
+    .join('|');
+}
+
+function slugType(type) {
+  return String(type ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Memo-like defaults per R2: a custom type resolves a sensible author/reviewer
+// chain and a standard release gate unless the overlay entry overrides them.
+
+function defaultOverlayEntry(type, { description, template } = {}) {
+  return {
+    template: template ?? `templates/docs/${type}.md`,
+    documentClass: type,
+    description: description || `Custom document class: ${type}`,
+    primaryOwners: ['cx-product-manager', 'cx-operations'],
+    toneDefault: 'direct',
+    toneAllowed: ['direct', 'executive-concise', 'friendly'],
+    structureRequirements: [],
+    visualRequirements: [],
+    researchProfile: null,
+    releaseGate: {
+      structuralLint: true,
+      citationLint: true,
+      proseMinimum: 1,
+      requiredReviewers: [],
+      optionalReviewers: [],
+    },
+    registeredBy: 'construct templates register',
+    registeredAt: new Date().toISOString().slice(0, 10),
+  };
+}
+
+const DEFAULT_TEMPLATE_SKELETON = (type, description) => `# {title}
+
+<!-- ${description || `Custom ${type} document`} · registered via \`construct templates register ${type}\` -->
+
+## Summary
+
+One-paragraph overview of what this document decides or communicates, in enough
+detail that the release gate's prose floor is met. Replace this text.
+
+## Details
+
+Expand the substance here. Cite sources with links or mark unverified claims
+with [unverified] so the citation gate passes.
+
+## Next steps
+
+- Action or decision requested
+`;
+
+/**
+ * Register a custom document class in the project tier: write the template file
+ * under .construct/templates/docs/<type>.md and add or update the type's entry
+ * in the project overlay. The builtin manifest is never touched.
+ *
+ * @param {object} args
+ * @param {string} args.type
+ * @param {string} [args.description]
+ * @param {string} [args.from]        path to a template file to seed the override
+ * @param {string} [args.cwd]
+ * @param {string} [args.homeDir]
+ * @param {boolean} [args.force]      overwrite an existing template file
+ * @returns {{ type: string, overlayPath: string, templatePath: string, existed: boolean }}
+ */
+export function registerArtifactType({ type, description, from, cwd = process.cwd(), homeDir, force = false } = {}) {
+  const safeType = slugType(type);
+  if (!safeType) throw new Error('type is required (letters, digits, dot, dash, underscore)');
+
+  const templatePath = configPath(cwd, 'templates', 'docs', `${safeType}.md`);
+  const existed = fs.existsSync(templatePath);
+  fs.mkdirSync(path.dirname(templatePath), { recursive: true });
+
+  let templateBody;
+  if (from) {
+    const src = path.resolve(cwd, from);
+    if (!fs.existsSync(src)) throw new Error(`--from template not found: ${from}`);
+    templateBody = fs.readFileSync(src, 'utf8');
+  } else if (!existed || force) {
+    templateBody = DEFAULT_TEMPLATE_SKELETON(safeType, description);
+  }
+  if (templateBody !== undefined && (!existed || force || from)) {
+    fs.writeFileSync(templatePath, templateBody.endsWith('\n') ? templateBody : `${templateBody}\n`);
+  }
+
+  const { project: overlayPath } = overlayPaths({ cwd, homeDir });
+  fs.mkdirSync(path.dirname(overlayPath), { recursive: true });
+  let overlay = { version: 1, artifacts: {} };
+  if (fs.existsSync(overlayPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(overlayPath, 'utf8'));
+      if (isPlainObject(parsed)) {
+        overlay = { version: parsed.version ?? 1, artifacts: isPlainObject(parsed.artifacts) ? parsed.artifacts : {} };
+      }
+    } catch {
+      overlay = { version: 1, artifacts: {} };
+    }
+  }
+  const prior = isPlainObject(overlay.artifacts[safeType]) ? overlay.artifacts[safeType] : null;
+  overlay.artifacts[safeType] = mergeEntry(defaultOverlayEntry(safeType, { description }), prior || {});
+  if (description) overlay.artifacts[safeType].description = description;
+  fs.writeFileSync(overlayPath, `${JSON.stringify(overlay, null, 2)}\n`);
+
+  return { type: safeType, overlayPath, templatePath, existed };
+}

package/lib/artifact-manifest.mjs

@@ -12,6 +12,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveActiveScope } from './scopes/loader.mjs';
 import { COMPLETION_STATES, isCompletionState } from './artifact-completion-states.mjs';
+import { applyArtifactOverlays, overlaySignature } from './artifact-manifest-overlay.mjs';
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const EMPTY_MANIFEST = { version: 1, artifacts: {} };
@@ -29,7 +30,7 @@ export const PLAIN_OUTPUT_FORMATS = Object.freeze(['txt', 'md', 'mdx']);
 export const GATE_LEVELS = Object.freeze(['fast', 'standard', 'render-smoke', 'full-certification', 'human-reviewed']);
 
 let cached = null;
-let cachedRoot = null;
+let cachedKey = null;
 
 function manifestPathForRoot(root) {
   return path.join(root, 'specialists', 'artifact-manifest.json');
@@ -50,17 +51,19 @@ export function findConstructRoot(startPath = process.cwd()) {
 
 export function loadArtifactManifest({ rootDir, force = false, cwd = process.cwd() } = {}) {
   const resolvedRoot = rootDir ?? findConstructRoot(cwd) ?? PACKAGE_ROOT;
-  if (cached && !force && cachedRoot === resolvedRoot) return cached;
 
-  const p = manifestPathForRoot(resolvedRoot);
-  if (!fs.existsSync(p)) {
-    cached = EMPTY_MANIFEST;
-    cachedRoot = resolvedRoot;
-    return cached;
-  }
+  // The builtin manifest is keyed by root, but project/user overlays and the
+  // sanctioned adhoc type resolve against cwd. Key the cache on both plus an
+  // overlay-file signature so a `templates register` earlier in a long-running
+  // process (the MCP server) invalidates a stale merged manifest.
 
-  cached = JSON.parse(fs.readFileSync(p, 'utf8'));
-  cachedRoot = resolvedRoot;
+  const key = `${resolvedRoot}|${cwd}|${overlaySignature({ cwd })}`;
+  if (cached && !force && cachedKey === key) return cached;
+
+  const p = manifestPathForRoot(resolvedRoot);
+  const builtin = fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : EMPTY_MANIFEST;
+  cached = applyArtifactOverlays(builtin, { cwd });
+  cachedKey = key;
   return cached;
 }
 

package/lib/cli-commands.mjs

@@ -215,6 +215,30 @@ export const CLI_COMMANDS = [
       { name: 'add --source=research --slug=<id> --topic="..." [--source-url=<url>]', desc: 'Persist a research finding into .cx/knowledge/external/research/' },
     ],
   },
+  {
+    name: 'synthesize',
+    emoji: '🔗',
+    category: 'Work',
+    core: false,
+    description: 'Cross-project synthesis: map each registered project, reduce to an origin-cited answer',
+    usage: 'construct synthesize --ask "<question>" [--projects=all|self|id,...] [--template <name>] [--dry-run] [--json]',
+    examples: [
+      { cmd: 'construct synthesize --ask "summarize each project\'s docs" --projects=all --dry-run', desc: 'Preview the assembled per-project context (no model call)' },
+      { cmd: 'construct synthesize --ask "how do these strategies converge" --projects=proj-app,proj-sdk', desc: 'Synthesize a convergence answer across two projects' },
+    ],
+  },
+  {
+    name: 'tracker',
+    emoji: '📮',
+    category: 'Models & Integrations',
+    core: false,
+    description: 'Analyze registered projects and contribute governed issue proposals to an external tracker (Jira)',
+    usage: 'construct tracker contribute --target <id> [--against <ids|all>] | --apply <proposal-id> [--approve <token>]',
+    subcommands: [
+      { name: 'contribute --target <id> [--against <ids|all>]', desc: 'Analyze corpora vs the tracker and emit an evidence-cited, deduped proposal artifact' },
+      { name: 'contribute --apply <proposal-id> [--approve <token>]', desc: 'Apply a proposal: dry-run by default; --approve executes the governed write batch' },
+    ],
+  },
   {
     name: 'sandbox',
     emoji: '🧪',
@@ -449,13 +473,16 @@ export const CLI_COMMANDS = [
     category: 'Models & Integrations',
     core: false,
     description: 'Show or update model tier assignments',
-    usage: 'construct models <list|set|free|reset|resolve>',
+    usage: 'construct models <list|set|free|reset|resolve|policy|explain>',
     subcommands: [
       { name: 'list', desc: 'Show current tier assignments' },
       { name: 'set --tier=<reasoning|standard|fast> --model=<model>', desc: 'Set a model for a tier' },
       { name: 'free', desc: 'List available free models' },
       { name: 'reset', desc: 'Reset all tier assignments' },
       { name: 'resolve --json', desc: 'Resolve the model for an embedded workflow given host context' },
+      { name: 'policy show', desc: 'Show the effective policy: winning source per tier + work-category map' },
+      { name: 'policy set <budget|free|frontier|local>', desc: 'Compute a preset and persist it to specialists/org/models.json' },
+      { name: 'explain --role <specialist>', desc: 'Per-specialist model resolution trace' },
     ],
   },
   {
@@ -822,12 +849,25 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Manage typed integration source targets in construct.config.json',
-    usage: 'construct sources list|add|remove|validate',
+    usage: 'construct sources list|add|remove|validate|sync',
     subcommands: [
-      { name: 'list', desc: 'Show config targets, legacy env merge, and effective set' },
-      { name: 'add <provider> <id> <selector-json>', desc: 'Add a typed target (github, jira, linear, slack)' },
+      { name: 'list', desc: 'Show config targets, legacy env merge, corpus freshness, and effective set' },
+      { name: 'add <provider> <id> <selector-json>', desc: 'Add a typed target (directory, github, jira, linear, slack)' },
       { name: 'remove <id>', desc: 'Remove a config target by id' },
       { name: 'validate', desc: 'Validate sources.targets in construct.config.json' },
+      { name: 'sync [<id>]', desc: 'Clone/fetch the content cache for corpus targets' },
+    ],
+  },
+  {
+    name: 'templates',
+    emoji: '📝',
+    category: 'Advanced',
+    core: false,
+    description: 'List doc templates and register custom document classes (project-tier overlay; builtin manifest untouched)',
+    usage: 'construct templates list|register <type>',
+    subcommands: [
+      { name: 'list', desc: 'Show shipped templates and project overrides' },
+      { name: 'register <type> [--description "..."] [--from <file>] [--force]', desc: 'Register a custom doc class: writes .cx/templates/docs/<type>.md + a project artifact-manifest overlay entry' },
     ],
   },
   {

package/lib/config/source-target-registry.mjs

@@ -20,6 +20,7 @@
  *   aliases                        — resolveKnownSourcesFromTargets
  *   embed                          — targetsToEmbedSources
  *   embedFilters                   — targetsToEmbedSourcesWithFilters
+ *   content                        — lib/sources/repo-cache.mjs (corpus clone/fetch)
  *   demandFetch.target*            — lib/embed/demand-fetch.mjs buildReadCallsForTarget
  *   demandFetch.query*             — lib/embed/demand-fetch.mjs buildReadCalls
  *

package/lib/config/source-targets.mjs

@@ -13,6 +13,10 @@
  * drives.
  */
 
+import { statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
 import {
   SOURCE_TARGET_PROVIDERS,
   getSourceTargetDescriptor,
@@ -27,6 +31,16 @@ export const SLACK_INTENTS = Object.freeze(slackDescriptor?.secondaryField?.enum
 
 const ID_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
 
+// Path selectors (directory) are stored portably with a leading `~`; the concrete
+// home is resolved at validate/read time so a config survives moves between machines.
+
+export function expandTilde(value, home = homedir()) {
+  const str = String(value ?? '');
+  if (str === '~') return home;
+  if (str.startsWith('~/')) return join(home, str.slice(2));
+  return str;
+}
+
 function applyPatternTransform(value, mode) {
   if (mode === 'trimUpper') return value.trim().toUpperCase();
   return value.trim();
@@ -68,6 +82,22 @@ export function validateSourceTarget(target, index = 0) {
     errors.push(`${at}.selector.${field}: ${hint}`);
   }
 
+  // A descriptor whose selector declares `existsAs` (directory targets) must
+  // resolve to a real filesystem entry of that kind at validate time — a
+  // format-valid but nonexistent path is an actionable error, not silent.
+
+  if (valid && descriptor.selector.existsAs) {
+    const resolved = descriptor.selector.expand === 'tilde' ? expandTilde(raw.trim()) : raw.trim();
+    let onDisk = false;
+    try {
+      const st = statSync(resolved);
+      onDisk = descriptor.selector.existsAs === 'directory' ? st.isDirectory() : st.isFile();
+    } catch { onDisk = false; }
+    if (!onDisk) {
+      errors.push(`${at}.selector.${field}: ${descriptor.selector.existsHint ?? hint}`);
+    }
+  }
+
   if (descriptor.secondaryField) {
     const { field: secField, enum: secEnum, hint: secHint } = descriptor.secondaryField;
     if (sel[secField] !== undefined && !secEnum.includes(sel[secField])) {

package/lib/doc-stamp.mjs

@@ -113,6 +113,7 @@ export function stampFrontmatter(content, {
   model = null,
   preserve_id = true,
   attribution = null,
+  extraFields = null,
 } = {}) {
   const existing = hasStamp(content) ? splitStamp(content) : null;
   const existingFields = existing ? parseStamp(content) : {};
@@ -145,6 +146,17 @@ export function stampFrontmatter(content, {
   }
   if (model) lines.push(`model: ${model}`);
   if (sessionId) lines.push(`session_id: ${sessionId}`);
+
+  // Caller-supplied provenance (e.g. ingest --as stamps origin_target_id /
+  // origin_provider). Existing values carry forward so a re-stamp never erases
+  // the source attribution the reader relies on to re-verify the document.
+  if (extraFields && typeof extraFields === 'object') {
+    for (const [key, value] of Object.entries(extraFields)) {
+      const carried = existingFields[key] ?? value;
+      if (carried != null && String(carried).trim() !== '') lines.push(`${key}: ${carried}`);
+    }
+  }
+
   lines.push(`body_hash: ${hash}`);
   lines.push(STAMP_CLOSE);
   lines.push('');

package/lib/doctor/index.mjs

@@ -29,11 +29,12 @@ import * as graphStaleness from './watchers/graph-staleness.mjs';
 import * as providerBreaker from './watchers/provider-breaker.mjs';
 import * as oracleLiveness from './watchers/oracle-liveness.mjs';
 import * as orchestrationRuns from './watchers/orchestration-runs.mjs';
+import * as sourceTargets from './watchers/source-targets.mjs';
 import { stateDir } from '../config/xdg.mjs';
 import { isMainModule } from '../roots.mjs';
 
 const STATE_PATH = join(stateDir(), 'doctor.json');
-const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol, cxBudget, graphStaleness, providerBreaker, oracleLiveness, orchestrationRuns];
+const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol, cxBudget, graphStaleness, providerBreaker, oracleLiveness, orchestrationRuns, sourceTargets];
 
 let running = false;
 let timers = [];

package/lib/doctor/source-target-health.mjs

@@ -0,0 +1,101 @@
+/**
+ * lib/doctor/source-target-health.mjs — health of registered source targets
+ * (bead construct-760c.8, epic closer for multi-project context targets).
+ *
+ * Filesystem- and env-only: it resolves the project's `sources.targets[]` and
+ * reports three classes of problem without ever opening a socket, so the default
+ * `construct doctor` keeps its zero-outbound-fetch invariant (deep connectivity
+ * probes stay behind `--probe-providers`):
+ *   - a directory target whose path does not resolve,
+ *   - a corpus target whose local cache is missing or older than its TTL
+ *     (actionable: `construct sources sync <id>`),
+ *   - a network-backed target whose credential env var is not present (a
+ *     presence check only, surfaced as a soft notice).
+ *
+ * With no targets configured it returns an empty finding set — the caller emits
+ * nothing, so a project that never registered a target sees no source-target
+ * noise (R2).
+ */
+
+import { statSync } from 'node:fs';
+
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { getSourceTargetDescriptor } from '../config/source-target-registry.mjs';
+import { expandTilde, resolveEffectiveSourceTargetsFromConfig } from '../config/source-targets.mjs';
+import { isCorpusTarget, corpusFreshness, DEFAULT_CORPUS_TTL_MS } from '../sources/repo-cache.mjs';
+
+// Credential env var per network-backed provider — presence-only, never read for
+// its value. Directory targets need none and are absent from the map.
+const CREDENTIAL_ENV = {
+  github: 'GITHUB_TOKEN',
+  jira: 'JIRA_API_TOKEN',
+  confluence: 'CONFLUENCE_API_TOKEN',
+  slack: 'SLACK_BOT_TOKEN',
+  linear: 'LINEAR_API_KEY',
+};
+
+function directoryFinding(target) {
+  const descriptor = getSourceTargetDescriptor(target.provider);
+  const raw = target.selector?.[descriptor.selector.field];
+  const dir = expandTilde(String(raw ?? ''));
+  let ok = false;
+  try { ok = statSync(dir).isDirectory(); } catch { ok = false; }
+  return ok
+    ? { label: `Source target ${target.id} (directory) path resolves`, ok: true }
+    : { label: `Source target ${target.id} (directory) path missing: ${dir} — fix the path or run \`construct sources remove ${target.id}\``, ok: false };
+}
+
+function corpusFinding(target, { cwd, ttlMs, now }) {
+  const f = corpusFreshness(target, { projectRoot: cwd, ttlMs, now });
+  if (!f.cached) {
+    return { label: `Source target ${target.id} (corpus) not yet cached — run \`construct sources sync ${target.id}\``, ok: false, optional: true };
+  }
+  if (f.stale) {
+    return { label: `Source target ${target.id} (corpus) cache is stale — run \`construct sources sync ${target.id}\``, ok: false, optional: true };
+  }
+  return { label: `Source target ${target.id} (corpus) cache is fresh`, ok: true };
+}
+
+function credentialFinding(target, env) {
+  const varName = CREDENTIAL_ENV[target.provider];
+  if (!varName) return null;
+  const present = typeof env[varName] === 'string' && env[varName].trim() !== '';
+  return present
+    ? null
+    : { label: `Source target ${target.id} (${target.provider}) credential not detected (${varName}) — presence check only`, ok: false, optional: true };
+}
+
+/**
+ * Evaluate source-target health. Returns { configured, findings } where each
+ * finding is { label, ok, optional? }. An empty findings array (configured 0)
+ * means the caller should stay silent.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]
+ * @param {object} [opts.env]
+ * @param {number} [opts.ttlMs]  corpus staleness threshold
+ * @param {number} [opts.now]    injectable clock (ms) for testing
+ */
+export function checkSourceTargetHealth({ cwd = process.cwd(), env = process.env, ttlMs = DEFAULT_CORPUS_TTL_MS, now = Date.now() } = {}) {
+  // Read the DECLARED targets from raw config, not the validated `config` — a
+  // directory target whose path was deleted fails config validation and would
+  // otherwise be sanitized away to an empty set, hiding the very problem this
+  // watcher exists to flag. `raw` preserves what the user actually registered.
+  const loaded = loadProjectConfig(cwd, env);
+  const sourceConfig = loaded.raw ?? loaded.config;
+  const targets = resolveEffectiveSourceTargetsFromConfig(sourceConfig, env);
+  if (!targets.length) return { configured: 0, findings: [] };
+
+  const findings = [];
+  for (const target of targets) {
+    const descriptor = getSourceTargetDescriptor(target.provider);
+    if (descriptor?.selector?.existsAs === 'directory') {
+      findings.push(directoryFinding(target));
+    } else if (isCorpusTarget(target)) {
+      findings.push(corpusFinding(target, { cwd, ttlMs, now }));
+    }
+    const cred = credentialFinding(target, env);
+    if (cred) findings.push(cred);
+  }
+  return { configured: targets.length, findings };
+}

package/lib/doctor/watchers/source-targets.mjs

@@ -0,0 +1,44 @@
+/**
+ * lib/doctor/watchers/source-targets.mjs — registered source-target health watcher.
+ *
+ * Ticks hourly. Reuses lib/doctor/source-target-health.mjs (filesystem + env
+ * only, zero outbound fetch) to surface directory targets whose path vanished
+ * and corpus caches past their TTL, recording an audit action per hard problem
+ * so doctor reports source-target drift between Oracle ticks. A project with no
+ * registered targets returns a silent pass (no noise).
+ */
+
+import { record } from '../audit.mjs';
+import { checkSourceTargetHealth } from '../source-target-health.mjs';
+
+export const name = 'source-targets';
+export const intervalMs = 60 * 60 * 1000;
+
+function projectRoot() {
+  return process.env.CONSTRUCT_PROJECT_ROOT || process.cwd();
+}
+
+export async function tick() {
+  const actions = [];
+  const escalations = [];
+  const root = projectRoot();
+
+  const { configured, findings } = checkSourceTargetHealth({ cwd: root });
+  if (!configured) {
+    return { actions, escalations, notes: [{ configured: 0 }] };
+  }
+
+  const problems = findings.filter((f) => !f.ok && !f.optional);
+  for (const problem of problems) {
+    record({
+      kind: 'action',
+      watcher: name,
+      action: 'source-target-unhealthy',
+      target: 'sources.targets',
+      summary: problem.label,
+    });
+    actions.push({ type: 'source-target-unhealthy', target: 'sources.targets' });
+  }
+
+  return { actions, escalations, notes: [{ configured, problems: problems.length }] };
+}