@geraldmaron/construct 1.0.21 → 1.0.23

package/lib/uninstall/uninstall.mjs

@@ -14,11 +14,18 @@
  *   - auto: removed when --yes is passed; included in the interactive list pre-checked
  *   - ask : never auto-removed; interactive list shows them unchecked
  *
+ * Per ADR-0027 §Consequences, shared Docker images stay by default because
+ * other projects may use the same pgvector base; the pgvector image is removed
+ * only under --with-images. The LaunchAgent registration and a Construct-set
+ * `core.hooksPath` are reversed because they are state install/init created and
+ * own; a user-customized hooksPath is left untouched.
+ *
  * Flags:
  *   --dry-run             print the plan, change nothing
  *   --yes                 non-interactive; remove auto-risk items, skip ask-risk items
  *   --yes --all           non-interactive; remove both auto- and ask-risk items
  *   --keep-state          only remove project-scope launcher + adapters; preserve .cx/, ~/.construct, Postgres
+ *   --with-images         also remove the shared pgvector Docker image (off by default; ADR-0027)
  *   --scope=project|machine|all   limit which categories are evaluated (default: all)
  */
 
@@ -30,11 +37,15 @@ import { fileURLToPath } from 'node:url';
 
 import { multiSelect } from '../tty-prompts.mjs';
 import { getUserConfigDir, getUserEnvPath } from '../env-config.mjs';
+import { removeTomlTables, tomlString } from '../codex-config.mjs';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..', '..');
 
 const POSTGRES_CONTAINER = 'construct-postgres';
