@geraldmaron/construct 1.1.0 → 1.1.1

package/lib/embed/semantic.mjs

@@ -3,8 +3,10 @@
  *
  * Generates embeddings via @huggingface/transformers, caches them to disk,
  * computes cosine similarity, and clusters related signals by topic.
- * All local — no external API calls. Default model is all-MiniLM-L6-v2
- * (384-dimensional vectors, ~50MB on disk, fast inference).
+ * Inference is local and offline (allowRemoteModels=false): the model loads
+ * from local cache only and returns null when no cached weights are present,
+ * never reaching the network. Default model is all-MiniLM-L6-v2 (384-dimensional
+ * vectors, ~50MB on disk, fast inference).
  *
  * Storage:
  *   ~/.cx/cache/embeddings/<sha256>.json — single embedding vector
@@ -37,6 +39,7 @@ async function getEmbedder() {
   try {
     const { pipeline, env: hfEnv } = await import('@huggingface/transformers');
     hfEnv.allowLocalModels = true;
+    hfEnv.allowRemoteModels = false;
     hfEnv.useBrowserCache = false;
     embedder = await pipeline('feature-extraction', MODEL_NAME, {
       quantized: true,

package/lib/handoffs/cleanup.mjs

@@ -10,7 +10,7 @@
  *      surfaced as a warning but never deleted — open work is sacred.
  *
  * The function is idempotent and runs from:
- *   - `construct down` (best effort, time-boxed)
+ *   - `construct stop` (best effort, time-boxed)
  *   - doctor daemon tick (lib/doctor/watchers/handoffs.mjs)
  *   - `construct handoffs prune` (manual)
  *

package/lib/hooks/audit-trail.mjs

@@ -33,11 +33,11 @@
  * @matcher  Edit|Write|MultiEdit|NotebookEdit|Bash
  * @exits 0 = pass
  */
-import { readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { appendBounded, readLastLineAcrossSegments } from '../logging/rotate.mjs';
+import { appendAuditRecord } from '../audit-trail.mjs';
 import { resolveProjectScopedPath } from '../project-root.mjs';
 import { logHookFailure } from './_lib/log.mjs';
 
@@ -77,16 +77,6 @@ function readLastAgent() {
   }
 }
 
-function readPrevLineHash() {
-  try {
-    const lastLine = readLastLineAcrossSegments(AUDIT_FILE);
-    if (lastLine === null) return null;
-    return sha256(lastLine);
-  } catch {
-    return null;
-  }
-}
-
 function truncateSnippet(s, limit = 280) {
   if (!s) return '';
   const str = String(s);
@@ -140,22 +130,18 @@ if (toolName !== 'Bash' && target) {
   }
 }
 
-const record = {
-  ts: new Date().toISOString(),
-  session_id: input?.session_id || null,
-  tool: toolName,
-  agent: readLastAgent(),
-  task: null,
-  cwd,
-  target,
-  detail,
-  content_hash: contentHash,
-  prev_line_hash: readPrevLineHash(),
-};
-
 try {
-  mkdirSync(dirname(AUDIT_FILE), { recursive: true });
-  appendBounded('audit-trail', AUDIT_FILE, JSON.stringify(record) + '\n');
+  appendAuditRecord({
+    ts: new Date().toISOString(),
+    session_id: input?.session_id || null,
+    tool: toolName,
+    agent: readLastAgent(),
+    task: null,
+    cwd,
+    target,
+    detail,
+    content_hash: contentHash,
+  }, { file: AUDIT_FILE });
 } catch (err) {
   logHookFailure({ hook: 'audit-trail', err, phase: 'append' });
 }

package/lib/model-router.mjs

@@ -25,6 +25,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "child_process";
 import { findOpenCodeConfigPath } from "./opencode-config.mjs";
+import { isLocalModel } from "./mcp/tool-budget.mjs";
 import {
   isFreeModel,
   pollFreeModels,
@@ -79,10 +80,21 @@ function normalizeModelOperatingProfile(value) {
   return MODEL_OPERATING_PROFILES[normalized] ? normalized : null;
 }
 
+function parseModelSizeB(model) {
+  const size = String(model || "").toLowerCase().match(/(?:[:/-])(\d+(?:\.\d+)?)b\b/);
+  return size ? parseFloat(size[1]) : null;
+}
+
 function inferSmallModelProfile(selectedModel) {
   const model = String(selectedModel || '').toLowerCase();
   if (!model) return false;
-  if (/^(ollama|local)\//.test(model) && /(?:[:/-])(3b|7b|8b|13b|14b|32b)\b/.test(model)) return true;
+  // Match any parameter-count marker (7b, 24b, 30b, 32b, …) rather than a fixed list —
+  // the old list silently missed 24b/30b, so Devstral-24B and qwen3-coder-30B resolved
+  // to the balanced profile. Treat <=34B local models as small.
+  if (/^(ollama|local)\//.test(model)) {
+    const size = parseModelSizeB(model);
+    if (size !== null && size <= 34) return true;
+  }
   if (/^(anthropic|openrouter\/anthropic)\/.*haiku/.test(model)) return true;
   if (/gpt-5\.1-mini|gemma-3|gemma-4|phi3:mini/.test(model)) return true;
   return false;
@@ -100,6 +112,45 @@ export function resolveModelOperatingProfile({
   return MODEL_OPERATING_PROFILES.balanced;
 }
 
+// Small local models follow large multi-instruction prompts poorly; the binding
+// constraint is instruction-following capacity, not the token window (which the cx32k
+// Modelfile variants already widen). Map a model to the persona section tier it can
+// comply with — floor (must-keep only), mid, or full. A COLLAPSED probe verdict forces
+// floor; otherwise local size estimates the tier and any cloud model gets the full
+// persona, so cloud configs are never slimmed.
+
+export function resolveCapabilityTier({ model, verdict = null } = {}) {
+  if (!isLocalModel(model)) return 'full';
+  if (verdict === 'COLLAPSED') return 'floor';
+  const size = parseModelSizeB(model);
+  if (size === null) return 'floor';
+  if (size >= 24) return 'mid';
+  return 'floor';
+}
+
+const CODE_MODEL_RE = /coder|codellama|starcoder|deepseek-coder|devstral/i;
+
+// Pick the model for the narrow local editor (construct-local) from the DECLARED local
+// inventory rather than the generic fast-tier default (which, for an Ollama family,
+// resolves to a non-code generalist like llama3.2:3b). The editor does bounded code
+// edits, so prefer a code-specialized model in the reliable size band [7,34]B (smallest =
+// cheapest competent editor), then the smallest code model, then the smallest local model
+// of any kind. Candidates should already exclude probe-COLLAPSED models. Returns null only
+// when there are no candidates, so the caller keeps its own fallback.
+
+export function selectLocalEditorModel(candidates = []) {
+  if (!Array.isArray(candidates) || candidates.length === 0) return null;
+  const sized = candidates.map((m) => ({ m, size: parseModelSizeB(m) }));
+  const pick = (arr) => {
+    const band = arr.filter((x) => x.size !== null && x.size >= 7 && x.size <= 34).sort((a, b) => a.size - b.size);
+    if (band.length) return band[0].m;
+    const anySized = arr.filter((x) => x.size !== null).sort((a, b) => a.size - b.size);
+    return anySized.length ? anySized[0].m : arr[0].m;
+  };
+  const coders = sized.filter((x) => CODE_MODEL_RE.test(x.m));
+  return coders.length ? pick(coders) : pick(sized);
+}
+
 /**
  * Provider-family definitions. Each entry contains:
  *   - `test`: RegExp that matches provider URLs.

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/prompt-composer.js

@@ -30,6 +30,7 @@ import {
 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';
@@ -212,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/server/index.mjs

@@ -343,7 +343,7 @@ async function buildStatus() {
     rootDir: ROOT_DIR,
     cwd: process.cwd(),
     homeDir: HOME,
-    // The dashboard is long-lived and `construct up` rewrites managed values in
+    // The dashboard is long-lived and `construct dev` rewrites managed values in
     // ~/.construct/config.env. Read fresh config on every request instead of
     // letting inherited process env shadow updated ports/credentials.
     env: {},

package/lib/server/langfuse-login.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/server/langfuse-login.mjs — Magic-link bridge for local Langfuse.
  *
- * `construct up` seeds Langfuse with deterministic admin creds via the
+ * `construct dev` seeds Langfuse with deterministic admin creds via the
  * LANGFUSE_INIT_* env vars in langfuse/docker-compose.yml. This bridge turns
  * the "Open Langfuse" link in the dashboard into a one-click sign-in: the
  * server fetches a CSRF token from local Langfuse, then returns an HTML
@@ -28,7 +28,7 @@ export async function handleLangfuseLogin(req, res, { baseUrl = LANGFUSE_LOCAL.b
     const csrfResponse = await fetch(`${baseUrl}/api/auth/csrf`, { headers: { Accept: 'application/json' } });
     if (!csrfResponse.ok) {
       res.writeHead(502, HTML_HEADERS);
-      res.end(`<!doctype html><meta charset="utf-8"><title>Langfuse unreachable</title><pre>Could not reach local Langfuse at ${escapeHtml(baseUrl)}. Status: ${csrfResponse.status}. Try \`construct up\` first.</pre>`);
+      res.end(`<!doctype html><meta charset="utf-8"><title>Langfuse unreachable</title><pre>Could not reach local Langfuse at ${escapeHtml(baseUrl)}. Status: ${csrfResponse.status}. Try \`construct dev\` first.</pre>`);
       return;
     }
     const { csrfToken } = await csrfResponse.json();
@@ -53,6 +53,6 @@ export async function handleLangfuseLogin(req, res, { baseUrl = LANGFUSE_LOCAL.b
 </body></html>`);
   } catch (err) {
     res.writeHead(502, HTML_HEADERS);
-    res.end(`<!doctype html><meta charset="utf-8"><title>Langfuse unreachable</title><pre>Could not reach local Langfuse: ${escapeHtml(err?.message || 'unknown error')}. Try \`construct up\` first.</pre>`);
+    res.end(`<!doctype html><meta charset="utf-8"><title>Langfuse unreachable</title><pre>Could not reach local Langfuse: ${escapeHtml(err?.message || 'unknown error')}. Try \`construct dev\` first.</pre>`);
   }
 }

package/lib/service-manager.mjs

@@ -2,7 +2,7 @@
  * lib/service-manager.mjs — start, stop, and describe Construct runtime services.
  *
  * Manages the dashboard process, memory server (cm), and OpenCode. 
- * startServices() is the single entry point for `construct up` —
+ * startServices() is the single entry point for `construct dev` —
  * spawns whatever is available and returns a result per service.
  */
 import { spawn, spawnSync } from 'node:child_process';

package/lib/session-store.mjs

@@ -350,7 +350,7 @@ export function buildResumeContext(session) {
 }
 
 /**
- * Close all active sessions (called on construct down).
+ * Close all active sessions (called on construct stop).
  */
 export function closeAllSessions(rootDir) {
   const index = readIndex(rootDir);

package/lib/setup.mjs

@@ -40,7 +40,7 @@ function printHelp() {
   console.log(`Construct install — machine setup (once per machine)
 
 Usage:
-  construct install [--scope=project|user|both] [--yes] [--no-launch-agent] [--reconfigure] [--with-docling]
+  construct install [--scope=project|user|both] [--yes] [--dry-run] [--no-launch-agent] [--reconfigure] [--with-docling]
 
 Flags:
   --scope=<s>       project | user | both (default: project — see ADR-0029)
@@ -50,6 +50,7 @@ Flags:
                                ~/.claude/* via consent-gated sync).
                       both:    print project guidance, then run user-scope install.
   --yes             accept detected defaults without prompting
+  --dry-run         print the install plan and exit without writing anything
   --no-launch-agent skip macOS LaunchAgent background service registration
   --reconfigure     re-prompt for service consent, ignoring cached answers
   --with-docling    eagerly provision the docling document-extraction venv now
@@ -306,6 +307,36 @@ function printProjectScopeGuidance() {
   console.log('  construct install --scope=both');
 }
 
+// Dry-run renders the user-scope plan as intent only — every line names a write,
+// network call, or service registration that the real run would perform — and
+// returns before touching disk so the preview is provably side-effect-free.
+
+function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent }) {
+  console.log('Construct install — dry-run (no changes written)');
+  console.log('────────────────────────────────────────────────');
+  console.log(`Scope: ${scope}`);
+  if (scope === 'both') {
+    console.log('  · would print project-scope guidance, then run the user-scope plan below');
+  }
+  console.log('\nWould write:');
+  console.log(`  · ${getUserEnvPath(homeDir)} (user config, managed defaults)`);
+  console.log(`  · ${getCanonicalOpenCodeConfigPath(homeDir)} (OpenCode config)`);
+  console.log(`  · ${path.join(homeDir, '.construct', 'lib')} → ${path.join(ROOT_DIR, 'lib')} (hook lib symlink)`);
+  console.log(`  · ${path.join(homeDir, '.construct', 'workspace')} (workspace docs scaffold)`);
+  console.log(`  · ${path.dirname(defaultVectorIndexPath(homeDir))} (LanceDB vector store dir)`);
+  console.log('\nWould check / install runtime tooling:');
+  console.log('  · cm (memory CLI) and cass (session search) when available on PATH');
+  console.log('\nWould reach the network / external services:');
+  console.log('  · embedding model warmup (loads from local cache; offline-safe, no download)');
+  if (withDocling) console.log('  · docling Python venv provisioning via uv (~10 min)');
+  console.log('  · construct sync --quiet, construct sync --global, construct doctor');
+  if (process.platform === 'darwin' && !noLaunchAgent) {
+    console.log('\nWould register macOS LaunchAgent:');
+    console.log(`  · ${path.join(homeDir, 'Library', 'LaunchAgents', 'dev.construct.pressure-release.plist')} (consent-gated)`);
+  }
+  console.log('\nNo files were written. Re-run without --dry-run to apply.');
+}
+
 export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME } = {}) {
   const argSet = new Set(args);
   const isYes = argSet.has('--yes');
@@ -316,7 +347,8 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     return;
   }
 
-  const KNOWN_FLAGS = new Set(['--yes', '--no-launch-agent', '--reconfigure', '--with-docling', '--help', '-h']);
+  const KNOWN_FLAGS = new Set(['--yes', '--dry-run', '--no-launch-agent', '--reconfigure', '--with-docling', '--help', '-h']);
+  const dryRun = argSet.has('--dry-run');
   const withDocling = argSet.has('--with-docling');
   const unknownFlags = args.filter((a) => {
     if (!a.startsWith('-')) return false;
@@ -342,6 +374,11 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     return;
   }
 
+  if (dryRun) {
+    printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent: argSet.has('--no-launch-agent') });
+    return;
+  }
+
   if (scope === 'both') {
     printProjectScopeGuidance();
     console.log('');

package/lib/storage/embeddings-local.mjs

@@ -1,9 +1,11 @@
 /**
  * lib/storage/embeddings-local.mjs — Local ONNX embedding via @huggingface/transformers.
  *
- * Lazy-loads the model, caches to disk, uses a single-worker queue to avoid
- * parallel inference contention. Falls back to hashing-bow-v1 if the model
- * fails to load.
+ * Lazy-loads the model from local cache only and runs inference offline. Falls
+ * back to hashing-bow-v1 when the model is absent or fails to load. Remote model
+ * fetching is disabled (allowRemoteModels=false): the runtime path never reaches
+ * the network, so a first run with no cached weights degrades to the hashing
+ * backend rather than downloading from the HuggingFace hub.
  *
  * Model: Xenova/all-MiniLM-L6-v2 (384 dimensions, quantized)
  */
@@ -29,6 +31,7 @@ async function getExtractor(cacheDir) {
   modelPromise = (async () => {
     const { pipeline, env: hfEnv } = await import('@huggingface/transformers');
     hfEnv.allowLocalModels = true;
+    hfEnv.allowRemoteModels = false;
     hfEnv.useBrowserCache = false;
     try {
       const ex = await pipeline('feature-extraction', MODEL_ID, {

package/lib/storage/file-lock.mjs

@@ -50,17 +50,24 @@ function tryAcquire(lockPath) {
     return true;
   } catch (err) {
     if (err.code !== 'EEXIST') throw err;
-    let holder = null;
-    try { holder = Number(readFileSync(lockPath, 'utf8').trim()); } catch { /* unreadable */ }
-    if (!isHolderAlive(holder)) {
-      try { unlinkSync(lockPath); } catch { /* race */ }
-      try {
-        writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
-        heldLocks.add(lockPath);
-        return true;
-      } catch { return false; }
-    }
-    return false;
+
+    // Steal only from a holder we can positively read as dead. An empty or
+    // unreadable pidfile is the mid-create window of a live holder, not a
+    // crash; stealing it would admit two writers and break an append chain.
+    // The acquire timeout still bounds the wait if the holder truly crashed.
+
+    let raw = '';
+    try { raw = readFileSync(lockPath, 'utf8').trim(); } catch { return false; }
+    if (raw === '') return false;
+    const holder = Number(raw);
+    if (!Number.isFinite(holder) || isHolderAlive(holder)) return false;
+
+    try { unlinkSync(lockPath); } catch { /* another stealer won */ }
+    try {
+      writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+      heldLocks.add(lockPath);
+      return true;
+    } catch { return false; }
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -92,7 +92,9 @@
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
     "@opentelemetry/resources": "^2.7.1",
     "@opentelemetry/sdk-trace-node": "^1.25.0",
-    "@opentelemetry/semantic-conventions": "^1.25.0"
+    "@opentelemetry/semantic-conventions": "^1.25.0",
+    "mammoth": "^1.12.0",
+    "unpdf": "^1.6.2"
   },
   "overrides": {
     "express-rate-limit": "8.5.1"

package/personas/construct.md

@@ -6,7 +6,7 @@ You are Construct. The user talks only to you; internal routing and specialist d
 
 **Anti-fabrication contract**: every load-bearing claim cites a verifiable source. Missing source becomes `unknown` or `[unverified]`. Specialists tailor; the persona never weakens. See `rules/common/no-fabrication.md`.
 
-## Start of every session
+## Start of every session <!-- cx:prio=3 -->
 
 Before responding, run in parallel. do not narrate:
 1. `project_context`. state from `.cx/context.md`
@@ -23,7 +23,7 @@ Honor the project operating hierarchy:
 
 Use the single-writer rule whenever multiple sessions are active: if two sessions would touch the same file, one session owns the edit and the other reviews, researches, or waits for handoff.
 
-## Classify before acting
+## Classify before acting <!-- cx:prio=1 -->
 
 Before any non-trivial request, CALL the code-backed orchestration policy via the `orchestration_policy` MCP tool with the request text and your `fileCount` / `moduleCount` / `introducesContract` estimate. Do not classify from memory. Honor the returned `track` and `specialists`. When `track` is `orchestrated` you may not author the deliverable yourself: emit the task-packet, dispatch the chain, return in Construct's voice after verdicts. Visual deliverables (wireframes, diagrams, decks) use real visual tools, not bullet prose.
 
@@ -31,7 +31,7 @@ Tracks: immediate (act directly), focused (one bounded specialist), orchestrated
 
 Orchestrated dispatches emit a task-packet with `goal`, `intent`, `workCategory`, `riskFlags`, `acceptanceCriteria` before naming specialists (`specialists/contracts.json:construct-to-orchestrator`).
 
-## Gates and contracts (org-in-a-box)
+## Gates and contracts (org-in-a-box) <!-- cx:prio=2 -->
 
 `orchestration_policy` returns three artifacts; honor all three:
 
@@ -41,16 +41,16 @@ Orchestrated dispatches emit a task-packet with `goal`, `intent`, `workCategory`
 
 Before DONE: postconditions met · sources cited · framing logged · ADRs have Rejected alternatives.
 
-## Branch + commit approval
+## Branch + commit approval <!-- cx:prio=1 -->
 
 - **Working branch is surfaced every session** at the top of session-start. Restate it before any mutating operation.
 - **Never commit, push, or merge without asking first.** Before `git commit`, `git push`, or `gh pr merge`: state branch, show the proposed message / refspec / PR number verbatim, wait for explicit yes. A batch go-ahead covers a defined sequence; new commits later are their own gate. See `rules/common/commit-approval.md`.
 
-## Intake surface
+## Intake surface <!-- cx:prio=3 -->
 
 The active profile (`construct profile show`) sets the intake taxonomy. Session-start surfaces pending intake at `.cx/intake/pending/<id>.json`. Read with `construct intake show <id>`; the triage block names the primary owner, recommended chain, and next action. For non-trivial signals, plan with `construct graph from-intake <id>` and update node status with evidence (`construct graph status … done --evidence=…`). A node cannot reach `done` without an evidence record. Team / enterprise mode wraps tool calls in the MCP broker; when it returns `ApprovalRequired`, surface the question and never bypass.
 
-## Action discipline
+## Action discipline <!-- cx:prio=1 -->
 
 - Dispatch, don't solo-plan: 3+ files, 2+ modules, or a new contract → cx-architect owns the plan.
 - Ask or look up, don't speculate: call `context7_query-docs` / `WebFetch`, ask, or commit to a default. Never a fourth round of internal debate.
@@ -58,7 +58,7 @@ The active profile (`construct profile show`) sets the intake taxonomy. Session-
 - Probe before bulk read: check size via `Glob` / `wc -l` or a `limit: 50` probe before `Read` with `limit > 200`.
 - Start-of-task: parallel bootstrap (above) + `cx_trace` before anything mutating.
 
-## Communication + state
+## Communication + state <!-- cx:prio=2 -->
 
 Lead with the answer. One question when blocked. Confirm what changed when done.
 
@@ -70,7 +70,7 @@ Non-trivial work: update Beads (`bd note <id>`), `plan.md`, docs with owner / ac
 
 Load-bearing state: `AGENTS.md`, `.cx/context.md`/`.json`, `docs/README.md`, `docs/architecture.md` (read at session start, update before DONE, prune stale sections). `plan.md` is local-only.
 
-## Quality gates
+## Quality gates <!-- cx:prio=2 -->
 
 After any implementation, dispatch validation before marking done:
 1. cx-reviewer. correctness, regression, coverage
@@ -79,17 +79,17 @@ After any implementation, dispatch validation before marking done:
 
 Do not mark `done` until cx-reviewer and cx-qa return verdicts. BLOCKED or any CRITICAL finding stops shipping.
 
-## Hard release gates
+## Hard release gates <!-- cx:prio=3 -->
 
 Run `npm run release:check` before any commit or push. never wait for CI. Commits follow `.gitmessage`; PRs follow `.github/pull_request_template.md`. Full policy: `rules/common/release-gates.md`.
 
-## Loop guard
+## Loop guard <!-- cx:prio=1 -->
 
 Same action 3+ times with no state change → stop. Report what was tried, what blocked progress, what decision is needed.
 
 Before stopping: surface incomplete tracker-linked plan slices and unmet acceptance criteria. Do not stop silently with work in-flight.
 
-## Drive mode
+## Drive mode <!-- cx:prio=3 -->
 
 Activates on word-boundary triggers. `/work:drive`, standalone `drive`, or `full send`. Substring matches do not count.