@geraldmaron/construct 1.2.1 → 1.2.2

package/lib/telemetry/client.mjs

@@ -5,7 +5,6 @@
  * CONSTRUCT_TRACE_BACKEND and never throws into callers.
  */
 import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 

package/lib/telemetry/intent-verifications.mjs

@@ -13,18 +13,18 @@
  */
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { appendBounded } from '../logging/rotate.mjs';
 import { resolveProjectScopedPath } from '../project-root.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 // intent-verifications are PROJECT-SCOPED — a verification belongs to a
-// specific routing decision in a specific project. DEFAULT_LOG_PATH stays
-// at the legacy user-scope location for back-compat with readers that
-// imported the constant; the writer below resolves per-call so each
-// invocation lands in the project's .cx/ when one is detected.
+// specific routing decision in a specific project. DEFAULT_LOG_PATH resolves
+// to the global doctor root for back-compat with readers that imported the
+// constant; the writer below resolves per-call so each invocation lands in
+// the project's .cx/ when one is detected.
 
-export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'intent-verifications.jsonl');
+export const DEFAULT_LOG_PATH = path.join(doctorRoot(), 'intent-verifications.jsonl');
 
 /**
  * Fire-and-forget append of one verification event.

package/lib/telemetry/model-pricing-catalog.mjs

@@ -15,13 +15,14 @@
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { join } from "path";
-import { homedir } from "os";
+
+import { doctorRoot } from "../config/xdg.mjs";
 
 const OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models";
 const LITELLM_PRICING_URL =
   "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
 const PRICING_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
-const PRICING_CACHE_PATH = join(homedir(), ".cx", "pricing-cache.json");
+const PRICING_CACHE_PATH = join(doctorRoot(), "pricing-cache.json");
 
 export function describePricingCatalogFreshness() {
   try {
@@ -133,7 +134,7 @@ async function fetchLiteLLMPricing(fetchImpl = globalThis.fetch) {
       });
     }
     try {
-      mkdirSync(join(homedir(), ".cx"), { recursive: true });
+      mkdirSync(doctorRoot(), { recursive: true });
       writeFileSync(PRICING_CACHE_PATH, JSON.stringify({ fetchedAt: Date.now(), models }));
     } catch { /* non-critical */ }
     return models;

package/lib/telemetry/rule-calls.mjs

@@ -1,16 +1,16 @@
 /**
  * lib/telemetry/rule-calls.mjs — record when a rule path is referenced at runtime.
  *
- * Mirrors hook-calls telemetry: append-only JSONL at ~/.cx/rule-calls.jsonl.
+ * Mirrors hook-calls telemetry: append-only JSONL at <doctorRoot>/rule-calls.jsonl.
  * Consumed by `construct rules usage` for consolidation decisions.
  */
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { appendBounded } from '../logging/rotate.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
-export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'rule-calls.jsonl');
+export const DEFAULT_LOG_PATH = path.join(doctorRoot(), 'rule-calls.jsonl');
 
 /**
  * @param {object} event

package/lib/telemetry/skill-calls.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/telemetry/skill-calls.mjs — measure which skill files actually get loaded.
  *
- * Appends one JSON line per skill load to ~/.cx/skill-calls.jsonl so
+ * Appends one JSON line per skill load to <doctorRoot>/skill-calls.jsonl so
  * `construct skills usage/orphans/hot/correlate-quality` can answer:
  * which skills have no load events in a 30-day window (pruning candidates),
  * which skills are loaded from many agents (hot paths), and which skills
@@ -15,17 +15,17 @@
  */
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { appendBounded } from '../logging/rotate.mjs';
 import { resolveProjectScope } from '../project-root.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 // Skill calls are CROSS-PROJECT telemetry — a single log lets you see which
 // skills load hot across every project the user has run Construct in. Stays
 // at user scope; each entry is tagged with `projectId` so a reader can
 // attribute usage to a specific project without losing the global view.
 
