@geraldmaron/construct 1.0.24 → 1.1.1

package/lib/opencode-telemetry.mjs

@@ -177,6 +177,13 @@ export async function onChatMessage(input, output, { env = process.env } = {}) {
 
 // ── Hook: chat.params ───────────────────────────────────────────────────────
 export async function onChatParams(input, output, { env = process.env } = {}) {
+  // The tool surface is NOT mutable here. OpenCode 1.15.4's chat.params `output`
+  // carries only sampler params (temperature/topP/topK/maxOutputTokens/options)
+  // — there is no tool list to filter (verified empirically 2026-06-09). Surface
+  // reduction therefore happens at the two points that actually control it:
+  // construct-mcp's own ListTools (the lean core + construct_call gateway) and
+  // sync disabling the heavy external MCP servers in opencode.json for local
+  // setups. Do not re-add tool pruning to this hook — it is a no-op.
   const ingest = getIngestClient(env);
   if (!ingest.available) return;
   const sessionId = input?.sessionID;

package/lib/orchestration-policy.mjs

@@ -123,10 +123,40 @@ export function extractNamedEntities(request = '') {
   });
 }
 
+// Research-shaped intent is the vocabulary of external and landscape research —
+// where the answer lives in papers, vendor docs, standards, or the market, not
+// in the local code. Grouped by shape so the matched kind rides on the gate
+// result and the decision is traceable. A false positive here is cheap (it only
+// offers the cx-researcher specialist, with no routing latency and no heavy-flow
+// coupling), so the set is tuned for recall; the precision floor is that a
+// code-walkthrough of the user's own system ("explain how X works") carries none
+// of these terms and stays answered from local context.
+const RESEARCH_SHAPE_PATTERNS = [
+  ['comparative', [/\bcompare\b/, /\bcomparison\b/, /\bcompared to\b/, /\bversus\b/, /\bhead[\s-]?to[\s-]?head\b/, /\btrade[\s-]?offs?\b/, /\bpros and cons\b/, /\balternatives\b/, /\balternative to\b/]],
+  ['selection', [/\bbest (approach(es)?|option|tool|library|framework|pattern|way to|method)\b/, /\bwhich\b.{0,40}\b(should|to)\b.{0,15}\b(use|choose|pick|adopt|go with)\b/, /\brecommend(ed|ation)?\b.{0,30}\b(tool|library|framework|approach|stack|way|practice)\b/, /\boptions for\b/]],
+  ['landscape', [/\blandscape\b/, /\bstate[\s-]of[\s-]the[\s-]art\b/, /\bsurvey of\b/, /\boverview of\b/, /\becosystem\b/, /\bprior art\b/, /\bliterature\b/, /\bexisting (solutions|approaches|tools|work)\b/, /\bwhat'?s out there\b/]],
+  ['market', [/\bmarket (research|analysis|share|size|landscape|trends?)\b/, /\bcompetitive (analysis|landscape)\b/, /\bcompetitors?\b/, /\bindustry (standard|trends?|benchmarks?)\b/, /\bpricing (comparison|models?|tiers?)\b/, /\badoption (rate|trends?)\b/]],
+  ['benchmark', [/\bbenchmarks?\b/, /\bbenchmarking\b/, /\bevaluate (options|alternatives|tools|approaches)\b/, /\bperformance comparison\b/]],
+  ['standards', [/\bbest practices?\b/, /\bindustry standard\b/, /\bconventions? for\b/, /\brecommended (way|approach|practice)\b/, /\brfc\s?\d+\b/, /\bspecification for\b/]],
+];
+
+/**
+ * Classify a request's research shape, or null when it carries none. The
+ * returned category names which kind of external research the prompt implies.
+ */
+export function classifyResearchShape(request = '') {
+  const text = String(request).toLowerCase();
+  for (const [category, patterns] of RESEARCH_SHAPE_PATTERNS) {
+    if (includesAny(text, patterns)) return category;
+  }
+  return null;
+}
+
 /**
  * Returns whether external research is required before scaffolding, with the
- * reason. Triggered by named entities not in the project glossary, or by
- * architecture / writing / research-driven work regardless of entities.
+ * reason. Triggered by named entities not in the project glossary, by
+ * architecture / writing / docs work, or by research-shaped intent regardless of
+ * entities.
  */
 export function requiresExternalResearch({ request = '', workCategory, riskFlags } = {}) {
   const entities = extractNamedEntities(request);
@@ -138,10 +168,15 @@ export function requiresExternalResearch({ request = '', workCategory, riskFlags
   if (category === WORK_CATEGORIES.writing || flags.architecture || flags.docs) {
     return { required: true, reason: 'writing-or-architecture' };
   }
-  // Research intent alone doesn't force external-source research — a simple
-  // code walkthrough ("explain how X works") is research intent but doesn't
-  // need primary-source citations. Only fire when combined with a broader
-  // scope that implies the answer isn't in the immediate code context.
+  // Research-shaped intent (compare, landscape, market, standards, …) fires even
+  // without a named entity, since the answer is external. Bare research intent
+  // does not: a code walkthrough ("explain how X works", "understand the
+  // retrieval path") carries none of these terms and stays answered from local
+  // context — the distinction that keeps the gate from firing on every prompt.
+  const shape = classifyResearchShape(request);
+  if (shape) {
+    return { required: true, reason: 'research-shaped', shape };
+  }
   return { required: false };
 }
 

package/lib/persona-sections.mjs

@@ -0,0 +1,66 @@
+/**
+ * lib/persona-sections.mjs — Capability-tiered persona section rendering.
+ *
+ * A persona is authored once. Each `## ` section carries an inline `<!-- cx:prio=N -->`
+ * marker on its heading; the preamble before the first heading is always prio 1
+ * (identity + anti-fabrication). Small local models follow large multi-instruction
+ * prompts poorly — instruction-following degrades well before the context window fills —
+ * so a weak model receives only the sections it can actually comply with. Tiers:
+ * floor (prio 1, must-keep), mid (prio <= 2), full (all). The marker is stripped from the
+ * emitted text. Untagged `## ` sections default to prio 2 so authoring omissions degrade
+ * gracefully rather than vanishing or forcing a floor model to read everything.
+ */
+
+const TIER_MAX_PRIO = Object.freeze({ floor: 1, mid: 2, full: 3 });
+const PRIO_MARKER = /<!--\s*cx:prio=(\d+)\s*-->/;
+const PRIO_MARKER_GLOBAL = /[ \t]*<!--\s*cx:prio=\d+\s*-->/g;
+
+// The markers are authoring metadata; no emitted prompt (full or tiered) may carry them.
+// Tiered render strips them via section parsing; full render (composePrompt) calls this.
+
+export function stripSectionMarkers(text) {
+  return String(text || "").replace(PRIO_MARKER_GLOBAL, "");
+}
+
+// `## ` (exactly two hashes) is the only section boundary; `### ` subheadings stay with
+// their parent section. The preamble (before the first `## `) is implicit prio 1.
+
+export function parsePersonaSections(body) {
+  const lines = String(body || "").split("\n");
+  const sections = [];
+  let current = { heading: null, prio: 1, lines: [] };
+
+  const flush = () => {
+    const content = current.lines.join("\n").trim();
+    if (content || current.heading) {
+      sections.push({ heading: current.heading, prio: current.prio, content });
+    }
+  };
+
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      flush();
+      const marker = line.match(PRIO_MARKER);
+      const prio = marker ? Number(marker[1]) : 2;
+      const heading = line.replace(PRIO_MARKER, "").trimEnd();
+      current = { heading, prio, lines: [heading] };
+    } else {
+      current.lines.push(line);
+    }
+  }
+  flush();
+  return sections;
+}
+
+export function renderPersonaForTier(body, tier = "full") {
+  const maxPrio = TIER_MAX_PRIO[tier] ?? TIER_MAX_PRIO.full;
+  return parsePersonaSections(body)
+    .filter((section) => section.prio <= maxPrio)
+    .map((section) => stripSectionMarkers(section.content))
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export function personaTierMaxPrio(tier) {
+  return TIER_MAX_PRIO[tier] ?? TIER_MAX_PRIO.full;
+}

package/lib/platforms/capabilities.mjs

@@ -0,0 +1,100 @@
+/**
+ * lib/platforms/capabilities.mjs — loader for the platform capability registry.
+ *
+ * Single source of truth for what each host platform can do (native subagent
+ * routing, hooks + their global-scope allowlist, MCP support, config format,
+ * local-model provisioning, instructions-only). The host enumeration, the
+ * displayName-to-id map, the hasNativeSubagents matrix, and the global hook /
+ * MCP allowlists all derive from this one registry so sync and init read host
+ * capabilities as data. See docs/adr/0033-platform-capability-registry.md.
+ *
+ * Hand-rolled validation (no AJV/zod) so this loads dependency-free on the
+ * bootstrap paths that run before npm install — same constraint as
+ * lib/config/schema.mjs. Fails loud on a malformed or unknown-shaped registry:
+ * a silent fall-through to a default would reintroduce exactly the per-host
+ * guesswork this registry exists to remove.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REGISTRY_PATH = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "platforms",
+  "capabilities.json",
+);
+
+const CONFIG_FORMATS = ["json", "toml", "markdown"];
+const PROVISIONING = ["modelfile", "none"];
+
+function fail(msg) {
+  throw new Error(`platform capability registry: ${msg}`);
+}
+
+function validateHost(id, host) {
+  if (!host || typeof host !== "object" || Array.isArray(host)) fail(`host '${id}' must be an object`);
+  const bools = ["hasNativeSubagents", "instructionsOnly", "supportsMcp"];
+  for (const k of bools) {
+    if (typeof host[k] !== "boolean") fail(`host '${id}.${k}' must be a boolean`);
+  }
+  if (typeof host.displayName !== "string" || !host.displayName) fail(`host '${id}.displayName' must be a non-empty string`);
+  if (!CONFIG_FORMATS.includes(host.configFormat)) fail(`host '${id}.configFormat' must be one of ${JSON.stringify(CONFIG_FORMATS)}`);
+  if (!PROVISIONING.includes(host.localModelProvisioning)) fail(`host '${id}.localModelProvisioning' must be one of ${JSON.stringify(PROVISIONING)}`);
+  if (!host.hooks || typeof host.hooks !== "object") fail(`host '${id}.hooks' must be an object`);
+  if (typeof host.hooks.supported !== "boolean") fail(`host '${id}.hooks.supported' must be a boolean`);
+  if (!Array.isArray(host.hooks.globalAllowlist)) fail(`host '${id}.hooks.globalAllowlist' must be an array`);
+  if (!Array.isArray(host.globalMcpAllowlist)) fail(`host '${id}.globalMcpAllowlist' must be an array`);
+}
+
+let cached = null;
+
+export function loadCapabilities() {
+  if (cached) return cached;
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(REGISTRY_PATH, "utf8"));
+  } catch (err) {
+    fail(`could not read/parse ${REGISTRY_PATH}: ${err.message}`);
+  }
+  if (raw.version !== 1) fail(`unsupported version ${raw.version}`);
+  if (!raw.hosts || typeof raw.hosts !== "object") fail("missing hosts object");
+  for (const [id, host] of Object.entries(raw.hosts)) validateHost(id, host);
+  cached = raw;
+  return raw;
+}
+
+// HOST_KEYS — the canonical host enumeration, derived from the registry so it
+// has exactly one definition. Order is the registry's declaration order.
+
+export const HOST_KEYS = Object.keys(loadCapabilities().hosts);
+
+export function getCapability(hostKey) {
+  const host = loadCapabilities().hosts[hostKey];
+  if (!host) fail(`unknown host '${hostKey}' (known: ${HOST_KEYS.join(", ")})`);
+  return host;
+}
+
+export function hasNativeSubagents(hostKey) {
+  return getCapability(hostKey).hasNativeSubagents;
+}
+
+// displayName-to-key lookup, built from the registry — the one place sync and
+// init resolve a detected host's display name to its canonical key.
+
+export function displayNameToKey() {
+  const map = {};
+  for (const [key, host] of Object.entries(loadCapabilities().hosts)) {
+    map[host.displayName] = key;
+  }
+  return map;
+}
+
+export function globalHookAllowlist(hostKey) {
+  return new Set(getCapability(hostKey).hooks.globalAllowlist);
+}
+
+export function globalMcpAllowlist(hostKey) {
+  return new Set(getCapability(hostKey).globalMcpAllowlist);
+}

package/lib/prompt-composer.js

@@ -27,9 +27,10 @@ import {
   resolveModelOperatingProfile,
   selectModelTierForWorkCategory,
 } from './model-router.mjs';
-import { searchObservations } from './observation-store.mjs';
+import { listObservations } from './observation-store.mjs';
 import { routeRequest } from './orchestration-policy.mjs';
 import { resolvePromptEntry, resolvePromptMetadata } from './prompt-metadata.mjs';
+import { stripSectionMarkers } from './persona-sections.mjs';
 import { readRoleFile } from './role-preload.mjs';
 import { estimateTokens, estimatePromptTokens, estimateTokensSync } from './token-engine.js';
 import { cxDir } from './paths.mjs';
@@ -91,14 +92,14 @@ function compactTokens(text, tokenLimit = 300, { modelId = 'default' } = {}) {
   return `${normalized.slice(0, cutIdx)}…`;
 }
 
-function readPromptBody(promptFile, rootDir) {
+export function readPromptBody(promptFile, rootDir) {
   const filePath = path.join(rootDir, promptFile);
   if (!fs.existsSync(filePath)) return '';
   const raw = fs.readFileSync(filePath, 'utf8');
   return stripLeadingYamlFrontmatter(raw).trim();
 }
 
-function stripLeadingYamlFrontmatter(content) {
+export function stripLeadingYamlFrontmatter(content) {
   if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return content;
   const closeIdx = content.indexOf('\n---', 4);
   if (closeIdx === -1) return content;
@@ -108,18 +109,22 @@ function stripLeadingYamlFrontmatter(content) {
 }
 
 function buildLearnedPatternsBlock(agentName, {
-  intent = null,
-  workCategory = null,
   project = null,
   modelId = 'default',
   tokenLimit = MODEL_OPERATING_PROFILES.balanced.learnedPatternsTokens,
 } = {}) {
   try {
     const rootDir = homedir();
-    const query = [agentName, intent, workCategory].filter(Boolean).join(' ');
     const shortName = String(agentName).replace(/^cx-/, '');
-    const results = searchObservations(rootDir, query, {
-      limit: MAX_OBSERVATIONS * 2,
+
+    // Prompt composition runs at sync time (config generation). A live semantic
+    // search here would load the 90MB embedding model and stall sync for ~80s on
+    // a cold cache (and searchObservations is async — its Promise can't be
+    // consumed from this synchronous function). Read the durable observation
+    // index synchronously and rank by confidence + role match instead.
+
+    const results = listObservations(rootDir, {
+      limit: MAX_OBSERVATIONS * 4,
       project: project ?? null,
     });
 
@@ -208,7 +213,7 @@ export function composePrompt(agentName, {
     selectedModel: executionContractModel?.selectedModel ?? modelId,
   });
 
-  fragments.push({ type: 'core', priority: PRIORITY['core'], label: entry.name, content: readPromptBody(entry.promptFile, rootDir), tokenBudget: null });
+  fragments.push({ type: 'core', priority: PRIORITY['core'], label: entry.name, content: stripSectionMarkers(readPromptBody(entry.promptFile, rootDir)), tokenBudget: null });
 
   const shortName = String(agentName).replace(/^cx-/, '');
   const flavorMapping = AGENT_FLAVOR_MAP[shortName];

package/lib/reconcile/agent-instructions-rewrap.mjs

@@ -22,6 +22,7 @@ import {
   injectIntoAgentFile,
   injectConstructBlock,
   buildConstructIntegrationBody,
+  variantForFile,
   CONSTRUCT_INTEGRATION_VERSION,
 } from '../agent-instructions/inject.mjs';
 
@@ -37,8 +38,11 @@ function hasIntegrationBlock(content) {
 // dedups against a sibling Beads block, so the comparison rebuilds the body
 // the same way injectIntoAgentFile does before hashing.
 
-function wouldChange(content) {
-  const body = buildConstructIntegrationBody({ hasBeadsBlock: BEADS_BLOCK_RE.test(content) });
+function wouldChange(content, name) {
+  const body = buildConstructIntegrationBody({
+    hasBeadsBlock: BEADS_BLOCK_RE.test(content),
+    variant: variantForFile(name),
+  });
   const { action } = injectConstructBlock(content, body, CONSTRUCT_INTEGRATION_VERSION);
   return action !== 'unchanged';
 }
@@ -66,7 +70,7 @@ async function detect() {
   if (candidates.length === 0) {
     return { needsRepair: false, summary: 'No agent file carries a CONSTRUCT INTEGRATION block.' };
   }
-  const stale = candidates.filter((c) => wouldChange(c.content)).map((c) => c.name);
+  const stale = candidates.filter((c) => wouldChange(c.content, c.name)).map((c) => c.name);
   if (stale.length === 0) {
     return { needsRepair: false, summary: 'CONSTRUCT INTEGRATION blocks are current.' };
   }
@@ -81,7 +85,7 @@ async function apply() {
   const candidates = candidateFiles();
   const rewrapped = [];
   for (const c of candidates) {
-    if (!wouldChange(c.content)) continue;
+    if (!wouldChange(c.content, c.name)) continue;
     const result = injectIntoAgentFile(c.full, { version: CONSTRUCT_INTEGRATION_VERSION });
     if (result.changed) rewrapped.push(c.name);
   }

package/lib/reflect/extractor.mjs

@@ -7,8 +7,15 @@
  *
  * Caller responsibility: read the transcript file and pass parsed lines.
  * Output is capped at MAX_BYTES to honor the A1 hook's per-session budget.
+ *
+ * Salience: the observation's confidence is the session's deterministic salience
+ * (see lib/reflect/salience.mjs) rather than a flat value, so low-value sessions are
+ * remembered weakly and age out of the live set first under consolidation; a session
+ * with no durable signal is not stored at all.
  */
 
+import { scoreSalience, shouldStore } from './salience.mjs';
+
 // Hard cap on the summary content so a runaway session can't blow up the
 // observation store. 5 KB matches the budget set in the A1 plan.
 const MAX_BYTES = 5 * 1024;
@@ -32,6 +39,10 @@ export function extractSessionObservation({ entries, cwd, sessionId, durationMs
   const stats = collectStats(entries);
   if (stats.assistantTurns === 0 && stats.userTurns === 0) return null;
 
+  // Extraction decision: a session with no durable signal is noise, not memory.
+  if (!shouldStore(stats)) return null;
+  const { salience, signals: salienceSignals } = scoreSalience(stats);
+
   const finalAssistant = stats.lastAssistantText;
   const headline = deriveHeadline(finalAssistant, stats);
 
@@ -64,7 +75,7 @@ export function extractSessionObservation({ entries, cwd, sessionId, durationMs
     summary: headline,
     content,
     tags: buildTags(stats),
-    confidence: 0.7,
+    confidence: salience,
     source: 'auto-reflect',
     extras: {
       sessionId: sessionId || null,
@@ -74,6 +85,8 @@ export function extractSessionObservation({ entries, cwd, sessionId, durationMs
       assistantTurns: stats.assistantTurns,
       toolCallCount: stats.toolCallCount,
       filesTouched: Array.from(stats.filesTouched).slice(0, MAX_FILES),
+      salience,
+      salienceSignals,
     },
   };
 }

package/lib/reflect/salience.mjs

@@ -0,0 +1,65 @@
+/**
+ * lib/reflect/salience.mjs — deterministic "is this worth remembering" score.
+ *
+ * The transcript extractor produces one observation per session and stamped every
+ * one with a flat confidence, so a session that changed the codebase and a trivial
+ * read-only exchange were remembered with equal weight (the mem0/Letta "salience"
+ * gap). This scores a session's durable value from signals already collected — what
+ * tools ran, whether files were mutated, how substantive the exchange was — with no
+ * LLM, matching Construct's offline-first posture.
+ *
+ * The score feeds the observation's `confidence`, so the existing consolidation pass
+ * carries retention on its own — no second mechanism. Consolidation archives a session
+ * only once both older than `archiveAfterDays` and below `archiveBelowConfidence` (0.5),
+ * so a low-salience session ages out of the live set while a high-salience one survives.
+ * `shouldStore` is the extraction decision: a session with no durable signal at all is
+ * not worth an observation.
+ */
+
+// Tools that change durable state are the strongest salience signal; a session
+// that edits the tree is worth more than one that only reads it.
+const MUTATING_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+const READ_TOOLS = new Set(['Read', 'Grep', 'Glob', 'LS']);
+
+function countByPredicate(toolTypes, pred) {
+  let n = 0;
+  for (const [name, count] of toolTypes ?? new Map()) if (pred(name)) n += count;
+  return n;
+}
+
+/**
+ * Score a session's salience in [0.05, 0.95] from its collected stats.
+ * @param {{toolTypes?: Map<string,number>, toolCallCount?: number, assistantTurns?: number, filesTouched?: Set<any>}} stats
+ * @returns {{salience: number, signals: string[]}}
+ */
+export function scoreSalience(stats = {}) {
+  const toolTypes = stats.toolTypes ?? new Map();
+  const mutations = countByPredicate(toolTypes, (t) => MUTATING_TOOLS.has(t));
+  const reads = countByPredicate(toolTypes, (t) => READ_TOOLS.has(t));
+  const bash = countByPredicate(toolTypes, (t) => t === 'Bash');
+  const assistantTurns = stats.assistantTurns ?? 0;
+  const filesTouched = stats.filesTouched?.size ?? 0;
+
+  const signals = [];
+  let score = 0.25;
+  if (mutations > 0) { score += 0.45; signals.push(`mutated ${mutations}× (durable change)`); }
+  else if (bash > 0) { score += 0.15; signals.push(`ran ${bash} bash command(s)`); }
+  else if (reads > 0) { signals.push('read-only/exploratory'); }
+  if (assistantTurns >= 5) { score += 0.1; signals.push(`${assistantTurns} assistant turns (substantive)`); }
+  if (filesTouched >= 3) { score += 0.05; signals.push(`${filesTouched} files in scope`); }
+
+  const salience = Math.max(0.05, Math.min(0.95, Number(score.toFixed(2))));
+  return { salience, signals };
+}
+
+/**
+ * The extraction decision: a session carrying no durable signal — no mutations, no
+ * bash, and barely any exchange — is noise, not memory, and is not stored.
+ */
+export function shouldStore(stats = {}) {
+  const toolTypes = stats.toolTypes ?? new Map();
+  const mutations = countByPredicate(toolTypes, (t) => MUTATING_TOOLS.has(t));
+  const bash = countByPredicate(toolTypes, (t) => t === 'Bash');
+  const assistantTurns = stats.assistantTurns ?? 0;
+  return mutations > 0 || bash > 0 || assistantTurns >= 2;
+}

package/lib/rules-delivery.mjs

@@ -0,0 +1,122 @@
+/**
+ * lib/rules-delivery.mjs — deliver glob-scoped rules to hosts with a native rule format.
+ *
+ * Cursor is the one supported host with a native per-rule glob convention
+ * (`.cursor/rules/*.mdc`, comma-separated `globs` frontmatter, auto-attached when a
+ * matching file enters context). Project sync emits one managed `.mdc` per
+ * glob-scoped rule (`rules/<dir>/<name>.md` with `paths:` frontmatter) whose globs
+ * match files actually present in the project — the project's own contents are the
+ * intent signal, so a Go rule lands only in a repo that contains Go. Emitted files
+ * carry the `construct-` prefix and are swept when their rule stops matching, so
+ * user-authored .mdc files are never touched (ADR-0027 ownership contract).
+ * Claude/Codex/OpenCode have no per-rule glob mechanism; for them rules remain
+ * reference-delivered (cited by path in prose) — see docs/concepts/rules-delivery.md.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.cx', 'dist', 'build', '.next', 'vendor', '.beads']);
+const MAX_FILES = 5000;
+
+function parseRule(absPath) {
+  const raw = fs.readFileSync(absPath, 'utf8');
+  const fm = raw.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!fm) return null;
+  const globs = [...fm[1].matchAll(/^\s*-\s+"([^"]+)"\s*$/gm)].map((m) => m[1]);
+  if (!/^paths:/m.test(fm[1]) || globs.length === 0) return null;
+  const desc = fm[1].match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? '';
+  return { globs, description: desc, body: raw.slice(fm[0].length).trim() };
+}
+
+export function collectGlobScopedRules(rulesDir) {
+  const out = [];
+  const walk = (dir, rel = '') => {
+    let ents;
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const full = path.join(dir, e.name);
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(full, childRel);
+      else if (e.name.endsWith('.md')) {
+        const parsed = parseRule(full);
+        if (parsed) out.push({ rule: childRel.replace(/\.md$/, ''), ...parsed });
+      }
+    }
+  };
+  walk(rulesDir);
+  return out;
+}
+
+// The rule corpus uses simple glob shapes (`**/*.go`, `**/go.mod`, `*.md`); this
+// translates exactly those: `**/` spans directories, `*` stays within a segment.
+
+export function globToRegExp(glob) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*\//g, '\u0001')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\u0001/g, '(?:.*/)?');
+  return new RegExp(`^${escaped}$`);
+}
+
+export function listProjectFiles(targetDir, { maxFiles = MAX_FILES } = {}) {
+  const files = [];
+  const walk = (dir, rel = '') => {
+    if (files.length >= maxFiles) return;
+    let ents;
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (files.length >= maxFiles) return;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) walk(path.join(dir, e.name), rel ? `${rel}/${e.name}` : e.name);
+      } else {
+        files.push(rel ? `${rel}/${e.name}` : e.name);
+      }
+    }
+  };
+  walk(targetDir);
+  return files;
+}
+
+/**
+ * Emit managed per-rule .mdc files into <targetDir>/.cursor/rules/ for every
+ * glob-scoped rule matching the project's own files, and sweep managed files
+ * whose rule stopped matching. Returns { emitted, swept }.
+ */
+export function emitCursorRules({ rulesDir, targetDir, dryRun = false } = {}) {
+  const rules = collectGlobScopedRules(rulesDir);
+  const files = listProjectFiles(targetDir);
+  const outDir = path.join(targetDir, '.cursor', 'rules');
+
+  const wanted = new Map();
+  for (const r of rules) {
+    const regs = r.globs.map(globToRegExp);
+    if (!files.some((f) => regs.some((re) => re.test(f)))) continue;
+    const name = `construct-${r.rule.replace(/\//g, '-')}.mdc`;
+    const mdc = `---\ndescription: ${r.description}\nglobs: ${r.globs.join(', ')}\nalwaysApply: false\n---\n\n${r.body}\n`;
+    wanted.set(name, mdc);
+  }
+
+  const emitted = [];
+  const swept = [];
+  if (!dryRun) {
+    if (wanted.size > 0) fs.mkdirSync(outDir, { recursive: true });
+    for (const [name, mdc] of wanted) {
+      const dest = path.join(outDir, name);
+      if (!fs.existsSync(dest) || fs.readFileSync(dest, 'utf8') !== mdc) {
+        fs.writeFileSync(dest, mdc);
+        emitted.push(name);
+      }
+    }
+    // Sweep only construct-<rule>.mdc files this module owns; construct.mdc (the
+    // front-door pointer) and user-authored files are never touched.
+    let existing = [];
+    try { existing = fs.readdirSync(outDir); } catch { /* no rules dir */ }
+    for (const name of existing) {
+      if (name.startsWith('construct-') && name.endsWith('.mdc') && !wanted.has(name)) {
+        fs.rmSync(path.join(outDir, name), { force: true });
+        swept.push(name);
+      }
+    }
+  }
+  return { emitted, swept, matched: [...wanted.keys()] };
+}