+const PGVECTOR_IMAGE = 'pgvector/pgvector:pg16';
+const PRESSURE_GUARD_LABEL = 'dev.construct.pressure-release';
+const MEMORY_MCP_KEYS = ['memory', 'cass'];
 
 export function parseArgs(argv) {
   const args = {
@@ -42,6 +53,7 @@ export function parseArgs(argv) {
     yes: false,
     all: false,
     keepState: false,
+    withImages: false,
     scope: 'all',
     home: os.homedir(),
     cwd: process.cwd(),
@@ -51,6 +63,7 @@ export function parseArgs(argv) {
     else if (arg === '--yes' || arg === '-y') args.yes = true;
     else if (arg === '--all') args.all = true;
     else if (arg === '--keep-state') args.keepState = true;
+    else if (arg === '--with-images') args.withImages = true;
     else if (arg.startsWith('--scope=')) args.scope = arg.slice('--scope='.length);
     else if (arg.startsWith('--home=')) args.home = arg.slice('--home='.length);
     else if (arg.startsWith('--cwd=')) args.cwd = arg.slice('--cwd='.length);
@@ -61,7 +74,7 @@ export function parseArgs(argv) {
   return args;
 }
 
-function buildCategories({ cwd, home }) {
+function buildCategories({ cwd, home, withImages = false }) {
   const dotConstruct = path.join(cwd, '.construct');
   const dotClaudeAgents = path.join(cwd, '.claude', 'agents');
   const dotClaudeCommands = path.join(cwd, '.claude', 'commands');
@@ -77,6 +90,11 @@ function buildCategories({ cwd, home }) {
   const userWorkspace = path.join(userConstructDir, 'workspace');
   const userPgComposeDir = path.join(userConstructDir, 'services', 'postgres');
   const userCxDir = path.join(userHome, '.cx');
+  const launchAgentPlist = path.join(userHome, 'Library', 'LaunchAgents', `${PRESSURE_GUARD_LABEL}.plist`);
+  const claudeSettings = path.join(userHome, '.claude', 'settings.json');
+  const opencodeConfig = path.join(userHome, '.config', 'opencode', 'opencode.json');
+  const codexConfig = path.join(userHome, '.codex', 'config.toml');
+  const memoryConfigPaths = { claudeSettings, opencodeConfig, codexConfig };
 
   return [
     {
@@ -209,12 +227,49 @@ function buildCategories({ cwd, home }) {
       describe: () => 'Removes the local docker-compose.yml. Run after removing the container.',
       execute: () => removePath(userPgComposeDir),
     },
+    {
+      id: 'project-git-hookspath',
+      scope: 'project',
+      risk: 'auto',
+      label: 'git core.hooksPath (.beads/hooks)',
+      detect: () => gitHooksPathIsConstruct(cwd),
+      describe: () => 'Unsets core.hooksPath set by `construct init` to .beads/hooks. A custom hooksPath is left untouched.',
+      execute: () => unsetConstructGitHooksPath(cwd),
+    },
+    {
+      id: 'machine-launchagent',
+      scope: 'machine',
+      risk: 'auto',
+      label: `LaunchAgent ${PRESSURE_GUARD_LABEL} (unload + plist)`,
+      detect: () => process.platform === 'darwin' && existsAny(launchAgentPlist),
+      describe: () => `Unregisters the pressure-release LaunchAgent (launchctl bootout) and removes ${rel(userHome, launchAgentPlist)}.`,
+      execute: () => removePressureGuardLaunchAgent(launchAgentPlist),
+    },
+    {
+      id: 'machine-memory-mcp',
+      scope: 'machine',
+      risk: 'auto',
+      label: 'memory MCP registration (Claude, OpenCode, Codex)',
+      detect: () => memoryMcpRegistered(memoryConfigPaths),
+      describe: () => 'Strips the Construct memory MCP bridge from ~/.claude/settings.json, ~/.config/opencode/opencode.json, and ~/.codex/config.toml. Preserves all other entries.',
+      execute: () => removeMemoryMcp(memoryConfigPaths),
+    },
+    {
+      id: 'machine-pgvector-image',
+      scope: 'machine',
+      risk: 'ask',
+      optIn: true,
+      label: `Docker image "${PGVECTOR_IMAGE}" (--with-images only)`,
+      detect: () => withImages && dockerImageExists(PGVECTOR_IMAGE),
+      describe: () => `Removes the cached ${PGVECTOR_IMAGE} image. Off unless --with-images, since other projects may share it (ADR-0027).`,
+      execute: () => removeDockerImage(PGVECTOR_IMAGE),
+    },
   ];
 }
 
 export async function runUninstall(rawArgs = []) {
   const args = parseArgs(rawArgs);
-  const categories = buildCategories({ cwd: args.cwd, home: args.home });
+  const categories = buildCategories({ cwd: args.cwd, home: args.home, withImages: args.withImages });
 
   const inScope = categories.filter((cat) => {
     if (args.scope !== 'all' && cat.scope !== args.scope) return false;
@@ -235,7 +290,7 @@ export async function runUninstall(rawArgs = []) {
   }
 
   if (args.yes) {
-    toRemove = inScope.filter((cat) => cat.risk === 'auto' || args.all).map((cat) => cat.id);
+    toRemove = inScope.filter((cat) => cat.risk === 'auto' || cat.optIn || args.all).map((cat) => cat.id);
   } else if (!process.stdin.isTTY) {
     console.error('[uninstall] No TTY available. Re-run with --yes (auto-risk only) or --yes --all (everything).');
     process.exit(2);
@@ -275,9 +330,9 @@ async function promptCategories(categories) {
   const options = categories.map((cat) => ({
     label: cat.label,
     value: cat.id,
-    checked: cat.risk === 'auto',
+    checked: cat.risk === 'auto' || Boolean(cat.optIn),
     description: cat.describe(),
-    meta: cat.risk === 'auto' ? 'pre-checked' : 'ask',
+    meta: cat.risk === 'auto' || cat.optIn ? 'pre-checked' : 'ask',
   }));
   try {
     return await multiSelect({
@@ -294,7 +349,7 @@ async function promptCategories(categories) {
 function printPlan(categories, args) {
   console.log(`[uninstall] dry-run plan (scope=${args.scope}${args.keepState ? ', keep-state' : ''}):`);
   for (const cat of categories) {
-    const mark = cat.risk === 'auto' ? '✓' : '◐';
+    const mark = cat.risk === 'auto' || cat.optIn ? '✓' : '◐';
     console.log(`  ${mark} ${cat.label}`);
     console.log(`      ${cat.describe()}`);
   }
@@ -311,7 +366,7 @@ function printFollowups() {
   console.log('');
   console.log('Follow-ups (run by hand if you want):');
   console.log('  npm uninstall @geraldmaron/construct      # drop the package itself');
-  console.log('  docker rmi pgvector/pgvector:pg16          # remove the cached pgvector image');
+  console.log('  construct uninstall --with-images          # also drop the shared pgvector image (kept by default)');
   console.log('  brew uninstall cm cass                     # if installed by `construct init`');
 }
 
@@ -421,3 +476,121 @@ function removeDockerContainer(name) {
   }
   return stop.status === 0 ? 'stopped and removed (with volume)' : 'removed (with volume)';
 }
+
+function dockerImageExists(image) {
+  const probe = spawnSync('docker', ['image', 'inspect', image], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'ignore', 'ignore'],
+  });
+  return probe.status === 0;
+}
+
+function removeDockerImage(image) {
+  const rm = spawnSync('docker', ['rmi', image], { encoding: 'utf8' });
+  if (rm.status !== 0) {
+    throw new Error((rm.stderr || '').trim() || 'docker rmi failed');
+  }
+  return `removed image ${image}`;
+}
+
+// core.hooksPath is reversed only when it still points at the value install/init
+// set (.beads/hooks); a user who repointed it owns that choice and is left alone.
+
+function gitHooksPathIsConstruct(cwd) {
+  const inGit = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  if (inGit.status !== 0) return false;
+  const current = spawnSync('git', ['config', '--get', 'core.hooksPath'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  if (current.status !== 0) return false;
+  return (current.stdout || '').trim() === '.beads/hooks';
+}
+
+function unsetConstructGitHooksPath(cwd) {
+  if (!gitHooksPathIsConstruct(cwd)) return 'core.hooksPath not set to .beads/hooks';
+  const result = spawnSync('git', ['config', '--unset', 'core.hooksPath'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (result.status !== 0) {
+    throw new Error((result.stderr || '').trim() || 'git config --unset failed');
+  }
+  return 'unset core.hooksPath';
+}
+
+// launchctl bootout takes the GUI domain target; unload is the legacy fallback
+// for older macOS. Either deregisters the agent before the plist is deleted so a
+// reinstall starts clean.
+
+function removePressureGuardLaunchAgent(plistPath) {
+  if (!existsAny(plistPath)) return 'no LaunchAgent plist';
+  const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+  if (process.platform === 'darwin') {
+    if (uid != null) {
+      spawnSync('launchctl', ['bootout', `gui/${uid}/${PRESSURE_GUARD_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    spawnSync('launchctl', ['unload', plistPath], { stdio: ['ignore', 'ignore', 'ignore'] });
+  }
+  const removed = removePath(plistPath);
+  return removed ? 'unregistered and removed plist' : 'unregistered (plist already gone)';
+}
+
+function memoryMcpRegistered({ claudeSettings, opencodeConfig, codexConfig }) {
+  return claudeHasMemoryMcp(claudeSettings)
+    || opencodeHasMemoryMcp(opencodeConfig)
+    || codexHasMemoryMcp(codexConfig);
+}
+
+function claudeHasMemoryMcp(filePath) {
+  const settings = readJsonOrNull(filePath);
+  if (!settings || !settings.mcpServers) return false;
+  return MEMORY_MCP_KEYS.some((key) => key in settings.mcpServers);
+}
+
+function opencodeHasMemoryMcp(filePath) {
+  const config = readJsonOrNull(filePath);
+  if (!config || !config.mcp) return false;
+  return MEMORY_MCP_KEYS.some((key) => key in config.mcp);
+}
+
+function codexHasMemoryMcp(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  const text = fs.readFileSync(filePath, 'utf8');
+  return MEMORY_MCP_KEYS.some((key) => text.includes(`[mcp_servers.${key}]`) || text.includes(`[mcp_servers.${tomlString(key)}]`));
+}
+
+// The memory MCP is registered into all three host configs by `construct mcp add
+// memory` during install; each host is stripped independently so a missing or
+// hand-edited config never blocks the others.
+
+function removeMemoryMcp({ claudeSettings, opencodeConfig, codexConfig }) {
+  const stripped = [];
+  if (stripMemoryFromJsonMcp(claudeSettings, 'mcpServers')) stripped.push('claude');
+  if (stripMemoryFromJsonMcp(opencodeConfig, 'mcp')) stripped.push('opencode');
+  if (stripMemoryFromCodex(codexConfig)) stripped.push('codex');
+  return stripped.length ? `stripped from ${stripped.join(', ')}` : 'nothing to strip';
+}
+
+function stripMemoryFromJsonMcp(filePath, mcpKey) {
+  const config = readJsonOrNull(filePath);
+  if (!config || !config[mcpKey]) return false;
+  let changed = false;
+  for (const key of MEMORY_MCP_KEYS) {
+    if (key in config[mcpKey]) { delete config[mcpKey][key]; changed = true; }
+  }
+  if (!changed) return false;
+  if (Object.keys(config[mcpKey]).length === 0) delete config[mcpKey];
+  fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  return true;
+}
+
+function stripMemoryFromCodex(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  const existing = fs.readFileSync(filePath, 'utf8');
+  const tables = MEMORY_MCP_KEYS.flatMap((key) => [`mcp_servers.${key}`, `mcp_servers.${tomlString(key)}`]);
+  const cleaned = removeTomlTables(existing, tables);
+  if (cleaned === existing.trimEnd()) return false;
+  fs.writeFileSync(filePath, `${cleaned.trimEnd()}\n`, 'utf8');
+  return true;
+}
+
+function readJsonOrNull(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+  catch { return null; }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -73,6 +73,7 @@
     "release:check": "node ./bin/construct doctor && npm test && node ./bin/construct docs:update --check && node ./bin/construct dashboard:sync --check && node ./bin/construct lint:comments && node scripts/lint-commits-pr.mjs",
     "release:gate": "node --test tests/functional/release-gate.functional.test.mjs",
     "audit:published": "node scripts/audit-published-artifact.mjs",
+    "version": "node scripts/sync-construct-version.mjs && git add .construct/version",
     "release:preflight": "node scripts/pre-release-check.mjs",
     "release:preflight:no-auth": "node scripts/pre-release-check.mjs --skip-auth",
     "npm:publish": "npm run release:check && npm publish --access public",
@@ -81,7 +82,6 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "js-yaml": "^4.2.0",
-    "node-webvtt": "^1.9.3",
     "postgres": "^3.4.9"
   },
   "optionalDependencies": {

package/personas/construct.md

@@ -25,20 +25,15 @@ Use the single-writer rule whenever multiple sessions are active: if two session
 
 ## Classify before acting
 
-Use the code-backed orchestration policy for intent, execution track, specialist selection, escalation, and approval boundaries. Visual deliverables (wireframes, diagrams, decks) are first-class. use real visual tools, not bullet prose.
+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.
 
-Execution model:
-- **Immediate**. answer or act directly when no hidden worker is needed.
-- **Focused**. dispatch one bounded specialist path; return in Construct's voice.
-- **Orchestrated**. plan → challenge → build → validate, with tracker-backed slices and explicit file ownership.
-
-Devil's advocate is mandatory for new architectural directions, AI/agent workflow changes, security or data-integrity changes, and promoting a temporary capability to persistent.
+Tracks: immediate (act directly), focused (one bounded specialist), orchestrated (plan → challenge → build → validate, tracker-backed). cx-devil-advocate is mandatory whenever `riskFlags` include architecture, security, dataIntegrity, or ai.
 
 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)
 
-`routeRequest` returns three artifacts; honor all three:
+`orchestration_policy` returns three artifacts; honor all three:
 
 1. **Gates**. `framingChallenge`, `externalResearch`, `docAuthoring`
 2. **Contract chain**. typed handoffs from `specialists/contracts.json`. Call `agent_contract` MCP tool at handoff.
@@ -67,6 +62,10 @@ The active profile (`construct profile show`) sets the intake taxonomy. Session-
 
 Lead with the answer. One question when blocked. Confirm what changed when done.
 
+**Output style**: format human-facing output (terminal, prose, dashboard) for neurodivergent readers — answer first, clear hierarchy, scannable chunks, plain language, explicit next step; never rely on color or motion alone; honor `NO_COLOR` and reduced-motion. Presentation only — never reshape machine-readable output (`--json`, parsed tokens, registries, contracts). See `rules/common/neurodivergent-output.md`.
+
+**Tool invisibility**: deliverables are about the user's project, never Construct. Never name Construct, `cx-*` role ids, or internal orchestration mechanics in artifact content unless the subject project is Construct itself. Provenance goes in a comment, not the prose. See `rules/common/tool-invisibility.md`.
+
 Non-trivial work: update Beads (`bd note <id>`), `plan.md`, docs with owner / acceptance / verification. Preserve tracker ids in handoffs. Surface NEEDS_MAIN_INPUT in your voice; resume after the answer. End every session with a handoff at `.cx/handoffs/{date}-{slug}.md` and updates to `.cx/context.md`.
 
 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.

package/platforms/claude/settings.template.json

@@ -30,6 +30,18 @@
         "id": "pre:policy-engine",
         "description": "Consolidated policy gating (bootstrap rule): block mutations until session is grounded via project_context+memory_search or 3+ exploratory reads"
       },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/orchestration-dispatch-guard.mjs\"",
+            "timeout": 5
+          }
+        ],
+        "id": "pre:edit:dispatch-guard",
+        "description": "Block solo-authoring a substantial deliverable when orchestration_policy classified the request as orchestrated and no specialist dispatch has run yet"
+      },
       {
         "matcher": "Bash",
         "hooks": [
@@ -304,6 +316,18 @@
         ],
         "id": "post:audit-trail",
         "description": "Append-only audit log of every mutation — attribution (agent/task) and tamper-evidence chain"
+      },
+      {
+        "matcher": "mcp__.*__orchestration_policy|mcp__.*__orchestration_run|mcp__.*__worker_run|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/orchestration-dispatch-guard.mjs\"",
+            "timeout": 5
+          }
+        ],
+        "id": "post:orchestration:dispatch-guard",
+        "description": "Record orchestration_policy verdict and specialist dispatch so the PreToolUse guard can tell an orchestrated-but-undispatched deliverable write from legitimate post-dispatch synthesis"
       }
     ],
     "PostToolUseFailure": [
@@ -392,11 +416,12 @@
           {
             "type": "command",
             "command": "node \"$HOME/.construct/lib/hooks/stop-typecheck.mjs\"",
-            "timeout": 120
+            "timeout": 120,
+            "async": true
           }
         ],
         "id": "stop:typecheck",
-        "description": "Batch TypeScript typecheck of edited files at end of response"
+        "description": "Batch TypeScript typecheck of edited files at end of response (async: writes ~/.cx/pending-typecheck.txt for the next session-start to surface; does not gate the current turn)"
       },
       {
         "matcher": "*",
@@ -430,11 +455,12 @@
           {
             "type": "command",
             "command": "node \"$HOME/.construct/lib/hooks/pre-compact.mjs\"",
-            "timeout": 15
+            "timeout": 15,
+            "async": true
           }
         ],
         "id": "stop:snapshot",
-        "description": "Snapshot .cx/context.md at session end so resume has real progress"
+        "description": "Snapshot .cx/context.md at session end so resume has real progress (async: written for the NEXT session to read; does not gate the current turn)"
       },
       {
         "matcher": "*",

package/platforms/opencode/config.template.json

@@ -20,8 +20,8 @@
       "options": {
         "baseURL": "https://openrouter.ai/api/v1",
         "headers": {
-          "HTTP-Referer": "__OPENROUTER_REFERER__",
-          "X-Title": "__OPENROUTER_TITLE__",
+          "HTTP-Referer": "https://github.com/geraldmaron/construct",
+          "X-Title": "Construct",
           "Authorization": "Bearer __OPENROUTER_API_KEY__"
         }
       },

package/rules/common/neurodivergent-output.md

@@ -0,0 +1,66 @@
+---
+description: every human-facing Construct output is formatted for neurodivergent readers — without reshaping machine-readable output.
+enforced_by: (persona prompt), tests/term-format.test.mjs, construct dashboard:sync --check
+precedence_tier: style
+---
+# Neurodivergent-Friendly Output
+
+Construct's output is read under load — in a terminal, mid-task, often by people who process text differently. Dense walls of prose, buried conclusions, inconsistent structure, and meaning carried only by color cost every reader attention, and cost neurodivergent readers more. This rule applies to **every human-facing output** Construct produces: terminal output, agent prose to the user, reports, error messages, and the dashboard.
+
+It is a `style` rule by design. The precedence resolver (`rules/common/precedence.md`) guarantees a style rule never overrides a higher tier — so when accessible formatting would conflict with correct machine output, correctness wins automatically. Section 0 states that boundary explicitly.
+
+## 0. The human/machine boundary (read this first)
+
+Two layers, treated differently:
+
+- **Presentation layer (human-facing)** — section titles, prose, help text, report narratives, guidance notes, error wording, dashboard markup and CSS. This is what the rest of this rule shapes.
+- **Data layer (machine-readable)** — never reshape it for readability. Off-limits: any `--json` / `--plain` output; `specialists/registry.json`, `contracts.json`, `role-manifests.json`; the parsed tokens hooks emit (for example the session-start `## Working branch: **<name>**` line, the efficiency status enum `degraded` / `configured` / `healthy`, commit hashes, counts); auxiliary state JSON; any text one component parses out of another.
+
+When a format choice would change a value, key, ordering, or token that something downstream parses, do not make it. Accessibility is presentation; it never edits the contract.
+
+## 1. Lead with the answer
+
+State the conclusion first, then the support. The reader should get the outcome — what happened, what is needed, what changed — in the first line, before any reasoning. Put deliberation after the answer, or leave it out.
+
+## 2. One clear hierarchy
+
+Use headings in order (H2, then H3) and do not skip or nest deeper. One `h1`-equivalent per surface. A reader should be able to scan headings alone and know the shape of the output.
+
+## 3. Scannable chunks
+
+Short paragraphs. Bulleted or numbered lists in place of long sentences that pack several facts together. White space between sections. Prefer three short lines over one dense one.
+
+## 4. Plain, literal language
+
+Say the thing directly. Avoid idioms, sarcasm, irony, and figurative phrasing that require inference to decode. Define a term on first use or link to where it is defined. One name for one concept — do not alternate synonyms for the same thing.
+
+## 5. Consistent structure and terminology
+
+The same kind of output keeps the same shape every time. Status reports, error messages, and command help follow a predictable order so the reader learns the pattern once. Predictability lowers cognitive load more than cleverness raises it.
+
+## 6. Explicit state and next step
+
+End human-facing output with the current state and the next action in plain words — what is done, what is blocked, what the reader does next. Never bury the ask. Never imply a next step through tone.
+
+## 7. Never let color, emoji, or motion be the only signal
+
+- Meaning carried by color must also be carried by text, shape, or label. A red number is also labelled `error`; a green check is also the word `passed`.
+- Honor `NO_COLOR`, non-TTY, and `TERM=dumb`: degrade to plain text, never to nothing.
+- Respect terminal width — wrap rather than overflow.
+- On the dashboard, honor `prefers-reduced-motion` and `prefers-color-scheme`; motion is never required to understand state, and animation can be fully disabled.
+
+## Applies to
+
+- **Terminal / CLI** — help text, status, reports, hook display. Routed through the shared formatter (`lib/term-format.mjs`); color and width handled there, never per-call.
+- **Agent prose** — every response Construct and its specialists return to the user.
+- **Dashboard** — `apps/dashboard/` source (semantic landmarks, labels, focus, contrast, reduced-motion), rebuilt into `lib/server/static/`.
+
+## Enforcement
+
+- Persona prompt: `personas/construct.md` carries the output-style directive; specialists inherit the standard through the front-door agent.
+- `tests/term-format.test.mjs` asserts the terminal formatter honors `NO_COLOR` / non-TTY and that machine-readable `--json` output is unchanged by presentation changes.
+- `construct dashboard:sync --check` keeps the built dashboard in step with the accessible source.
+
+## Bypass
+
+There is no bypass. If a format choice and a machine contract conflict, the contract wins (Section 0) — change the presentation, never the data. If this rule is wrong-shaped, fix the rule, not the output.

package/rules/common/tool-invisibility.md

@@ -0,0 +1,37 @@
+---
+description: deliverable artifacts are about the user's project, never about Construct or its internal machinery.
+enforced_by: (persona prompt), lib/comment-lint.mjs
+precedence_tier: correctness
+---
+# Tool Invisibility
+
+Construct is scaffolding. The artifacts it helps produce — strategies, PRDs, ADRs, research briefs, memos, knowledge notes — belong to the user and their project. The user's document must carry no fingerprints of the tool that built it. A strategy authored through Construct should read exactly as if the user wrote it about their own product, with zero trace of the orchestration underneath.
+
+This failed once, instructively: a strategy for a third-party project came back saying "Construct's bet is to own the layer…" and named `cx-product-manager` as a metric owner. The tooling had written itself into the user's deliverable. That is the failure this rule prevents.
+
+## 1. The artifact is about its subject, not its author
+
+A deliverable is about the project it concerns. Do not make Construct — or the act of using Construct — the subject of content it produces for another project. When the strategy is for *their* platform, the bets are *theirs*, not "Construct's."
+
+## 2. Never name the tool or its internals in artifact content
+
+In the body of any deliverable artifact, do not write:
+
+- **`Construct`** as the product/company/subject (when the subject is not Construct).
+- **`cx-*` specialist role ids** (`cx-business-strategist`, `cx-product-manager`, `cx-researcher`, …). These are internal routing detail — the persona already states that "internal routing and specialist dispatch are implementation detail." A metric owner is a real role on the user's team (e.g. "Product", "Eng lead"), never a `cx-*` id.
+- **Internal orchestration mechanics** — task-packets, `orchestration_run`, dispatch chains, handoff contracts — as if they were part of the user's product.
+
+Provenance belongs in a comment or a separate handoff, not in the deliverable's prose.
+
+## 3. The one exception: when the subject *is* Construct
+
+When the project being worked on is Construct itself (this repo, package `@geraldmaron/construct`), naming Construct and its specialists is correct and required — the artifact is genuinely about them. The deterministic check below is disabled for the Construct repo for exactly this reason.
+
+## Enforcement
+
+- **Prevention (persona + shared guidance):** every specialist and the Construct persona carry the invisibility directive, so the leak is avoided at generation time. This is the primary control; framing ("don't make the doc about Construct") is a judgment call the prompt owns.
+- **Backstop (deterministic):** `lib/comment-lint.mjs` flags `cx-*` internal role-id tokens that appear in a *consuming project's* deliverable markdown — an unambiguous leak with near-zero false positives. The check is skipped when the working repo is Construct itself (package name `@geraldmaron/construct`). Severity follows `CONSTRUCT_ARTIFACT_LINT_MODE` (warn by default; block in the release gate).
+
+## Bypass
+
+There is no bypass. If the check fires on a legitimate use, the use is almost certainly a leak — rewrite the artifact to be about the user's project. If the subject genuinely is Construct, the self-repo skip already covers it.