-export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'skill-calls.jsonl');
+export const DEFAULT_LOG_PATH = path.join(doctorRoot(), 'skill-calls.jsonl');
 
 /**
  * Fire-and-forget log of a skill load event.

package/lib/template-registry.mjs

@@ -70,4 +70,5 @@ export const TEMPLATE_OWNERSHIP_EXEMPTIONS = new Set([
   'rfc-platform',
   'prd-platform',
   'prd-business',
+  'README',
 ]);

package/lib/templates/visual-requirements.mjs

@@ -3,7 +3,7 @@
  *
  * Loads structure and visual requirements from specialists/artifact-manifest.json
  * (single source of truth) and merges legacy types not yet in the manifest.
- * Paired with docs/concepts/doc-visual-matrix.md; pinned by template tests.
+ * Paired with docs/guides/concepts/doc-visual-matrix.md; pinned by template tests.
  */
 
 import { validateArtifactPostconditions } from '../contracts/validate.mjs';

package/lib/test-corpus-inventory.mjs

@@ -173,7 +173,7 @@ export function computeReleaseCriticalGaps(ledger) {
   for (const row of SHIPPED_MATRIX_CAPABILITIES) {
     if (ledgerCoversHint(allLedgerIds, row.ledgerHints)) continue;
     gaps.push({
-      source: 'docs/audit/capability-matrix.md',
+      source: 'docs/operations/audit/capability-matrix.md',
       capability: row.id,
       status: 'shipped',
       reason: 'no ledger entry matches shipped capability hints',

package/lib/uninstall/uninstall.mjs

@@ -24,7 +24,7 @@
  *   --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
+ *   --keep-state          only remove project-scope launcher + adapters; preserve .cx/, the XDG user dirs, 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)
  */
@@ -37,6 +37,7 @@ import { fileURLToPath } from 'node:url';
 
 import { multiSelect } from '../tty-prompts.mjs';
 import { getUserConfigDir, getUserEnvPath } from '../env-config.mjs';
+import { stateDir, cacheDir, doctorRoot } from '../config/xdg.mjs';
 import { removeTomlTables, tomlString } from '../codex-config.mjs';
 import { postgresContainerName, LEGACY_PG_CONTAINER } from '../home-namespace.mjs';
 
@@ -84,12 +85,13 @@ function buildCategories({ cwd, home, withImages = false }) {
   const projectPlanMd = path.join(cwd, 'plan.md');
   const userHome = home;
   const userConstructDir = getUserConfigDir(userHome);
+  const userStateDir = stateDir(userHome);
   const userConfigEnv = getUserEnvPath(userHome);
-  const userEmbedCache = path.join(userConstructDir, 'cache', 'embeddings');
-  const userVectorIndex = path.join(userConstructDir, 'vector');
-  const userWorkspace = path.join(userConstructDir, 'workspace');
+  const userEmbedCache = path.join(cacheDir(userHome), 'embeddings');
+  const userVectorIndex = path.join(userStateDir, 'vector');
+  const userWorkspace = path.join(userStateDir, 'workspace');
   const userPgComposeDir = path.join(userConstructDir, 'services', 'postgres');
-  const userCxDir = path.join(userHome, '.cx');
+  const userCxDir = doctorRoot(userHome);
   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');
@@ -172,7 +174,7 @@ function buildCategories({ cwd, home, withImages = false }) {
       id: 'machine-workspace',
       scope: 'machine',
       risk: 'auto',
-      label: '~/.construct/workspace and ~/.construct/vector',
+      label: `${rel(userHome, userWorkspace)} and ${rel(userHome, userVectorIndex)}`,
       detect: () => existsAny(userWorkspace) || existsAny(userVectorIndex),
       describe: () => 'Removes the per-user working dir and fallback JSON vector index. Both are regenerated on next use.',
       execute: () => {
@@ -186,7 +188,7 @@ function buildCategories({ cwd, home, withImages = false }) {
       id: 'machine-cx',
       scope: 'machine',
       risk: 'auto',
-      label: '~/.cx (daemon state, logs)',
+      label: `${rel(userHome, userCxDir)} (daemon state, logs)`,
       detect: () => existsAny(userCxDir),
       describe: () => `Removes ${rel(userHome, userCxDir)}. Daemon PIDs, telemetry, setup logs; all regenerated on next setup.`,
       execute: () => removePath(userCxDir),
@@ -195,7 +197,7 @@ function buildCategories({ cwd, home, withImages = false }) {
       id: 'machine-embedding-cache',
       scope: 'machine',
       risk: 'ask',
-      label: '~/.construct/cache/embeddings (~22 MB ONNX model)',
+      label: `${rel(userHome, userEmbedCache)} (~22 MB ONNX model)`,
       detect: () => existsAny(userEmbedCache),
       describe: () => 'Removes the cached ONNX embedding model. Skip if you plan to reinstall soon — re-downloading takes a minute.',
       execute: () => removePath(userEmbedCache),
@@ -204,7 +206,7 @@ function buildCategories({ cwd, home, withImages = false }) {
       id: 'machine-config-env',
       scope: 'machine',
       risk: 'ask',
-      label: '~/.construct/config.env (API keys + consent flags)',
+      label: `${rel(userHome, userConfigEnv)} (API keys + consent flags)`,
       detect: () => existsAny(userConfigEnv),
       describe: () => 'Removes saved API keys (Anthropic/OpenAI/telemetry/etc.) and bootstrap consent. Skip if you intend to reinstall and reuse the keys.',
       execute: () => removePath(userConfigEnv),
@@ -231,7 +233,7 @@ function buildCategories({ cwd, home, withImages = false }) {
       id: 'machine-postgres-compose',
       scope: 'machine',
       risk: 'auto',
-      label: '~/.construct/services/postgres/ (compose file)',
+      label: `${rel(userHome, userPgComposeDir)} (compose file)`,
       detect: () => existsAny(userPgComposeDir),
       describe: () => 'Removes the local docker-compose.yml. Run after removing the container.',
       execute: () => removePath(userPgComposeDir),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -52,7 +52,7 @@
   "scripts": {
     "mcp": "node lib/mcp/server.mjs",
     "test": "node scripts/run-tests.mjs",
-    "test:functional": "node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
+    "test:functional": "XDG_CONFIG_HOME= XDG_STATE_HOME= XDG_CACHE_HOME= node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
     "test:unit": "node scripts/run-tests.mjs --exclude=tests/functional",
     "lint:js": "eslint bin/construct \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"tests/**/*.mjs\"",
     "coverage": "c8 --reporter=text-summary --reporter=lcov --src=lib --src=bin node scripts/run-tests.mjs --exclude=tests/functional",
@@ -80,7 +80,7 @@
     "release:check": "node ./bin/construct doctor && npm test && node ./bin/construct docs:update --check && node ./bin/construct docs:site --check && node ./bin/construct registry:generate-docs --check && node ./bin/construct docs:verify --strict && node scripts/alignment/census.mjs --ratchet && node ./bin/construct dashboard:sync --check && node ./bin/construct lint:comments && node ./bin/construct certify gate && 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",
+    "version": "node scripts/sync-construct-version.mjs && git add -f .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",

package/platforms/claude/settings.template.json

@@ -9,7 +9,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/session-start.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/session-start.mjs\"",
             "timeout": 10
           }
         ],
@@ -23,7 +23,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/policy-engine.mjs\" PreToolUse",
+            "command": "node \"$HOME/.config/construct/lib/hooks/policy-engine.mjs\" PreToolUse",
             "timeout": 10
           }
         ],
@@ -35,7 +35,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/orchestration-dispatch-guard.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/orchestration-dispatch-guard.mjs\"",
             "timeout": 5
           }
         ],
@@ -47,7 +47,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/block-no-verify.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/block-no-verify.mjs\"",
             "timeout": 5
           }
         ],
@@ -59,7 +59,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/pre-push-gate.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/pre-push-gate.mjs\"",
             "timeout": 180
           }
         ],
@@ -71,7 +71,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/guard-bash.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/guard-bash.mjs\"",
             "timeout": 5
           }
         ],
