@geraldmaron/construct 1.0.15 → 1.0.17

package/lib/embedded-contract/workflow-invoke.mjs

@@ -0,0 +1,218 @@
+/**
+ * lib/embedded-contract/workflow-invoke.mjs — embedded workflow invocation contract.
+ *
+ * Invokes a named Construct workflow non-interactively and returns a provenanced
+ * execution plan: the selected roles (auto/explicit/constrained), each role's
+ * rationale, the skills they apply, the resolved model, the evidence the chain
+ * requires, and the output contract it will produce. Construct supplies the
+ * orchestration plan and provenance; the host agent runtime performs the
+ * specialist reasoning — so this contract never fabricates specialist output.
+ *
+ * Durable side effects are gated by approval mode (resolveWriteGate):
+ *   - proposal-only           → status 'proposed', zero writes
+ *   - requires-human-approval → status 'awaiting-approval', an approval request
+ *                               is recorded, zero durable writes
+ *   - allow-durable-write     → status 'recorded', the invocation is written to
+ *                               the observation store as durable provenance
+ * On team/enterprise deployments, durable writes are flagged as mandatorily
+ * audited. A traceId correlates the call with downstream provenance.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { addObservation } from '../observation-store.mjs';
+import { recordApprovalRequest } from '../roles/approval-surface.mjs';
+import { getWorkflowDef, WORKFLOW_TYPES } from './workflow-defs.mjs';
+import { roleMap, roleRationale, skillsForChain, contractFacts } from './role-facts.mjs';
+import { resolveEmbeddedModel } from './model-resolve.mjs';
+import { resolveWriteGate, newTraceId, DEFAULT_APPROVAL_MODE } from './audit.mjs';
+
+const VALID_STRATEGIES = ['auto', 'explicit', 'constrained'];
+
+function selectRoles({ strategy, defChain, requestedRoles, map, warnings }) {
+  const filterKnown = (ids) => ids.filter((id) => {
+    if (map.has(id)) return true;
+    warnings.push(`Unknown role id ignored: ${id}.`);
+    return false;
+  });
+
+  if (strategy === 'explicit') {
+    if (!Array.isArray(requestedRoles) || requestedRoles.length === 0) {
+      warnings.push('roleStrategy=explicit requires requestedRoles; using the workflow default chain.');
+      return [...defChain];
+    }
+    return filterKnown(requestedRoles);
+  }
+  if (strategy === 'constrained') {
+    const allowed = new Set(requestedRoles || []);
+    const dropped = defChain.filter((id) => !allowed.has(id));
+    if (dropped.length) warnings.push(`Constrained: roles outside requestedRoles dropped from the default chain: ${dropped.join(', ')}.`);
+    return defChain.filter((id) => allowed.has(id));
+  }
+  return [...defChain];
+}
+
+function errorResult({ workflowId, traceId, approvalMode, code, message, warnings }) {
+  return {
+    workflowId,
+    status: 'error',
+    selectedRoles: [],
+    roleStrategy: null,
+    roleRationale: [],
+    skillsApplied: [],
+    modelResolution: null,
+    outputs: null,
+    recommendations: [],
+    evidence: { requirements: [], satisfied: [], traceId },
+    risks: { level: 'unknown', factors: [] },
+    requiresApproval: false,
+    approvalMode: approvalMode || DEFAULT_APPROVAL_MODE,
+    durableWritesPerformed: [],
+    traceId,
+    errors: [{ code, message }],
+    warnings,
+  };
+}
+
+/**
+ * Invoke an embedded workflow. Async because durable provenance and approval
+ * records are written through existing stores. Returns a result object carrying
+ * a `warnings` array (lifted into the envelope by the calling surface).
+ *
+ * @param {object} request
+ * @param {string} request.workflowType
+ * @param {string} [request.input]
+ * @param {object} [request.context]
+ * @param {string} [request.roleStrategy]    auto | explicit | constrained
+ * @param {string[]} [request.requestedRoles]
+ * @param {string} [request.approvalMode]     proposal-only | requires-human-approval | allow-durable-write
+ * @param {boolean} [request.trace=true]
+ * @param {string} [request.host]
+ * @param {string} [request.hostModel]
+ * @param {string} [request.hostProvider]
+ * @param {object} [opts]   { env, cwd }
+ * @returns {Promise<object>}
+ */
+export async function invokeWorkflow(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
+  const {
+    workflowType, context = {}, roleStrategy = 'auto', requestedRoles,
+    approvalMode, trace = true, host, hostModel, hostProvider, ingestion = null,
+  } = request;
+  const warnings = [];
+  if (ingestion) {
+    if (ingestion.error) warnings.push(`ingestion: ${ingestion.error.code} — ${ingestion.error.reason}`);
+    for (const drop of ingestion.droppedInfo || []) warnings.push(`ingestion: ${drop.kind || 'dropped-content'}${drop.recoverable ? ' (recoverable)' : ''}.`);
+    if (ingestion.truncated) warnings.push('ingestion: source text was truncated before invocation.');
+    if (ingestion.note) warnings.push(`ingestion: ${ingestion.note}`);
+  }
+  const traceId = trace ? newTraceId() : null;
+  const workflowId = `wf-${randomUUID()}`;
+
+  const def = getWorkflowDef(workflowType);
+  if (!def) {
+    return errorResult({ workflowId, traceId, approvalMode, code: 'UNKNOWN_WORKFLOW_TYPE', message: `Unknown workflowType "${workflowType}". Known: ${WORKFLOW_TYPES.join(', ')}.`, warnings });
+  }
+
+  const strategy = VALID_STRATEGIES.includes(roleStrategy) ? roleStrategy : 'auto';
+  if (strategy !== roleStrategy) warnings.push(`Unknown roleStrategy "${roleStrategy}"; defaulting to auto.`);
+
+  const map = roleMap();
+  const selectedRoles = selectRoles({ strategy, defChain: def.chain, requestedRoles, map, warnings });
+  if (selectedRoles.length === 0) {
+    return errorResult({ workflowId, traceId, approvalMode, code: 'NO_ROLES_SELECTED', message: 'Role selection produced an empty chain.', warnings });
+  }
+
+  const { warnings: modelWarnings = [], ...modelResolution } = resolveEmbeddedModel(
+    { workflowType, requestedTier: def.tier, host, hostModel, hostProvider },
+    { env },
+  );
+  for (const w of modelWarnings) warnings.push(`model-resolution: ${w}`);
+
+  const primaryOwner = selectedRoles[0];
+  const facts = contractFacts(primaryOwner);
+  const skillsApplied = skillsForChain(selectedRoles, map);
+  const rationale = roleRationale(selectedRoles, map);
+
+  // Evidence is satisfied only when a requirement key is actually present in the
+  // caller-supplied context; missing requirements are reported, never assumed.
+
+  const contextKeys = new Set(Object.keys(context || {}));
+  const satisfied = facts.evidenceRequirements.filter((req) => contextKeys.has(req));
+  const missingEvidence = facts.evidenceRequirements.filter((req) => !contextKeys.has(req));
+
+  const deploymentMode = getDeploymentMode(env, { cwd });
+  const mode = approvalMode || def.defaultApprovalMode;
+  const gate = resolveWriteGate({ approvalMode: mode, deploymentMode });
+
+  const outputs = {
+    schema: def.outputSchema,
+    expected: facts.expectedOutputs,
+    note: 'Construct returns the orchestration plan and output contract; specialist reasoning is performed by the host agent runtime.',
+  };
+  const recommendations = [`Run roles in order: ${selectedRoles.map((r) => `cx-${r}`).join(' → ')}.`];
+  if (missingEvidence.length) recommendations.push(`Supply missing evidence before execution: ${missingEvidence.join(', ')}.`);
+
+  const riskFactors = [];
+  if (missingEvidence.length) riskFactors.push(`missing required evidence: ${missingEvidence.join(', ')}`);
+  if (modelResolution.error) riskFactors.push(`model could not be resolved: ${modelResolution.error.reason}`);
+  const risks = { level: missingEvidence.length || modelResolution.error ? 'medium' : 'low', factors: riskFactors };
+
+  const durableWritesPerformed = [];
+  const errors = [];
+  let status;
+
+  if (gate.requiresApproval) {
+    try {
+      await recordApprovalRequest({
+        personaId: primaryOwner,
+        action: `embedded-workflow:${workflowType}`,
+        target: workflowId,
+        reason: `Embedded workflow ${workflowType} awaiting human approval.`,
+        context: { workflowType, selectedRoles, traceId },
+      });
+    } catch (err) {
+      warnings.push(`Could not record approval request: ${err.message}`);
+    }
+    status = 'awaiting-approval';
+  } else if (gate.allowWrites) {
+    try {
+      const obs = await addObservation(cwd, {
+        role: primaryOwner,
+        category: 'decision',
+        summary: `Embedded workflow invoked: ${workflowType}`,
+        content: `roles=${selectedRoles.join(',')}; tier=${def.tier}; model=${modelResolution.selectedModel || 'unresolved'}; traceId=${traceId}`,
+        tags: ['embedded-contract', `workflow/${workflowType}`],
+        source: 'embedded-contract',
+      });
+      durableWritesPerformed.push({ kind: 'observation', id: obs?.id ?? null, store: '.cx/observations', audited: gate.mandatoryAudit });
+    } catch (err) {
+      errors.push({ code: 'DURABLE_WRITE_FAILED', message: err.message });
+    }
+    status = errors.length ? 'error' : 'recorded';
+  } else {
+    status = 'proposed';
+  }
+
+  return {
+    workflowId,
+    workflowType,
+    status,
+    ingestion,
+    selectedRoles,
+    roleStrategy: strategy,
+    roleRationale: rationale,
+    skillsApplied,
+    modelResolution,
+    outputs,
+    recommendations,
+    evidence: { requirements: facts.evidenceRequirements, satisfied, missing: missingEvidence, traceId },
+    risks,
+    requiresApproval: gate.requiresApproval,
+    approvalMode: gate.approvalMode,
+    durableWritesPerformed,
+    traceId,
+    errors,
+    warnings,
+  };
+}

