@geraldmaron/construct 1.5.1 → 1.5.3

package/lib/artifact-loop-core.mjs

@@ -234,8 +234,8 @@ function todayStamp() {
   return new Date().toISOString().slice(0, 10);
 }
 
-function outputPathForType(artifactType, slug, cwd) {
-  const relDir = OUTPUT_DIR_BY_TYPE[artifactType] || 'docs/specs/prd';
+function outputPathForType(artifactType, slug, cwd, entry = null) {
+  const relDir = OUTPUT_DIR_BY_TYPE[artifactType] || entry?.outputDir || 'docs/specs/prd';
   const fileName = artifactType === 'adr'
     ? `ADR-draft-${slug}.md`
     : `${todayStamp()}-${slug}.md`;
@@ -278,12 +278,29 @@ export function extractArtifactMarkdown(text) {
   return doc;
 }
 
-function buildDraftBody({ artifactType, title, draftFromHost, draftMarkdown, rootDir, allowScaffold = true }) {
+// An adhoc artifact has no fixed template: the supplied instructions become the
+// scaffold body, marked [unverified] so it clears the citation gate as an
+// unresearched draft. Free-form structure, still through the release gate.
+
+function buildAdhocScaffold({ title, instructions }) {
+  const instr = String(instructions || '').trim();
+  const bodyText = instr
+    || 'Free-form artifact. Expand this from the supplied instructions and evidence.';
+  return ensureFrontmatter(
+    `# ${title}\n\n${bodyText}\n\n> Scope: adhoc artifact — structure follows the instructions above.\n\n[unverified]\n`,
+    'adhoc',
+  );
+}
+
+function buildDraftBody({ artifactType, title, draftFromHost, draftMarkdown, rootDir, allowScaffold = true, instructions }) {
   const source = draftMarkdown || (draftFromHost ? normalizeDraftMarkdown(draftFromHost) : null);
   if (source && source.length >= 200 && /^#\s+/m.test(source)) {
     return ensureFrontmatter(source, artifactType);
   }
   if (!allowScaffold) return null;
+  if (artifactType === 'adhoc') {
+    return buildAdhocScaffold({ title, instructions });
+  }
   const tmpl = getTemplate({ name: artifactType }, { ROOT_DIR: rootDir });
   if (tmpl?.content) {
     return fillTemplate(tmpl.content, { title, date: todayStamp() });
@@ -300,17 +317,20 @@ export async function runConstructArtifactLoop({
   artifactType: artifactTypeOverride,
   draftMarkdown,
   allowScaffold = true,
+  instructions,
+  titleOverride,
 } = {}) {
   const root = rootDir || findConstructRoot(cwd);
   const draftFromHost = draftMarkdown ? null : lastAssistantBody(turnBlocks);
   const resolvedDraft = draftMarkdown || extractArtifactMarkdown(draftFromHost);
   const artifactType = artifactTypeOverride || resolveLoopArtifactType(text, turnBlocks);
-  const title = extractTitle(
+  const entry = getArtifactEntry(artifactType, { rootDir: root, cwd });
+  const title = titleOverride?.trim() || extractTitle(
     resolvedDraft || draftFromHost,
     explicit ? (extractLoopSubject(text) || 'draft-artifact') : 'draft-artifact',
   );
   const slug = slugify(title);
-  const outPath = outputPathForType(artifactType, slug, cwd);
+  const outPath = outputPathForType(artifactType, slug, cwd, entry);
   const workflowType = WORKFLOW_BY_TYPE[artifactType] || 'prd-draft';
   const input = [
     `Artifact loop: ${artifactType}`,
@@ -335,6 +355,7 @@ export async function runConstructArtifactLoop({
     draftMarkdown: resolvedDraft,
     rootDir: root,
     allowScaffold,
+    instructions,
   });
   if (!body) {
     const relPath = path.relative(cwd, outPath);

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/auto-docs.mjs

@@ -114,9 +114,13 @@ const DIR_DESCRIPTIONS = {
 };
 
 function buildStructureSection(rootDir) {
+  // git stderr must be discarded: from the published package rootDir is not a
+  // repository, and execSync's default stdio prints "fatal: not a git repository"
+  // to the user's terminal before the catch fires (doctor and sync both hit this).
+
   let trackedDirs;
   try {
-    const out = execSync('git ls-tree --name-only HEAD', { cwd: rootDir, encoding: 'utf8' });
+    const out = execSync('git ls-tree --name-only HEAD', { cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
     trackedDirs = new Set(out.trim().split('\n').filter(Boolean));
   } catch {
     trackedDirs = null;

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' },
     ],
   },
   {
@@ -575,8 +602,13 @@ export const CLI_COMMANDS = [
     emoji: '📈',
     category: 'Observability',
     core: false,
-    description: 'Generate agent performance review from the configured telemetry trace backend',
-    usage: 'construct review [--agent=<id>] [--days=N]',
+    description: 'Agent performance review from telemetry (run|legacy), or a deterministic PR-diff review for CI (pr)',
+    usage: 'construct review [run|legacy|pr --base=<ref> [--output=<file>]]',
+    subcommands: [
+      { name: 'run', desc: 'Generate the per-agent performance review from local session costs + telemetry' },
+      { name: 'legacy', desc: 'Telemetry pipeline report (requires CONSTRUCT_TELEMETRY_* credentials)' },
+      { name: 'pr', desc: 'Deterministic diff review vs a base ref — secret/quality heuristics, no model, no credentials (backs the CI review gate, ADR-0069)' },
+    ],
   },
   {
     name: 'optimize',
@@ -822,12 +854,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/decisions/golden.mjs

@@ -12,7 +12,7 @@ import { loadRegistry } from '../registry/loader.mjs';
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
@@ -25,19 +25,18 @@ function hookName(command) {
   return 'cmd';
 }
 
-export function buildSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
+export async function buildSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
   const snapshot = { commands: [], agents: [], hooks: {} };
 
-  const cli = readFileSync(join(repoRoot, 'lib', 'cli-commands.mjs'), 'utf8');
-  const nameRe = /name:\s*'([^']+)'[\s\S]*?core:\s*(true|false)/g;
-  let m;
-  const seen = new Set();
-  while ((m = nameRe.exec(cli)) !== null) {
-    if (seen.has(m[1])) continue;
-    seen.add(m[1]);
-    snapshot.commands.push({ name: m[1], core: m[2] === 'true' });
-  }
-  snapshot.commands.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  // The command surface comes from the CLI_COMMANDS registry module, not a
+  // text scan of its source: the earlier regex scan paired `subcommands:` item
+  // names with the NEXT command's `core:` field, minting phantom commands and
+  // swallowing real ones, so the pinned set never matched the true surface.
+
+  const { CLI_COMMANDS } = await import(pathToFileURL(join(repoRoot, 'lib', 'cli-commands.mjs')).href);
+  snapshot.commands = CLI_COMMANDS
+    .map((c) => ({ name: c.name, core: c.core === true }))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
   const registry = loadRegistry({ rootDir: repoRoot });
   snapshot.agents = Object.values(registry.specialists || {}).map((s) => s.name).sort();
@@ -59,26 +58,26 @@ function snapshotPath(repoRoot) {
   return join(repoRoot, 'tests', 'fixtures', 'golden', 'surface.json');
 }
 
-export function compareSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
+export async function compareSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
   const file = snapshotPath(repoRoot);
   if (!existsSync(file)) return { ok: false, diffs: ['no committed snapshot — run: construct decisions golden --write'] };
   const expected = JSON.stringify(JSON.parse(readFileSync(file, 'utf8')));
-  const actual = JSON.stringify(buildSurfaceSnapshot({ repoRoot }));
+  const actual = JSON.stringify(await buildSurfaceSnapshot({ repoRoot }));
   if (expected === actual) return { ok: true, diffs: [] };
   return { ok: false, diffs: ['surface snapshot drift — review the change, then regenerate with: construct decisions golden --write'] };
 }
 
-export function writeSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
-  writeFileSync(snapshotPath(repoRoot), JSON.stringify(buildSurfaceSnapshot({ repoRoot }), null, 2) + '\n');
+export async function writeSurfaceSnapshot({ repoRoot = REPO_ROOT } = {}) {
+  writeFileSync(snapshotPath(repoRoot), JSON.stringify(await buildSurfaceSnapshot({ repoRoot }), null, 2) + '\n');
 }
 
 export async function runGoldenCli(args = []) {
   if (args.includes('--write')) {
-    writeSurfaceSnapshot();
+    await writeSurfaceSnapshot();
     process.stdout.write('✓ wrote surface golden snapshot\n');
     return;
   }
-  const { ok, diffs } = compareSurfaceSnapshot();
+  const { ok, diffs } = await compareSurfaceSnapshot();
   if (ok) {
     process.stdout.write('✓ surface matches the golden snapshot\n');
     return;

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('');