@@ -83,7 +83,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/config-protection.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/config-protection.mjs\"",
             "timeout": 5
           }
         ],
@@ -95,7 +95,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/mcp-health-check.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/mcp-health-check.mjs\"",
             "timeout": 3
           }
         ],
@@ -107,7 +107,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/edit-guard.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/edit-guard.mjs\"",
             "timeout": 5
           }
         ],
@@ -133,7 +133,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/scan-secrets.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/scan-secrets.mjs\"",
             "timeout": 10
           }
         ],
@@ -145,7 +145,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/adaptive-lint.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/adaptive-lint.mjs\"",
             "timeout": 30,
             "async": true
           }
@@ -158,7 +158,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/comment-lint.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/comment-lint.mjs\"",
             "timeout": 15
           }
         ],
@@ -170,7 +170,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/brand-prose-lint.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/brand-prose-lint.mjs\"",
             "timeout": 15
           }
         ],
@@ -182,7 +182,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/artifact-release-gate.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/artifact-release-gate.mjs\"",
             "timeout": 15
           }
         ],
@@ -194,7 +194,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/doc-coupling-check.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/doc-coupling-check.mjs\"",
             "timeout": 5
           }
         ],
@@ -206,7 +206,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/graph-impact-advisory.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/graph-impact-advisory.mjs\"",
             "timeout": 10
           }
         ],