package/lib/hooks/config-protection.mjs

@@ -6,8 +6,8 @@
  * prettier / tsconfig / biome / stylelint configs. Those rules are a contract
  * with the codebase; weakening them is almost always a bug fix in disguise.
  *
- * Meta-system files (hooks, registry, settings template, install.sh) are
- * audited but NOT blocked. Editing them is normal development work on
+ * Meta-system files (hooks, registry, settings template, install/setup
+ * entrypoints) are audited but NOT blocked. Editing them is normal work on
  * Construct itself. The previous block-with-CX_ALLOW_META_EDIT pattern was a
  * sticky env-var toggle: friction the first time, zero protection thereafter
  * because it stayed on. Layers that actually work for self-modification
@@ -31,22 +31,29 @@ const filePath = process.env.TOOL_INPUT_FILE_PATH || (() => {
 
 if (!filePath) process.exit(0);
 
+// Lint-RULE configs are hard contracts with the codebase: weakening a rule is
+// almost always a bug fix in disguise, so edits are blocked. tsconfig is the TS
+// COMPILER config — its options legitimately change with the toolchain (e.g. a
+// version-compat flag like ignoreDeprecations on a major TS bump), so it is
+// audited as a meta edit rather than blocked. Quality-relevant tsconfig changes
+// still surface in code review and the type-checked build.
 const PROTECTED = [
   /\.eslintrc(\.[a-z]+)?$/i,
   /eslint\.config(\.[a-z]+)?$/i,
   /\.prettierrc(\.[a-z]+)?$/i,
   /prettier\.config(\.[a-z]+)?$/i,
-  /tsconfig(\.[^/]+)?\.json$/i,
   /biome\.json$/i,
   /\.stylelintrc(\.[a-z]+)?$/i,
   /stylelint\.config(\.[a-z]+)?$/i,
 ];
 
 const META_FILES = [
-  /(?:^|\/)agents\/registry\.json$/,
-  /(?:^|\/)install\.sh$/,
+  /(?:^|\/)specialists\/registry\.json$/,
+  /(?:^|\/)lib\/setup\.mjs$/,
+  /(?:^|\/)bin\/construct-postinstall\.mjs$/,
   /(?:^|\/)claude\/settings\.template\.json$/,
   /(?:^|\/)lib\/hooks\/[^/]+\.mjs$/,
+  /(?:^|\/)tsconfig(\.[^/]+)?\.json$/i,
 ];
 
 async function emitEvent(type, category, summary) {

package/lib/hooks/stop-notify.mjs

@@ -26,6 +26,7 @@ import { listSessions, loadSession, updateSession } from '../session-store.mjs';
 import { captureSessionArtifacts } from '../artifact-capture.mjs';
 import { appendSessionStats } from '../memory-stats.mjs';
 import { estimateUsageCost } from '../telemetry/model-pricing-catalog.mjs';
+import { flushReadTrackerDeltas } from '../read-tracker-store.mjs';
 
 function loadTranscriptCheckpoints(checkpointPath) {
   try {
@@ -140,6 +141,12 @@ let raw = '';
 try { raw = readFileSync(0, 'utf8'); } catch { /* non-critical */ }
 if (raw) process.stdout.write(raw);
 
+// PostToolUse Read hooks append delta lines instead of rewriting the full
+// read-tracker JSON on every call. Stop fires once per session end; this
+// is the canonical point to fold accumulated deltas back into the JSON.
+// Already wired into pre-compact + audit-reads; Stop is the third anchor.
+try { flushReadTrackerDeltas({ env: process.env }); } catch { /* non-critical */ }
+
 const home = homedir();
 const tsResultPath = join(home, '.cx', 'ts-result.txt');
 const warnFlagsPath = join(home, '.cx', 'warn-flags.txt');

package/lib/init-unified.mjs

@@ -283,20 +283,26 @@ function parseWithDocs(value) {
     return LANE_ORDER;
   }
   
-  const lanes = value.split(',').map(v => v.trim().toLowerCase());
-  const validLanes = lanes.filter(lane => LANE_ORDER.includes(lane));
-  
-  // Map common aliases
-  const mapped = validLanes.map(lane => {
-    if (lane === 'adr') return 'adrs';
-    if (lane === 'rfc') return 'rfcs';
-    if (lane === 'runbook') return 'runbooks';
-    if (lane === 'postmortem') return 'postmortems';
-    if (lane === 'prd') return 'prds';
-    return lane;
-  });
-  
-  return [...new Set(mapped)]; // dedupe
+  // Map singular aliases to canonical lane keys BEFORE validating, so
+  // `--with-docs=adr,rfc` resolves rather than being silently filtered out.
+  const ALIASES = { adr: 'adrs', rfc: 'rfcs', runbook: 'runbooks', postmortem: 'postmortems', prd: 'prds', brief: 'briefs', memo: 'memos', changelog: 'changelogs', meeting: 'meetings', note: 'notes' };
+
+  const requested = value.split(',').map(v => v.trim().toLowerCase()).filter(Boolean);
+  const resolved = [];
+  const unknown = [];
+  for (const lane of requested) {
+    const canonical = ALIASES[lane] || lane;
+    if (LANE_ORDER.includes(canonical)) resolved.push(canonical);
+    else unknown.push(lane);
+  }
+
+  // Surface typo'd lanes loudly instead of dropping them silently; valid lanes
+  // still proceed so one bad token does not abort init.
+  if (unknown.length) {
+    console.warn(`Warning: ignoring unknown --with-docs lane(s): ${unknown.join(', ')}. Valid lanes: ${LANE_ORDER.join(', ')}`);
+  }
+
+  return [...new Set(resolved)]; // dedupe
 }
 
 function inferProjectName(targetPath) {
@@ -741,8 +747,6 @@ This project enforces documentation quality:
 }
 
 function preflight(target) {
-  console.log('[TRACE init:pre-flight]');
-  
   // Check git repo
   try {
     execSync('git rev-parse --show-toplevel', { cwd: target, stdio: 'ignore' });
@@ -797,6 +801,14 @@ async function main() {
 
   const { clean } = preflight(target);
 
+  // Interactive sessions check machine prerequisites up front and offer to run
+  // `construct install` before any scaffolding, so a missing dependency is
+  // surfaced at the start rather than midway. Non-interactive runs rely on
+  // preflight's git check and stay silent so CI/tests are unaffected.
+  if (interactive && process.stdin.isTTY) {
+    await checkPrerequisites();
+  }
+
   if (!quiet) {
     console.log(`Initializing Construct in ${path.relative(process.cwd(), target) || "."}`);
   }
@@ -1037,7 +1049,6 @@ async function main() {
   // so the user can inspect what's watched and edit the file directly. Empty
   // parentDirs is the correct default: the inbox watcher always scans
   // .cx/inbox/ and docs/intake/ (when present); extra dirs are opt-in.
-  console.log('[TRACE init:intake-ask]');
 
   const intakeConfig = (await askIntakeCollection(target, skipInteractive)) ?? { parentDirs: [], maxDepth: 4 };
   // When a custom intake surface was detected, default includeProjectInbox
@@ -1063,8 +1074,6 @@ async function main() {
   }
   
   // Ask about documentation system
-  console.log('[TRACE init:docs-ask]');
-  
   const { lanes, withArchitecture, withReadme, docsPreset: userDocsPreset } = await askDocumentationQuestions();
   
   // Create README.md if requested or missing
@@ -1072,9 +1081,7 @@ async function main() {
   if (withReadme || !fs.existsSync(readmePath)) {
     writeIfMissing(readmePath, buildProjectReadme(projectName));
   }
-  
-    console.log('[TRACE init:docs-write]');
-  
+
   // Create documentation system if lanes specified
   if (lanes.length > 0) {
     // Filter out lanes that the project already covers elsewhere
@@ -1195,19 +1202,22 @@ async function main() {
     console.log('  NEXT STEPS');
     console.log('═══════════════════════════════════════════════════════════');
     console.log('');
-    console.log('1. Review AGENTS.md');
+    // Number steps from a running counter so the list stays sequential when
+    // the optional intake step is absent (was: hard-coded 1,2,4 → a visible gap).
+    let step = 0;
+    console.log(`${++step}. Review AGENTS.md`);
     console.log('   Operating rules and guidelines for this project');
     console.log('');
-    console.log('2. Edit plan.md');
+    console.log(`${++step}. Edit plan.md`);
     console.log('   Add your current work and tasks');
     console.log('');
     if (lanes.includes('intake')) {
-      console.log('3. Use Intake');
+      console.log(`${++step}. Use Intake`);
       console.log('   Drop files in .cx/inbox/ for processing');
       console.log('   Run: construct intake');
       console.log('');
     }
-    console.log('4. Start working');
+    console.log(`${++step}. Start working`);
     console.log('   Address @construct in your editor to begin');
     console.log('');
   }

package/lib/install/first-invocation.mjs

@@ -24,8 +24,12 @@ import { parseEnvFile, writeEnvValues, getUserEnvPath } from '../env-config.mjs'
 import { probeAll, formatProbe } from '../bootstrap/resources.mjs';
 
 const BOOTSTRAP_CHECKED_KEY = 'BOOTSTRAP_CHECKED';
+// 'install' is the actual handler name in bin/construct's dispatch map;
+// 'setup' is kept for backwards-compat in case anything still routes via
+// that key. Without 'install' the probe will re-prompt the user while
+// they're already running the very command meant to satisfy it.
 const SKIP_COMMANDS = new Set([
-  'hook', 'setup', 'uninstall', 'version', 'help', 'completions', 'doctor',
+  'hook', 'install', 'setup', 'uninstall', 'version', 'help', 'completions', 'doctor', 'upgrade', 'update',
 ]);
 
 export function shouldSkipProbe({ command, env = process.env, stdin = process.stdin } = {}) {

package/lib/intake/classify.mjs

@@ -90,6 +90,9 @@ const FILENAME_HINTS = [
   { re: /eval|metric|benchmark/i, intakeType: 'eval-finding' },
   { re: /-bug\b|\bbug-/i, intakeType: 'bug' },
   { re: /runbook/i, intakeType: 'ops' },
+  { re: /^memo[-_]|[-_]memo\b/i, intakeType: 'memo' },
+  { re: /transcript|meeting-notes|standup|stand-up/i, intakeType: 'transcript' },
+  { re: /dataset|raw-?data|data-?dump|\.csv$|\.tsv$/i, intakeType: 'raw-data' },
 ];
 
 // Title-level family terms by intakeType. When the doc's H1 contains a
@@ -105,6 +108,9 @@ const TITLE_FAMILY = {
   'eval-finding': /^#\s*(eval(uation)?(\s+finding)?\b|benchmark)/im,
   bug: /^#\s*(bug\s+report|defect)\b/im,
   ops: /^#\s*(runbook|operations\s+guide)\b/im,
+  memo: /^#\s*(memo|decision\s+memo|status\s+update)\b/im,
+  transcript: /^#\s*(transcript|meeting\s+(notes|minutes)|call\s+notes)\b/im,
+  'raw-data': /^#\s*(dataset|raw\s+data|data\s+export)\b/im,
 };
 
 // Title-lock returns the highest confidence the classifier emits because

package/lib/intake/prepare.mjs

@@ -32,12 +32,13 @@ import path from 'node:path';
 import { buildHybridSearchResultsAsync } from '../storage/hybrid-query.mjs';
 import { suggestDocsLaneForFile } from '../docs-routing.mjs';
 import { createIntakeQueue } from './queue.mjs';
-import { classifyRdIntake } from './classify.mjs';
+import { classifyRdIntake, suggestTags } from './classify.mjs';
 import { detectCustomerMentions, linkSignalToCustomer, updateCustomerProfile } from '../embed/customer-profiles.mjs';
 import { resolveActiveProfile } from '../profiles/loader.mjs';
 import { emitBestEffort as emitRoleEvent } from '../roles/event-bus.mjs';
 import { gatherAttribution, stampAttribution } from './attribution.mjs';
 import { MANIFEST_REL_PATH } from './manifest.mjs';
+import { loadVocabulary } from '../tags/vocabulary.mjs';
 
 const DEFAULT_RELATED_LIMIT = 5;
 const EXCERPT_CHARS = 800;
@@ -66,12 +67,18 @@ export async function prepareIntakeForIngestedFile({
 
   let related = [];
   try {
-    const search = await hybridSearchFn(rootDir, query, { limit: relatedLimit, env });
-    related = (search?.results || []).map((hit) => ({
-      path: hit.source_path || hit.id,
+    const raw = await hybridSearchFn(rootDir, query, { limit: relatedLimit, env });
+    // Test mocks return an array directly; production wrapper returns
+    // { results: [...] }. Accept both shapes so suggestTags sees the
+    // same `related` regardless of caller. Preserve `tags` for the
+    // related-inherit suggestion path.
+    const hits = Array.isArray(raw) ? raw : (raw?.results || []);
+    related = hits.map((hit) => ({
+      path: hit.source_path || hit.path || hit.id,
       title: hit.title || hit.id,
       score: hit.score,
       summary: hit.summary || '',
+      tags: Array.isArray(hit.tags) ? hit.tags : undefined,
     }));
   } catch (err) {
     related = [];
@@ -98,6 +105,16 @@ export async function prepareIntakeForIngestedFile({
 
   const droppedInfo = ingestedFile.droppedInfo ?? [];
 
+  // Tag auto-attribution: deterministic suggestions from triage + related
+  // doc inheritance, filtered against the project tag vocabulary. Vocab
+  // load failures fall through with empty suggestions — never block the
+  // packet write on a missing/malformed vocab file.
+
+  let vocab = null;
+  try { vocab = loadVocabulary(rootDir); }
+  catch { vocab = null; }
+  const tagSuggestions = suggestTags(triage, related, vocab);
+
   const baseEntry = {
     intake: {
       sourcePath: ingestedFile.sourcePath,
@@ -112,6 +129,7 @@ export async function prepareIntakeForIngestedFile({
     excerpt: extracted.slice(0, EXCERPT_CHARS),
     query,
     customers: customers.length ? customers : undefined,
+    tags: tagSuggestions.length > 0 ? tagSuggestions : undefined,
   };
 
   // Capability detection mirrors inbox.mjs: stamp provenance onto the packet

package/lib/intake/tables/rnd.mjs

@@ -22,6 +22,9 @@ export const INTAKE_TYPES = [
   'ops',
   'security',
   'legal-compliance',
+  'memo',
+  'transcript',
+  'raw-data',
   'unknown',
 ];
 
@@ -170,6 +173,36 @@ export const CLASSIFICATION_TABLE = [
     risk: 'low',
     requiresApproval: false,
   },
+  {
+    intakeType: 'memo',
+    keywords: ['memo', 'decision memo', 'for your information', 'fyi', 'action item', 'action items', 'status update', 'weekly update', 'announcement', 'heads up', 'team update', 'decided to', 'proposal to'],
+    rdStage: 'artifact',
+    primaryOwner: 'docs-keeper',
+    recommendedChain: ['docs-keeper', 'reviewer'],
+    recommendedAction: 'summarize',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'transcript',
+    keywords: ['transcript', 'webvtt', 'meeting notes', 'meeting minutes', 'minutes of', 'attendees', 'call notes', 'stand-up notes', 'standup notes', 'recording of', 'speaker 1', 'speaker 2'],
+    rdStage: 'signal',
+    primaryOwner: 'researcher',
+    recommendedChain: ['researcher', 'data-analyst'],
+    recommendedAction: 'summarize',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'raw-data',
+    keywords: ['dataset', 'raw data', 'data dump', 'csv export', 'data export', 'column names', 'field names', 'rows and columns', 'records export', 'telemetry export', 'json export'],
+    rdStage: 'research',
+    primaryOwner: 'data-analyst',
+    recommendedChain: ['data-analyst', 'data-engineer'],
+    recommendedAction: 'summarize',
+    risk: 'low',
+    requiresApproval: false,
+  },
 ];
 
 export default { INTAKE_TYPES, STAGES, CLASSIFICATION_TABLE, UNKNOWN_TRIAGE };

package/lib/integrations/intake-integrations.mjs

@@ -88,6 +88,22 @@ function resolveConfluenceAuth(homeDir) {
 
 // ── GitHub Issues ────────────────────────────────────────────────────────
 
+// A packet that originated from a demo/fixture/inbox-test source must not
+// be published to a real GitHub repo. The caller can override via
+// `publishDemo: true` when the demo run is intentional (e.g. an explicit
+// integration test that creates and then deletes the issue). Default-safe.
+
+export function isDemoIntakePacket(packet) {
+  if (process.env.CONSTRUCT_DEMO === '1') return true;
+  if (process.env.CONSTRUCT_INTAKE_DEMO === '1') return true;
+  const sourcePath = String(packet?.intake?.sourcePath || packet?.sourcePath || '');
+  if (!sourcePath) return false;
+  if (sourcePath.includes('/tests/fixtures/')) return true;
+  if (sourcePath.includes('/.cx/intake/demo/')) return true;
+  if (sourcePath.includes('/cx-intake-demo')) return true;
+  return false;
+}
+
 /**
  * Create a GitHub issue from an intake packet.
  *
@@ -98,9 +114,19 @@ function resolveConfluenceAuth(homeDir) {
  * @param {string} [opts.apiUrl] - GitHub API URL (default: api.github.com)
  * @param {string} [opts.host] - GitHub host (default: github.com)
  * @param {object} [opts.fetchImpl]
- * @returns {Promise<{ ok: boolean, externalUrl: string|null, externalId: string|null, error?: string }>}
+ * @param {boolean} [opts.publishDemo] - Override the demo-source gate
+ * @returns {Promise<{ ok: boolean, externalUrl: string|null, externalId: string|null, error?: string, skipped?: string }>}
  */
-export async function createGitHubIssue(packet, { repo, token, apiUrl, host, fetchImpl = globalThis.fetch } = {}) {
+export async function createGitHubIssue(packet, { repo, token, apiUrl, host, fetchImpl = globalThis.fetch, publishDemo = false } = {}) {
+  if (!publishDemo && isDemoIntakePacket(packet)) {
+    return {
+      ok: false,
+      externalUrl: null,
+      externalId: null,
+      skipped: 'demo-source',
+      error: 'Refused to publish: packet originated from a demo/fixture path (set CONSTRUCT_DEMO=0 and re-run with --publish-issues to override).',
+    };
+  }
   const hd = homedir();
   const auth = resolveGitHubAuth(hd);
   const resolvedRepo = repo || auth.repo || process.env.GITHUB_REPO;