@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/bridges/copilot-proxy.mjs

@@ -23,18 +23,33 @@ async function getCopilotToken() {
   }
 }
 
-const server = http.createServer(async (req, res) => {
-  // CORS
-  res.setHeader('Access-Control-Allow-Origin', '*');
-  res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
-  res.setHeader('Access-Control-Allow-Headers', '*');
+// Fail closed: the bridge fronts the user's Copilot entitlement, so every request
+// must carry the per-launch bearer token service-manager injects, and an unconfigured
+// token means no access at all. No CORS headers are emitted — the only legitimate
+// caller is a loopback server process (OpenCode), never a browser page, so a wildcard
+// Access-Control-Allow-Origin would just let any open tab drive the entitlement.
+
+const EXPECTED_TOKEN = process.env.CONSTRUCT_COPILOT_BRIDGE_TOKEN || null;
+
+function isAuthorized(req) {
+  if (!EXPECTED_TOKEN) return false;
+  const match = String(req.headers.authorization || '').match(/^Bearer\s+(.+)$/i);
+  return Boolean(match) && match[1] === EXPECTED_TOKEN;
+}
 
+const server = http.createServer(async (req, res) => {
   if (req.method === 'OPTIONS') {
     res.writeHead(204);
     res.end();
     return;
   }
 
+  if (!isAuthorized(req)) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Unauthorized: missing or invalid bridge bearer token.' }));
+    return;
+  }
+
   if (req.url === '/v1/chat/completions' && req.method === 'POST') {
     const token = await getCopilotToken();
     if (!token) {

package/lib/certification/skill-inventory.mjs

@@ -13,6 +13,7 @@ import { createHash } from 'node:crypto';
 import { artifactTypes, loadArtifactManifest } from '../artifact-manifest.mjs';
 import { validateSkillEffectiveness } from '../validators/skill-effectiveness.mjs';
 import { collectScopeRoleIds } from '../scopes/enrich.mjs';
+import { bindingForSpecialist } from '../roles/flavor-bindings.mjs';
 
 function findConstructRoot(startPath = process.cwd()) {
   let current = path.resolve(startPath);
@@ -95,7 +96,7 @@ function verificationHooks(meta, body) {
 }
 
 function resolveOwners(skillId, { registry, declaredSkills, ownerBases }) {
-  if (skillId.startsWith('brand/')) return ['cx-docs-keeper'];
+  if (skillId.startsWith('brand/')) return ['cx-operations'];
   const owners = new Set();
   for (const agent of Object.values(registry.specialists ?? {})) {
     if ((agent.skills ?? []).includes(skillId)) owners.add(`cx-${agent.name}`);
@@ -107,6 +108,14 @@ function resolveOwners(skillId, { registry, declaredSkills, ownerBases }) {
     }
     if (!owners.size) owners.add(`scope-role:${base}`);
   }
+  // A roles/*.md overlay's base name is not always a live specialist name —
+  // some overlays are skill bundles loaded onto a differently-named anchor.
+  // lib/roles/flavor-bindings.mjs is the source of truth for which
+  // specialist actually loads a given overlay; fall back to it here.
+  if (base && owners.size === 0) {
+    const binding = bindingForSpecialist(base);
+    if (binding?.specialistId) owners.add(binding.specialistId);
+  }
   if (declaredSkills.has(skillId) && owners.size === 0) {
     for (const agent of Object.values(registry.specialists ?? {})) {
       if ((agent.skills ?? []).includes(skillId)) owners.add(`cx-${agent.name}`);

package/lib/cli/approvals.mjs

@@ -0,0 +1,147 @@
+/**
+ * lib/cli/approvals.mjs — `construct approvals` CLI handler.
+ *
+ * Loads the ApprovalQueue from the appropriate persistence path and
+ * implements list / approve / deny / status subcommands.
+ *
+ * `approve` is the operator's decision point and the sole production drain
+ * for J6 governed write intents: once a record whose tool names a known
+ * governed provider (jira/github/confluence) is approved, the control plane
+ * (lib/writes/control-plane.mjs) executes it through the J2 envelope — the
+ * only place recommend becomes execute. Non-write-intent approvals (embed
+ * tool proposals) are left for their own runtime to act on and are not
+ * touched here.
+ */
+
+import { ApprovalQueue } from '../embed/approval-queue.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { executeApprovedWriteIntent } from '../writes/control-plane.mjs';
+import { parseWriteIntentToolName, KNOWN_PROVIDERS } from '../writes/write-intent.mjs';
+
+/**
+ * Run the approvals CLI command.
+ * @param {string[]} args
+ * @param {object} ctx
+ * @param {string} ctx.rootDir
+ * @param {string} ctx.homeDir
+ * @param {object} ctx.env
+ * @param {Function} ctx.println
+ * @param {Function} ctx.errorln
+ * @returns {number} exit code
+ */
+export async function runApprovalsCli(args, { rootDir, homeDir, env, println, errorln }) {
+  const sub = args[0];
+  if (!sub || sub === '--help' || sub === '-h') {
+    println('Usage: construct approvals <list|approve|deny|status>');
+    println('');
+    println('Subcommands:');
+    println('  list              List pending approvals');
+    println('  approve <id>      Approve a pending approval by id');
+    println('  deny <id>         Deny a pending approval by id');
+    println('  status <id>       Show full status of a specific approval');
+    return 0;
+  }
+
+  const deploymentMode = getDeploymentMode(env, { cwd: rootDir });
+  const persistPath = ApprovalQueue.resolvePersistPath(rootDir, deploymentMode);
+  const queue = new ApprovalQueue({ persistPath });
+
+  if (sub === 'list') {
+    const pending = queue.getPending();
+    if (pending.length === 0) {
+      println('No pending approvals.');
+      return 0;
+    }
+    for (const r of pending) {
+      const rb = r.requestedBy || {};
+      const by = rb.role || rb.userId || rb.serviceId || 'unknown';
+      println(`${r.approvalId}`);
+      println(`  tool:        ${r.toolCall?.tool || '?'}`);
+      println(`  requestedAt: ${r.requestedAt}`);
+      println(`  requestedBy: ${by}`);
+      println(`  expiresAt:   ${r.expiresAt}`);
+      println('');
+    }
+    return 0;
+  }
+
+  if (sub === 'approve') {
+    const id = args[1];
+    if (!id) {
+      errorln('Usage: construct approvals approve <id>');
+      return 1;
+    }
+    try {
+      const record = queue.approve(id, {
+        decidedBy: {
+          role: process.env.CONSTRUCT_ROLE || 'cli-operator',
+          userId: process.env.USER || process.env.USERNAME || null,
+          source: 'cli',
+        },
+      });
+      println(`Approved: ${record.approvalId} (tool: ${record.toolCall?.tool})`);
+
+      // Only a governed write intent (tool "<provider>.<kind>" naming a known
+      // governed provider) is executed here; anything else is another
+      // runtime's proposal and stays untouched.
+
+      const parsed = parseWriteIntentToolName(record.toolCall?.tool);
+      if (parsed && KNOWN_PROVIDERS.includes(parsed.providerId)) {
+        try {
+          const result = await executeApprovedWriteIntent(record, { rootDir });
+          println(`Executed ${parsed.providerId}.${parsed.writeKind} via control plane (status: ${result?.status ?? 'unknown'})`);
+        } catch (execErr) {
+          errorln(`Approved, but control-plane execution failed: ${execErr.message}`);
+          return 1;
+        }
+      }
+      return 0;
+    } catch (err) {
+      errorln(`Error: ${err.message}`);
+      return 1;
+    }
+  }
+
+  if (sub === 'deny') {
+    const id = args[1];
+    if (!id) {
+      errorln('Usage: construct approvals deny <id> [--reason=...]');
+      return 1;
+    }
+    const reasonFlag = args.find((a) => a.startsWith('--reason='));
+    const reason = reasonFlag ? reasonFlag.slice('--reason='.length) : 'denied by operator';
+    try {
+      const record = queue.deny(id, {
+        decidedBy: {
+          role: process.env.CONSTRUCT_ROLE || 'cli-operator',
+          userId: process.env.USER || process.env.USERNAME || null,
+          source: 'cli',
+        },
+        reason,
+      });
+      println(`Denied: ${record.approvalId} (reason: ${reason})`);
+      return 0;
+    } catch (err) {
+      errorln(`Error: ${err.message}`);
+      return 1;
+    }
+  }
+
+  if (sub === 'status') {
+    const id = args[1];
+    if (!id) {
+      errorln('Usage: construct approvals status <id>');
+      return 1;
+    }
+    const record = queue.getById(id);
+    if (!record) {
+      errorln(`Approval not found: ${id}`);
+      return 1;
+    }
+    println(JSON.stringify(record, null, 2));
+    return 0;
+  }
+
+  errorln(`Unknown approvals subcommand: ${sub}. Available: list, approve, deny, status`);
+  return 1;
+}

package/lib/cli-commands.mjs

@@ -24,14 +24,14 @@ export const CLI_COMMANDS = [
     category: 'Core',
     core: true,
     description: 'Start services for development',
-    usage: 'construct dev [--select] [--only=postgres,...]',
+    usage: 'construct dev [--select] [--only=memory,opencode,...]',
     examples: [
       { cmd: 'construct dev', desc: 'Start the default service set' },
-      { cmd: 'construct dev --only=postgres', desc: 'Start just Postgres' },
+      { cmd: 'construct dev --only=memory', desc: 'Start just the memory (cm) service' },
     ],
     options: [
       { flag: '--select', desc: 'Pick which services to start from an interactive checklist' },
-      { flag: '--only=<a,b,c>', desc: 'Start only the named services (postgres, telemetry, memory, opencode)' },
+      { flag: '--only=<a,b,c>', desc: 'Start only the named services (telemetry, memory, opencode, copilot-bridge)' },
     ],
   },
   {
@@ -61,22 +61,37 @@ export const CLI_COMMANDS = [
       { flag: '--json', desc: 'Output full status payload as JSON' },
     ],
   },
+  {
+    name: 'workers',
+    emoji: '🫀',
+    category: 'Core',
+    core: true,
+    description: 'List registered team workers and heartbeat freshness',
+    usage: 'construct workers <list> [--json]',
+    strictFlags: true,
+    examples: [
+      { cmd: 'construct workers list', desc: 'Show live/stale registered workers' },
+      { cmd: 'construct workers list --json', desc: 'Machine-readable worker status' },
+    ],
+    options: [
+      { flag: '--json', desc: 'Output worker list as JSON' },
+    ],
+  },
   {
     name: 'install',
     emoji: '🛠️',
     category: 'Core',
     core: true,
     description: 'Machine setup (scoped per ADR-0029): --scope=project|user|both, default project',
-    usage: 'construct install [--scope=project|user|both] [--yes] [--dry-run] [--no-docker] [--no-launch-agent] [--reconfigure] [--with-docling]',
+    usage: 'construct install [--scope=project|user|both] [--yes] [--dry-run] [--no-launch-agent] [--reconfigure] [--with-docling]',
     examples: [
       { cmd: 'construct install --dry-run', desc: 'Preview the plan before writing anything' },
       { cmd: 'construct install --scope=user --yes', desc: 'Non-interactive user-scope install' },
     ],
     options: [
-      { flag: '--scope=<s>',      desc: 'project (default, no-op + guidance) | user (writes ~/.construct/, MCP, ~/.claude/* via consent) | both' },
+      { flag: '--scope=<s>',      desc: 'project (default, no-op + guidance) | user (writes ~/.config/construct/, MCP, ~/.claude/* via consent) | both' },
       { flag: '--yes',            desc: 'Apply defaults without prompts (only meaningful with --scope=user|both)' },
       { flag: '--dry-run',        desc: 'Preview the install plan (scopes, files, services) without writing anything' },
-      { flag: '--no-docker',      desc: 'Skip Docker-based service setup (local Postgres)' },
       { flag: '--no-launch-agent', desc: 'Skip background macOS LaunchAgent registration' },
       { flag: '--reconfigure',    desc: 'Re-prompt for service consent, ignoring cached answers' },
       { flag: '--with-docling',   desc: 'Eagerly provision the docling document-extraction venv now (heavy, ~10 min; else lazy on first ingest)' },
@@ -407,9 +422,25 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Task graph management',
-    usage: 'construct graph <list|show|from-intake|recommend>',
+    usage: 'construct graph <list|show|from-intake|recommend|build|stat|query|validate|explain|owasp>',
     subcommands: [
       { name: 'recommend --json [--text|--file|<stdin>]', desc: 'Return a role-aware plan for an artifact without enqueuing (embedded contract; alias of intake classify)' },
+      { name: 'build|stat|query|validate|explain', desc: 'Living dependency graph — build/inspect/validate the typed file↔capability↔workflow↔test↔embed graph (replaces `construct matrix`)' },
+      { name: 'owasp | missing-tests --security', desc: 'OWASP GenAI Top-10 coverage matrix and the workflow/preset security-coverage gap list (LMCP-N8)' },
+    ],
+  },
+  {
+    name: 'pack',
+    emoji: '📦',
+    category: 'Work',
+    core: false,
+    description: 'Specialist/team/profile pack enable/disable lifecycle (LMCP-E3)',
+    usage: 'construct pack <list|enable|disable|info> [--json]',
+    subcommands: [
+      { name: 'list', desc: 'Every pack discovered across builtin/user/project tiers with its durable enabled state' },
+      { name: 'enable <pack-id>[@version]', desc: 'Validate the pack manifest and record it enabled in .cx/packs.json; refuses on an incompatible compatVersion or other validation failure' },
+      { name: 'disable <pack-id>', desc: 'Remove the pack\'s enabled entry (idempotent; the core pack cannot be disabled)' },
+      { name: 'info <pack-id>', desc: 'Full manifest plus enabled state for one pack' },
     ],
   },
   {
@@ -462,6 +493,30 @@ export const CLI_COMMANDS = [
       { name: 'preflight [--host H] [--json] [--no-probe]', desc: 'Verify orchestration tool attachment/readiness and return a typed reason plus recovery step' },
     ],
   },
+  {
+    name: 'flow',
+    emoji: '🧵',
+    category: 'Models & Integrations',
+    core: false,
+    description: 'Deterministic flow-engine runs: start or resume a checkpointed flow, or inspect its status',
+    usage: 'construct flow <resume|status> <run-id> [--flow=<path>] [--state=<json>]',
+    subcommands: [
+      { name: 'resume <run-id> --flow=<path> [--state=<json>]', desc: 'Start (new run-id) or resume a checkpointed flow and drive it to completion' },
+      { name: 'status <run-id>', desc: 'Read a flow checkpoint without driving it' },
+    ],
+  },
+  {
+    name: 'db',
+    emoji: '🗄️',
+    category: 'Models & Integrations',
+    core: false,
+    description: 'Inspect and migrate the optional Postgres backend',
+    usage: 'construct db <status|migrate> [--json]',
+    subcommands: [
+      { name: 'status [--json]', desc: 'Check Postgres reachability and migration state' },
+      { name: 'migrate [--json]', desc: 'Apply pending Postgres migrations idempotently' },
+    ],
+  },
   {
     name: 'acp',
     emoji: '🔗',
@@ -601,11 +656,12 @@ export const CLI_COMMANDS = [
     emoji: '👥',
     category: 'Work',
     core: false,
-    description: 'Team review and template listing (`team:add` / `team:remove` are internal registry editors)',
-    usage: 'construct team <list|show|review|templates>',
+    description: 'Team review, template listing, and custom team authoring (`team:add` / `team:remove` are internal registry editors)',
+    usage: 'construct team <list|show|create|review|templates>',
     subcommands: [
       { name: 'list', desc: 'List macro groups and squads (--kind group|squad)' },
       { name: 'show', desc: 'Show one group or squad by id' },
+      { name: 'create', desc: 'Scaffold a custom team into .cx/org/ (or ~/.construct/org/ with --user) — see docs/guides/cookbook/custom-specialists-and-teams.md' },
       { name: 'review', desc: 'Team review workflow' },
       { name: 'templates', desc: 'List team doc templates' },
     ],
@@ -785,7 +841,7 @@ export const CLI_COMMANDS = [
       { flag: '--dry-run',          desc: 'Print the plan and exit; change nothing' },
       { flag: '--yes',              desc: 'Remove auto-risk (✓) categories without prompting' },
       { flag: '--all',              desc: 'Combined with --yes: also remove ask-risk (◐) categories (project data, machine config)' },
-      { flag: '--keep-state',       desc: 'Only remove the launcher + adapters; preserve .cx/, ~/.construct, Postgres' },
+      { flag: '--keep-state',       desc: 'Only remove the launcher + adapters; preserve .cx/, ~/.config/construct, Postgres' },
       { flag: '--scope=<...>',      desc: 'Limit to project | machine | all (default: all)' },
     ],
   },
@@ -835,7 +891,16 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Embed mode management',
-    usage: 'construct embed start|stop|status',
+    usage: 'construct embed start|stop|status|list|enable|disable|dry-run',
+    subcommands: [
+      { name: 'start', desc: 'Fork the detached embed daemon' },
+      { name: 'stop', desc: 'Stop the running embed daemon' },
+      { name: 'status [<id>] [--json]', desc: 'Daemon status, or per-capability bindings/filter/runtime/last-tick with an id' },
+      { name: 'list [--json]', desc: 'Available embed capabilities and per-project enabled state (ADR-0061)' },
+      { name: 'enable <id>', desc: 'Enable an embed capability: validate and write .cx/embed/<id>.manifest.json' },
+      { name: 'disable <id>', desc: 'Disable an embed capability (idempotent)' },
+      { name: 'dry-run <id> [--json]', desc: 'Resolve the specialist→providers→filter→framework→authority→runtime chain; no side effects' },
+    ],
   },
   {
     name: 'backup',
@@ -957,7 +1022,19 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Provider management',
-    usage: 'construct provider list|test',
+    usage: 'construct provider list|status|health|validate|test|add|configure',
+    subcommands: [
+      { name: 'list', desc: 'List all resolved providers with capabilities and health' },
+      { name: 'status [--json]', desc: 'Alias of list with breaker state, degradation, and active filter columns' },
+      { name: 'health [id] [--json]', desc: 'Run health probes; exits non-zero if any probe fails' },
+      { name: 'validate <path|id> [--strict] [--json]', desc: 'Validate a manifest file or provider id against the B1 schema' },
+      { name: 'info <id>', desc: 'Show a single provider\'s metadata and config schema' },
+      { name: 'test <id>', desc: 'Run one provider\'s health probe; exits non-zero on failure' },
+      { name: 'add <id> [--json]', desc: 'Scaffold instance config from the provider\'s configSchema defaults, persisted to .cx/providers/<id>.json' },
+      { name: 'configure <id> [--key.path value ...] [--json]', desc: 'Merge + validate instance config (incl. ADR-0060 filter block) against configSchema; rejects with the schema path on failure' },
+      { name: 'plugins <add|remove> <id> [<package>] [--global]', desc: 'Register or remove a plugin provider override' },
+      { name: 'new <name> [--capabilities=...]', desc: 'Scaffold a new provider module' },
+    ],
   },
   {
     name: 'auth:status',
@@ -967,6 +1044,20 @@ export const CLI_COMMANDS = [
     description: 'Check auth status',
     usage: 'construct auth:status',
   },
+  {
+    name: 'approvals',
+    emoji: '✅',
+    category: 'Core',
+    core: true,
+    description: 'Manage pending MCP tool approvals',
+    usage: 'construct approvals list|approve|deny|status',
+    subcommands: [
+      { name: 'list', desc: 'List pending approvals with tool name, requestedAt, requestedBy' },
+      { name: 'approve <id>', desc: 'Approve a pending approval by id' },
+      { name: 'deny <id> [--reason=...]', desc: 'Deny a pending approval by id' },
+      { name: 'status <id>', desc: 'Show the full status of a specific approval' },
+    ],
+  },
   {
     name: 'tags',
     emoji: '🏷',
@@ -1133,7 +1224,7 @@ export const CLI_COMMANDS = [
   { name: 'lint:research',     category: 'Internal', core: false, internal: true, description: 'Internal lint: research artifacts', usage: 'construct lint:research' },
   { name: 'lint:templates',    category: 'Internal', core: false, internal: true, description: 'Internal lint: shipped templates', usage: 'construct lint:templates' },
   { name: 'lint:prompts',      category: 'Internal', core: false, internal: true, description: 'Internal lint: specialist prompt frontmatter + sections', usage: 'construct lint:prompts' },
-  { name: 'specialist',        category: 'Internal', core: false, internal: true, description: 'Maintainer tool: scaffold, edit, and lint specialist prompts', usage: 'construct specialist <create|edit|lint>' },
+  { name: 'specialist',        category: 'Internal', core: false, internal: true, description: 'Maintainer tool: scaffold/edit/lint built-in specialist prompts; `create --custom` scaffolds a user-authored specialist into .cx/org/ or ~/.construct/org/', usage: 'construct specialist <create|edit|lint> [--custom]' },
   { name: 'registry:status',   category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Dev: capability registry inspector', usage: 'construct registry:status [--json]' },
   { name: 'registry:validate', category: 'Internal', core: false, internal: true, surface: 'internal', strictFlags: true, description: 'Validate registry/capabilities.json against repo reality; --unified validates specialists/org (+ .cx overlay) invariants', usage: 'construct registry:validate [--json] [--unified]', options: [
     { flag: '--json', desc: 'Emit the validation report as JSON' },
@@ -1147,7 +1238,7 @@ export const CLI_COMMANDS = [
   { name: 'specialist:add',    category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Add a new specialist to a team', usage: 'construct specialist:add <specialist-id> --team <team-id>' },
   { name: 'specialist:remove', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Remove a specialist from the unified registry', usage: 'construct specialist:remove <specialist-id> [--force]' },
   { name: 'oracle', emoji: '🔮', category: 'Core', core: true, description: 'Oracle meta-controller — fleet health review and bounded-auto maintenance', usage: 'construct oracle start|status|review|pending|approve|gaps|reconcile' },
-  { name: 'matrix', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Living dependency matrix — build/inspect the typed file↔capability↔workflow↔test graph', usage: 'construct matrix build|stat|query <node-id> [--json]' },
+  { name: 'matrix', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Deprecated alias of `construct graph` — living dependency graph', usage: 'construct matrix build|stat|query|validate <node-id> [--json]' },
   { name: 'impact', category: 'Diagnostics', core: false, internal: false, surface: 'thin-cli', description: 'Change-impact analysis — map changed files to affected tests, capabilities, and workflows', usage: 'construct impact [files…] [--stdin] [--run] [--json]' },
   { name: 'rules', category: 'Diagnostics', core: false, internal: false, surface: 'thin-cli', description: 'Rule and hook reference telemetry rollup', usage: 'construct rules usage [--since=30d]' },
   { name: 'evaluator:rubrics', category: 'Internal', core: false, internal: true, description: 'Internal: list registered evaluator rubrics', usage: 'construct evaluator:rubrics' },

package/lib/comment-lint.mjs

@@ -4,6 +4,12 @@
  * lintFile(path) checks a single file. lintRepo({ rootDir, fix }) checks all
  * scoped paths and optionally inserts stub headers for files missing one.
  * Used by `construct lint:comments`, the comment-lint PostToolUse hook, and CI.
+ * Also enforces the future-state doc marker convention (construct-9oi4.15.3 /
+ * LMCP-O3): a guide/operations doc claiming a capability is "staged/
+ * experimental" or "not yet {implemented,active,shipped,supported}" must cite
+ * a construct-* bead id within two lines. And bans naming another project by
+ * name in a code comment (BANNED_EXTERNAL_PROJECTS) outside docs/decisions/**
+ * and docs/notes/**, where a prior-art comparison can carry a citation.
  */
 
 import fs from 'node:fs';
@@ -202,11 +208,125 @@ const BANNED_ARTIFACT = [
   },
 ];
 
+// Future-state doc markers (construct-9oi4.15.3 / LMCP-O3): a guide or
+// operations doc that tells the reader a capability is "staged/experimental"
+// or "not yet {implemented,active,shipped,supported}" must cite a tracked
+// construct-* bead within two lines, or the claim is unfalsifiable — nobody
+// can check whether the gap is still open. Scope is guides/operations/README,
+// matching where the M3 sweep (construct-9oi4.13.3) found and fixed its
+// contradictions. ADRs/RFCs carry their own Status/Tracking header convention
+// and docs/notes/research/** are working notes, not shipped-behavior claims —
+// both excluded. hooks-deprecated.md is excluded: it is a self-governing
+// ledger of removed hooks (checked separately by `construct doctor`), not a
+// forward-looking capability claim.
+
+const FUTURE_STATE_DOC_INCLUDE = [
+  /^docs\/guides\//,
+  /^docs\/operations\//,
+  /^docs\/README\.md$/,
+];
+
+const FUTURE_STATE_DOC_EXCLUDE = [
+  /^docs\/guides\/reference\/hooks-deprecated\.md$/,
+];
+
+function isFutureStateDocPath(rel) {
+  return FUTURE_STATE_DOC_INCLUDE.some((r) => r.test(rel)) && !FUTURE_STATE_DOC_EXCLUDE.some((r) => r.test(rel));
+}
+
+const FUTURE_STATE_MARKERS = [
+  /\bstaged\/experimental\b/i,
+  /\bnot\s+yet\s+(?:implemented|active|shipped|supported)\b/i,
+  /\bplanned[;:—-]+\s*not\s+(?:yet\s+)?implemented\b/i,
+];
+
+const BEAD_ID_RE = /\bconstruct-[a-z0-9]+(?:\.[a-z0-9]+)*\b/i;
+
+function hasBeadIdNearby(lines, idx) {
+  const lo = Math.max(0, idx - 2);
+  const hi = Math.min(lines.length, idx + 3);
+  for (let i = lo; i < hi; i++) {
+    if (BEAD_ID_RE.test(lines[i])) return true;
+  }
+  return false;
+}
+
+function checkFutureStateMarkers(content, rel) {
+  if (!isFutureStateDocPath(rel)) return [];
+  const lines = content.split('\n');
+  const skip = buildSkipMap(lines);
+  const violations = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (skip[i]) continue;
+    if (lines[i].includes('construct-lint-ignore')) continue;
+    for (const pattern of FUTURE_STATE_MARKERS) {
+      if (pattern.test(lines[i]) && !hasBeadIdNearby(lines, i)) {
+        violations.push({
+          line: i + 1,
+          label: 'future-state doc marker ("staged/experimental" / "not yet implemented" / "planned — not implemented") has no construct-* bead id within 2 lines (rules/common/no-fabrication.md)',
+          kind: 'artifact',
+        });
+      }
+    }
+  }
+  return violations;
+}
+
 function isBannedCheckSkipped(filePath) {
   if (!filePath) return false;
   return BANNED_CHECK_SKIP.some((suffix) => filePath.endsWith(suffix));
 }
 
+// External project names named in a code comment read as an unverifiable
+// comparison — no-fabrication requires prior-art comparisons carry a citation,
+// and only a decision document carries one. docs/decisions/** and docs/notes/**
+// are that citation-bearing exception; every other comment in the repo
+// describes this codebase's own behavior. A variant of CMT excludes the `//`
+// in a URL scheme (`https://…`) so a cited reference link doesn't misread as
+// a comment marker — this check runs on markdown prose too, unlike the other
+// BANNED entries above, so citation URLs are common in its input.
+
+const BANNED_EXTERNAL_PROJECTS = ['CrewAI', 'LangGraph', 'AutoGen', 'LangChain', 'MetaGPT', 'Aider', 'Devin'];
+
+const EXTERNAL_PROJECT_CMT = '(?:(?<!:)\\/\\/|^\\s*\\*(?!\\/))';
+
+const EXTERNAL_PROJECT_NAME_RE = new RegExp(
+  `${EXTERNAL_PROJECT_CMT}.*\\b(?:${BANNED_EXTERNAL_PROJECTS.join('|')})\\b`,
+  'i',
+);
+
+const EXTERNAL_PROJECT_EXEMPT_GLOBS = [
+  /^docs\/decisions\//,
+  /^docs\/notes\//,
+];
+
+function isExternalProjectExempt(rel) {
+  return EXTERNAL_PROJECT_EXEMPT_GLOBS.some((r) => r.test(rel));
+}
+
+function checkExternalProjectNames(content, filePath, rel) {
+  if (isBannedCheckSkipped(filePath)) return [];
+  if (isExternalProjectExempt(rel)) return [];
+
+  // Same JS/TS comment-convention scope as checkBanned: the "// " / " * "
+  // detection matches markdown's own "**bold**"/"* bullet" syntax as a
+  // false positive, so markdown/MDX prose is out of scope for this check.
+  if (filePath && ['.md', '.mdx'].includes(path.extname(filePath))) return [];
+  const lines = content.split('\n');
+  const violations = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes('construct-lint-ignore')) continue;
+    if (EXTERNAL_PROJECT_NAME_RE.test(lines[i])) {
+      violations.push({
+        line: i + 1,
+        label: 'external project name in a code comment — prior-art comparisons belong in docs/decisions or docs/notes with citations (rules/common/comments.md)',
+        kind: 'artifact',
+      });
+    }
+  }
+  return violations;
+}
+
 // Track fenced code blocks ( ``` … ``` ) and YAML frontmatter ( --- … --- )
 // so artifact-prose patterns inside code or metadata are not flagged.
 function buildSkipMap(lines) {
@@ -327,11 +447,8 @@ function checkArtifactBanned(content, rel) {
 // path and must never throw on a missing or malformed registry file.
 
 export const KNOWN_CX_ROLE_IDS = [
-  'accessibility', 'ai-engineer', 'architect', 'business-strategist', 'data-analyst',
-  'data-engineer', 'debugger', 'designer', 'devil-advocate', 'docs-keeper', 'engineer',
-  'evaluator', 'explorer', 'legal-compliance', 'operations', 'oracle', 'orchestrator',
-  'platform-engineer', 'product-manager', 'qa', 'rd-lead', 'release-manager', 'researcher',
-  'reviewer', 'security', 'sre', 'test-automation', 'trace-reviewer', 'ux-researcher',
+  'architect', 'data-analyst', 'debugger', 'designer', 'engineer', 'operations',
+  'orchestrator', 'product-manager', 'qa', 'researcher', 'reviewer', 'security',
 ];
 
 const CX_ROLE_LEAK = new RegExp(
@@ -392,8 +509,8 @@ function findToolIdentityLeaks(content) {
 function checkBanned(content, filePath) {
   if (isBannedCheckSkipped(filePath)) return [];
 
-  // Banned patterns are JS/TS comment conventions — they don't apply to markdown prose.
-  if (filePath && path.extname(filePath) === '.md') return [];
+  // Banned patterns are JS/TS comment conventions — they don't apply to markdown/MDX prose.
+  if (filePath && ['.md', '.mdx'].includes(path.extname(filePath))) return [];
 
   const warnings = [];
   const lines = content.split('\n');
@@ -465,6 +582,8 @@ export function lintFile(filePath, { rootDir = process.cwd(), fix = false } = {}
   // the finding.
   const artifactHits = checkArtifactBanned(content, rel);
   if (isArtifactPath(rel)) artifactHits.push(...findDanglingCitations(content, { rootDir }));
+  artifactHits.push(...checkFutureStateMarkers(content, rel));
+  artifactHits.push(...checkExternalProjectNames(content, filePath, rel));
   if (artifactHits.length > 0) {
     const mode = process.env.CONSTRUCT_ARTIFACT_LINT_MODE || 'warn';
     const bucket = mode === 'block' ? errors : warnings;
@@ -514,7 +633,7 @@ export function lintRepo({ rootDir = process.cwd(), fix = false } = {}) {
     const rel = relPath(rootDir, f);
     const { required } = requiresHeader(rel);
     const ext = path.extname(f);
-    if (!required && !['.mjs', '.md', '.sh'].includes(ext)) continue;
+    if (!required && !['.mjs', '.md', '.mdx', '.sh'].includes(ext)) continue;
     const result = lintFile(f, { rootDir, fix });
     if (result.errors.length || result.warnings.length) results.push(result);
   }