@@ -218,7 +218,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/edit-accumulator.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/edit-accumulator.mjs\"",
             "timeout": 3
           }
         ],
@@ -230,7 +230,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/registry-sync.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/registry-sync.mjs\"",
             "timeout": 15,
             "async": true
           }
@@ -243,7 +243,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/dep-audit.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/dep-audit.mjs\"",
             "timeout": 35,
             "async": true
           }
@@ -256,7 +256,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/audit-reads.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/audit-reads.mjs\"",
             "timeout": 3,
             "async": true
           }
@@ -269,7 +269,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/mcp-audit.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/mcp-audit.mjs\"",
             "timeout": 3,
             "async": true
           }
@@ -282,7 +282,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/agent-tracker.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/agent-tracker.mjs\"",
             "timeout": 3,
             "async": true
           }
@@ -295,7 +295,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/bash-output-logger.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/bash-output-logger.mjs\"",
             "timeout": 5
           }
         ],
@@ -307,7 +307,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/test-watch.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/test-watch.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -320,7 +320,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/post-merge-docs-check.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/post-merge-docs-check.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -333,7 +333,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/post-merge-tracking.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/post-merge-tracking.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -346,7 +346,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/audit-trail.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/audit-trail.mjs\"",
             "timeout": 5
           }
         ],
@@ -358,7 +358,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/orchestration-dispatch-guard.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/orchestration-dispatch-guard.mjs\"",
             "timeout": 5
           }
         ],
@@ -372,7 +372,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/model-fallback.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/model-fallback.mjs\"",
             "timeout": 130,
             "async": true
           }
@@ -385,7 +385,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/mcp-health-check.mjs\" --mark-failure",
+            "command": "node \"$HOME/.config/construct/lib/hooks/mcp-health-check.mjs\" --mark-failure",
             "timeout": 3
           }
         ],
@@ -397,7 +397,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/context-window-recovery.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/context-window-recovery.mjs\"",
             "timeout": 60,
             "async": true
           }
@@ -410,7 +410,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/edit-error-recovery.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/edit-error-recovery.mjs\"",
             "timeout": 15,
             "async": true
           }
@@ -425,7 +425,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/pre-compact.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/pre-compact.mjs\"",
             "timeout": 15
           }
         ],
@@ -439,7 +439,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/policy-engine.mjs\" Stop",
+            "command": "node \"$HOME/.config/construct/lib/hooks/policy-engine.mjs\" Stop",
             "timeout": 15
           }
         ],
@@ -451,7 +451,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/stop-typecheck.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/stop-typecheck.mjs\"",
             "timeout": 120,
             "async": true
           }
@@ -464,7 +464,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/readme-age-check.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/readme-age-check.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -477,7 +477,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/stop-notify.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/stop-notify.mjs\"",
             "timeout": 10,
             "async": true
           }
@@ -490,7 +490,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/pre-compact.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/pre-compact.mjs\"",
             "timeout": 15,
             "async": true
           }
