@geraldmaron/construct 1.5.1 → 1.5.3

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/tracker/contribute.mjs

@@ -0,0 +1,266 @@
+/**
+ * lib/tracker/contribute.mjs — analyze → propose → dedupe → apply pipeline for
+ * contributing governed issue proposals back to an external tracker (bead
+ * construct-760c.6). Jira first, but provider-generic: the write goes through the
+ * existing governed `provider_write` path, so a tracker's eligibility is its
+ * manifest `write` capability, not a hardcoded name here.
+ *
+ * Five stages:
+ *   1. FETCH   existing issues from the tracker (injectable; default reads via
+ *              the jira embed provider's JQL).
+ *   2. ANALYZE the registered project corpora (B2 content roots) for work the
+ *              tracker does not yet cover — deterministic, retrieval-only, so the
+ *              proposal set is stable and CI-testable without a model.
+ *   3. PROPOSE a proposal artifact (JSON + markdown): each proposed issue carries
+ *              a summary, an evidence-cited description (origin.targetId +
+ *              relPath — no fabrication), a suggested type, and a stable
+ *              idempotency key. The artifact is the human-review anchor.
+ *   4. DEDUPE  proposed vs existing issue summaries by token similarity;
+ *              near-duplicates are suppressed and reported with the matched key.
+ *   5. APPLY   batch through provider_write — dry_run by default (writes
+ *              nothing), an approval token required to execute. Idempotent:
+ *              an issue already recorded created for this proposal is skipped, so
+ *              a second apply is a no-op.
+ *
+ * Beads are never touched (R5): bd stays the internal tracker; this pipeline only
+ * proposes to the external one.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { resolveEffectiveSourceTargetsFromConfig } from '../config/source-targets.mjs';
+import { resolveContentRoots, expandProjectsFilter } from '../sources/content-roots.mjs';
+import { buildCorpus } from '../knowledge/rag.mjs';
+
+const DEFAULT_PROPOSAL_LIMIT = 10;
+const DEDUPE_THRESHOLD = 0.6;
+
+const STOP = new Set(['the', 'a', 'an', 'and', 'or', 'to', 'for', 'of', 'in', 'on', 'with', 'track', 'add', 'document', 'implement']);
+
+function tokenize(text) {
+  return new Set(String(text).toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/).filter((t) => t.length > 2 && !STOP.has(t)));
+}
+
+function jaccard(a, b) {
+  if (!a.size || !b.size) return 0;
+  let inter = 0;
+  for (const t of a) if (b.has(t)) inter++;
+  return inter / (a.size + b.size - inter);
+}
+
+function proposalsDir(cwd) {
+  return path.join(cwd, '.cx', 'tracker', 'proposals');
+}
+
+function stableId(projectKey, items) {
+  const h = crypto.createHash('sha256');
+  h.update(projectKey);
+  for (const it of items) h.update(`|${it.key}`);
+  return `prop-${h.digest('hex').slice(0, 12)}`;
+}
+
+// A tracker source target names its project via the manifest selector field
+// (jira: `project`). Resolve the requested target id to that key, or throw a
+// hard error naming the known tracker targets.
+function resolveTrackerTarget(targets, targetId) {
+  const target = targets.find((t) => t.id === targetId);
+  if (!target) {
+    const known = targets.map((t) => t.id).join(', ') || '(none registered)';
+    throw new Error(`unknown tracker target "${targetId}" — known targets: ${known}`);
+  }
+  const projectKey = target.selector?.project || target.selector?.[Object.keys(target.selector || {})[0]];
+  if (!projectKey) throw new Error(`tracker target "${targetId}" has no resolvable project key`);
+  return { target, projectKey };
+}
+
+// Deterministic analyze: each source doc in a bound project's corpus is a
+// candidate work item to track, summarized from its title and cited to its
+// origin. Ordering is stable (project id, then relPath) so proposals reproduce.
+function buildCandidates(roots, cwd, limit) {
+  const candidates = [];
+  for (const root of roots) {
+    const chunks = buildCorpus(cwd, { roots: [root] })
+      .filter((c) => c.origin?.targetId === root.origin.targetId && c.origin?.relPath)
+      .sort((a, b) => a.origin.relPath.localeCompare(b.origin.relPath));
+    const seen = new Set();
+    for (const c of chunks) {
+      if (seen.has(c.origin.relPath)) continue;
+      seen.add(c.origin.relPath);
+      const summary = `Track: ${c.title} (${c.origin.projectKey})`;
+      candidates.push({
+        key: `${c.origin.targetId}:${c.origin.relPath}`,
+        summary,
+        issueType: 'Task',
+        evidence: [{ targetId: c.origin.targetId, projectKey: c.origin.projectKey, relPath: c.origin.relPath }],
+        title: c.title,
+      });
+    }
+  }
+  candidates.sort((a, b) => a.key.localeCompare(b.key));
+  return candidates.slice(0, limit);
+}
+
+function renderDescription(candidate) {
+  const cite = candidate.evidence.map((e) => `\`${e.projectKey}:${e.relPath}\``).join(', ');
+  return [
+    `Proposed from analysis of registered project content.`,
+    ``,
+    `Source: ${cite}`,
+    ``,
+    `Scope [unverified]: derive concrete acceptance criteria from the cited source before starting — details beyond the source title are not yet verified.`,
+  ].join('\n');
+}
+
+function dedupe(candidates, existingIssues) {
+  const existingTok = existingIssues.map((i) => ({ key: i.key, tokens: tokenize(i.summary || i.title || '') }));
+  const proposals = [];
+  const suppressed = [];
+  for (const c of candidates) {
+    const ctok = tokenize(c.summary);
+    let best = null;
+    for (const e of existingTok) {
+      const score = jaccard(ctok, e.tokens);
+      if (score >= DEDUPE_THRESHOLD && (!best || score > best.score)) best = { key: e.key, score };
+    }
+    if (best) {
+      suppressed.push({ key: c.key, summary: c.summary, matchedIssueKey: best.key, similarity: Math.round(best.score * 100) / 100 });
+    } else {
+      proposals.push(c);
+    }
+  }
+  return { proposals, suppressed };
+}
+
+/**
+ * Default issue fetch: read the tracker target's existing issues through the
+ * jira embed provider. Injectable via deps.fetchIssues for tests.
+ */
+async function defaultFetchIssues({ projectKey, env }) {
+  const { JiraProvider } = await import('../embed/providers/jira.mjs');
+  const provider = new JiraProvider({ env });
+  const items = await provider.read('issues', { project: projectKey });
+  return (items || []).filter((i) => i && i.key).map((i) => ({ key: i.key, summary: i.title || i.summary || '' }));
+}
+
+function renderProposalMarkdown(proposal) {
+  const lines = [
+    `# Tracker contribution proposal — ${proposal.projectKey}`,
+    ``,
+    `Proposal id: \`${proposal.id}\` · target: \`${proposal.targetId}\` · generated ${proposal.createdAt}`,
+    ``,
+    `## Proposed issues (${proposal.proposals.length})`,
+    ``,
+  ];
+  for (const p of proposal.proposals) {
+    lines.push(`### ${p.summary}`, ``, `- type: ${p.issueType}`, `- idempotency key: \`${p.key}\``, ``, renderDescription(p), ``);
+  }
+  lines.push(`## Dedupe report (${proposal.suppressed.length} suppressed)`, ``);
+  if (proposal.suppressed.length) {
+    lines.push(`| Proposed | Matched issue | Similarity |`, `|---|---|---|`);
+    for (const s of proposal.suppressed) lines.push(`| ${s.summary} | ${s.matchedIssueKey} | ${s.similarity} |`);
+  } else {
+    lines.push(`_No near-duplicates suppressed._`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function saveProposal(cwd, proposal) {
+  const dir = proposalsDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, `${proposal.id}.json`), `${JSON.stringify(proposal, null, 2)}\n`);
+  fs.writeFileSync(path.join(dir, `${proposal.id}.md`), renderProposalMarkdown(proposal));
+  return { json: path.join(dir, `${proposal.id}.json`), md: path.join(dir, `${proposal.id}.md`) };
+}
+
+export function loadProposal(cwd, proposalId) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(proposalsDir(cwd), `${proposalId}.json`), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stages 1–4: fetch existing issues, analyze bound project corpora, propose
+ * evidence-cited issues, dedupe against existing, and persist the proposal
+ * artifact. No writes to the tracker.
+ */
+export async function analyzeAndPropose({ target, against, cwd = process.cwd(), env = process.env, limit = DEFAULT_PROPOSAL_LIMIT, deps = {} } = {}) {
+  const { config } = loadProjectConfig(cwd, env);
+  const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
+  const { projectKey } = resolveTrackerTarget(targets, target);
+
+  let selectedIds;
+  try {
+    selectedIds = expandProjectsFilter(against ?? 'all', targets).ids;
+  } catch (err) {
+    return { ok: false, message: err.message };
+  }
+  const roots = resolveContentRoots(targets, { projectRoot: cwd })
+    .filter((r) => selectedIds.has(r.origin.targetId));
+  if (!roots.length) {
+    return { ok: false, message: `no content-capable projects resolved for "${against ?? 'all'}" to analyze against` };
+  }
+
+  const fetchIssues = deps.fetchIssues ?? defaultFetchIssues;
+  const existing = await fetchIssues({ projectKey, env });
+
+  const candidates = buildCandidates(roots, cwd, limit);
+  const { proposals, suppressed } = dedupe(candidates, existing);
+
+  const now = deps.now ?? (() => new Date().toISOString());
+  const proposal = {
+    id: stableId(projectKey, candidates),
+    targetId: target,
+    projectKey,
+    createdAt: now(),
+    existingIssueCount: existing.length,
+    proposals: proposals.map((p) => ({ key: p.key, summary: p.summary, issueType: p.issueType, evidence: p.evidence, description: renderDescription(p) })),
+    suppressed,
+  };
+  const paths = saveProposal(cwd, proposal);
+  return { ok: true, proposal, paths };
+}
+
+/**
+ * Stage 5: apply a proposal through the governed write path. Without
+ * approveToken every write is a dry-run (renders payloads, writes nothing).
+ * Idempotent: an issue already recorded created for this proposal is skipped, so
+ * re-apply never creates a duplicate (R3/AC5).
+ */
+export async function applyProposal({ proposalId, proposal: inline, approveToken = null, cwd = process.cwd(), env = process.env, deps = {} } = {}) {
+  const proposal = inline || loadProposal(cwd, proposalId);
+  if (!proposal) return { ok: false, message: `proposal not found: ${proposalId}` };
+
+  const write = deps.providerWrite ?? (async (args) => (await import('../mcp/tools/provider-write.mjs')).providerWrite(args, { rootDir: cwd, env }));
+  const dryRun = !approveToken;
+
+  const auditPath = path.join(proposalsDir(cwd), `${proposal.id}.audit.json`);
+  let audit = [];
+  try { audit = JSON.parse(fs.readFileSync(auditPath, 'utf8')); } catch { audit = []; }
+  const alreadyCreated = new Set(audit.map((a) => a.key));
+
+  const results = [];
+  for (const p of proposal.proposals) {
+    if (!dryRun && alreadyCreated.has(p.key)) {
+      results.push({ key: p.key, status: 'skipped-idempotent' });
+      continue;
+    }
+    const item = { type: 'issue', project: proposal.projectKey, issueType: p.issueType, summary: p.summary, description: p.description };
+    const res = await write({ provider: 'jira', item, dry_run: dryRun, idempotency_key: `${proposal.id}:${p.key}`, approval_token: approveToken });
+    results.push({ key: p.key, status: res.status, dryRun });
+    if (!dryRun && res.status && !String(res.status).startsWith('denied')) {
+      const issueKey = res.envelope?.result?.key || res.envelope?.issueKey || null;
+      audit.push({ key: p.key, proposalId: proposal.id, issueKey, at: (deps.now ?? (() => new Date().toISOString()))() });
+    }
+  }
+
+  if (!dryRun) {
+    fs.mkdirSync(proposalsDir(cwd), { recursive: true });
+    fs.writeFileSync(auditPath, `${JSON.stringify(audit, null, 2)}\n`);
+  }
+  return { ok: true, proposalId: proposal.id, dryRun, results, audit: dryRun ? undefined : audit };
+}

package/lib/validator.mjs

@@ -10,8 +10,7 @@ import { loadRegistry } from './registry/loader.mjs';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { packageRoot, isMainModule } from './roots.mjs';
-
-const VALID_TIERS = new Set(['reasoning', 'standard', 'fast']);
+import { MODEL_TIERS, MODEL_TIER_SET as VALID_TIERS } from './model-tiers.mjs';
 const VALID_REASONING_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh']);
 
 const PROMPT_HARD_CAP_WORDS = 4000;
@@ -221,7 +220,7 @@ export function validateRegistry(reg, options = {}) {
   if (!reg.models || typeof reg.models !== 'object') {
     errors.push('registry: models is missing');
   } else {
-    for (const tier of ['reasoning', 'standard', 'fast']) {
+    for (const tier of MODEL_TIERS) {
       const t = reg.models[tier];
       if (!t || typeof t !== 'object') {
         errors.push(`models.${tier}: tier object is missing`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -123,10 +123,6 @@
     "unpdf": "^1.6.2",
     "zod": "^4.4.3"
   },
-  "overrides": {
-    "express-rate-limit": "8.5.1",
-    "undici": "6.27.0"
-  },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "c8": "^11.0.0",

package/registry/agent-manifest.json

@@ -70,10 +70,6 @@
         "name": "artifact_workflow",
         "use": "Plan a manifest-backed artifact workflow; validate or export locally."
       },
-      {
-        "name": "workflow_invoke",
-        "use": "Invoke an embedded Construct workflow (prd-draft, architecture-review, …)."
-      },
       {
         "name": "triage_recommend",
         "use": "Recommend intake triage — type, owner, and routing — for a new signal."

package/registry/capabilities.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "catalog": {
-    "generatedAt": "2026-07-06T22:40:56.862Z",
+    "generatedAt": "2026-07-09T04:29:22.395Z",
     "npmScripts": [
       "adapters",
       "audit:published",
@@ -11,6 +11,7 @@
       "catalog:regen",
       "catalog:validate",
       "certify:demos",
+      "ci:local",
       "clean:artifacts",
       "coverage",
       "deps:check",
@@ -746,6 +747,12 @@
         "core": true,
         "internal": false
       },
+      {
+        "name": "synthesize",
+        "category": "Work",
+        "core": false,
+        "internal": false
+      },
       {
         "name": "tags",
         "category": "Work",
@@ -788,12 +795,24 @@
         "core": false,
         "internal": false
       },
+      {
+        "name": "templates",
+        "category": "Advanced",
+        "core": false,
+        "internal": false
+      },
       {
         "name": "tools",
         "category": "Work",
         "core": false,
         "internal": false
       },
+      {
+        "name": "tracker",
+        "category": "Models & Integrations",
+        "core": false,
+        "internal": false
+      },
       {
         "name": "uninstall",
         "category": "Advanced",

package/scripts/sync-specialists.mjs

@@ -1459,12 +1459,21 @@ ${buildPrompt(entry, allEntries, "copilot")}
 }
 
 function syncCopilot(entries, targetDir = null, wants = true) {
+  // Deselected host: leave prior Copilot outputs untouched. Adapter pruning is
+  // explicit-consent-only and `.github` is out of adapter-prune's scope
+  // (lib/reconcile/adapter-prune.mjs), so a sync that did not select copilot
+  // must never delete or degrade another run's files — the old empty-writeEntries
+  // fall-through pruned .github/prompts and .github/agents and blanked the
+  // instructions block on every copilot-less sync (construct-lqp4c).
+
+  if (!wants) return;
+
   const promptsDir = targetDir
     ? path.join(targetDir, ".github", "prompts")
     : path.join(home, ".github", "prompts");
-  if (!DRY_RUN && wants) mkdirp(promptsDir);
+  if (!DRY_RUN) mkdirp(promptsDir);
 
-  const writeEntries = wants ? globalEntries(entries) : [];
+  const writeEntries = globalEntries(entries);
 
   for (const entry of writeEntries) {
     writeFile(path.join(promptsDir, `${adapterName(entry)}.prompt.md`), copilotPrompt(entry, entries), { stamp: false });
@@ -1483,7 +1492,7 @@ function syncCopilot(entries, targetDir = null, wants = true) {
   const agentsDir = targetDir
     ? path.join(targetDir, ".github", "agents")
     : path.join(home, ".github", "agents");
-  if (!DRY_RUN && wants) mkdirp(agentsDir);
+  if (!DRY_RUN) mkdirp(agentsDir);
   for (const entry of writeEntries) {
     writeFile(path.join(agentsDir, `${adapterName(entry)}.agent.md`), copilotAgentFile(entry, entries), { stamp: false });
   }

package/templates/docs/README.md

@@ -62,6 +62,28 @@ cp templates/docs/prd.md .cx/templates/docs/prd.md
 
 Ask Construct for a PRD; it'll follow the new shape.
 
+### Registering a new document class
+
+Overriding a template reshapes an *existing* class. To generate a class the builtin manifest never registered, register it — this writes the template plus a project-tier manifest overlay, and never touches the builtin `specialists/artifact-manifest.json`:
+
+```bash
+construct templates register convergence-brief \
+  --description "Cross-project strategy convergence brief" \
+  [--from .cx/templates/docs/convergence-brief.md]
+```
+
+That writes `.cx/templates/docs/convergence-brief.md` (a starter, or your `--from` file) and adds `convergence-brief` to `.cx/artifact-manifest.overlay.json`. The overlay merges over the builtin by three tiers (builtin → user `~/.config/construct/` → project `.cx/`), so the registered class now resolves everywhere: `get_template("convergence-brief")` returns the project override, and `author_artifact {type:"convergence-brief", ...}` drafts from it and runs the release gate. A registered class inherits memo-like author/reviewer defaults; override them (including `outputDir`) by editing its overlay entry.
+
+### One-off adhoc documents
+
+For a genuinely one-off document with no fixed shape, skip registration entirely and use the sanctioned `adhoc` type:
+
+```
+author_artifact {type:"adhoc", title:"Q3 strategy convergence", instructions:"..."}
+```
+
+`adhoc` needs an explicit `title` and `instructions`; its structure follows the instructions, but it still runs the full release gate — free-form structure, not free-form quality. It is not a bypass for a registered class: naming a known type through `adhoc` is redirected to that class. An unknown, unregistered non-adhoc class still returns a classification/registration prompt rather than becoming a PRD.
+
 ## Role Anti-Patterns
 
 Each specialist is cognitively rooted in a **role** (product-manager, engineer, architect, etc.) with a core set of failure modes to avoid. Flavored specialists extend the core with an overlay.

package/templates/docs/adhoc.md

@@ -0,0 +1,12 @@
+# {title}
+
+<!-- Adhoc artifact: structure follows your instructions, not a fixed shape. Keep only the sections you need; add whatever the subject demands. Quality gates still apply — cite sources or mark [unverified]. -->
+
+## Summary
+<!-- One paragraph. What this document decides, communicates, or captures, and for whom. -->
+
+## Detail
+<!-- The substance, in whatever structure the instructions imply: prose, sections, tables, or a mix. -->
+
+## Next steps
+<!-- Actions, decisions, or open questions this leaves. Omit if not applicable. -->

package/templates/docs/strategy-comparison.md

@@ -0,0 +1,19 @@
+# {title}
+
+_Generated {YYYY-MM-DD}. Every cross-project claim must cite its source as `project:path`._
+
+## Per-project summary
+
+One attributed subsection per project — what each project's own documents say, cited to origin.
+
+## Convergence
+
+Where the projects agree — shared strategy, common patterns, aligned bets. Each claim cites the projects it draws from.
+
+## Divergence
+
+Where the projects differ — conflicting choices, gaps, incompatible assumptions. Cite both sides.
+
+## Recommendation
+
+The synthesis: what the convergence and divergence imply. Mark any forward-looking claim `[unverified]` when it is not grounded in a cited source.