@@ -503,7 +503,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/session-optimize.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/session-optimize.mjs\"",
             "timeout": 600,
             "async": true
           }
@@ -516,7 +516,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/session-reflect.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/session-reflect.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -529,7 +529,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/session-tracking-refresh.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/session-tracking-refresh.mjs\"",
             "timeout": 5,
             "async": true
           }
@@ -544,7 +544,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/context-watch.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/context-watch.mjs\"",
             "timeout": 5
           }
         ],
@@ -556,7 +556,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/ci-status-check.mjs\"",
+            "command": "node \"$HOME/.config/construct/lib/hooks/ci-status-check.mjs\"",
             "timeout": 5
           }
         ],

package/rules/common/no-fabrication.md

@@ -55,7 +55,7 @@ Fabrication is the single largest threat to trust in an agent system. A persona
 
 ## Enforcement
 
-- `lib/comment-lint.mjs` enforces a subset of these patterns on artifact paths (`docs/prd/**`, `docs/adr/**`, `docs/rfc/**`, `docs/research/**`, `.cx/knowledge/**`, `.cx/handoffs/**`, `.cx/research/**`). PostToolUse warns; `npm run lint:comments`, `construct lint:comments`, and the release gate block.
+- `lib/comment-lint.mjs` enforces a subset of these patterns on artifact paths (`docs/specs/prd/**`, `docs/decisions/adr/**`, `docs/decisions/rfc/**`, `docs/notes/research/**`, `.cx/knowledge/**`, `.cx/handoffs/**`, `.cx/research/**`). PostToolUse warns; `npm run lint:comments`, `construct lint:comments`, and the release gate block.
 - `specialists/contracts.json` postconditions check structural requirements (mandatory sections, intake traceability, citation density). `lib/contracts/validate.mjs#validateHandoff` blocks handoffs that fail validation; binary postconditions in `lib/specialists/postconditions.mjs` block rubber-stamp reviews, post-hoc threat models, symptom-only fixes, stale-doc PRs, and post-hoc accessibility. Enforcement is hard-default `block`.
 - `construct intake done <id> --output=<path>` stamps `intake_id`, `intake_confidence`, and `intake_rationale` into the artifact's frontmatter so every intake-derived artifact carries verifiable provenance.
 

package/rules/common/release-gates.md

@@ -42,7 +42,7 @@ For every non-trivial change:
 
 1. **A Beads issue exists.** `bd ready` to find or create one. `bd show <id>` to read context. `bd update <id> --claim` to claim before editing files.
 2. **`plan.md` reflects the work.** Even though `plan.md` is local-only and gitignored, it stays the human-readable working plan. Mark items `done` when they ship; add new rows for work that wasn't previously tracked.
-3. **Doc updates land in the same change as code.** If runtime shape, contracts, boundaries, or major dependencies changed, update `docs/concepts/architecture.md` in the same commit. If the docs surface or maintenance contract changed, update `docs/README.md`. If active work, decisions, or assumptions changed, update `.cx/context.md` and `.cx/context.json`. Always add a `CHANGELOG.md` entry.
+3. **Doc updates land in the same change as code.** If runtime shape, contracts, boundaries, or major dependencies changed, update `docs/guides/concepts/architecture.md` in the same commit. If the docs surface or maintenance contract changed, update `docs/README.md`. If active work, decisions, or assumptions changed, update `.cx/context.md` and `.cx/context.json`. Always add a `CHANGELOG.md` entry.
 4. **Beads close on green.** `bd close <id>` happens after CI is green and the work is verified: not before.
 
 ## Hard rules

package/rules/common/research.md

@@ -47,7 +47,7 @@ Start with the narrowest authoritative source that can answer the question:
 1. **Local project evidence first**
    - `.cx/research/`
    - `.cx/knowledge/`
-   - `docs/prd/`, `docs/meta-prd/`, `docs/adr/`, `docs/runbooks/`
+   - `docs/specs/prd/`, `docs/meta-prd/`, `docs/decisions/adr/`, `docs/operations/runbooks/`
    - ingested markdown artifacts under `.cx/knowledge/`
    - repo code, tests, configs, and existing decisions
 2. **Primary external sources second**