@geraldmaron/construct 1.0.5 → 1.0.7

package/lib/provider-capabilities.js

@@ -117,23 +117,36 @@ export function resolveProviderCapabilitiesSync(modelId) {
 }
 
 /**
- * Probe provider for live capabilities (async).
- * Results are cached for 24h.
+ * Probe provider for capabilities and cache the result for 24h.
+ *
+ * Static path (probe=false): resolves capabilities from the adapter's static
+ * declaration. Live path (probe=true): dispatches to the adapter's optional
+ * `probe(modelId)` export — adapters that don't implement it fall back to the
+ * static declaration. Construct itself stays provider-agnostic; per-vendor
+ * probing is the adapter's responsibility.
  *
  * @param {string} modelId
  * @param {object} opts - { probe: boolean }
  * @returns {Promise<object>}
  */
 export async function probeProviderCapabilities(modelId, { probe = false } = {}) {
-  const caps = await resolveProviderCapabilities(modelId);
+  const adapterKey = resolveAdapterKey(modelId);
+  const loader = ADAPTERS[adapterKey] || ADAPTERS.generic;
 
+  let caps;
   if (probe) {
-    // TODO: implement live probing (API call) in Phase A follow-up
-    // For now, just return the static capabilities
+    try {
+      const mod = await loader();
+      caps = typeof mod.probe === 'function'
+        ? await mod.probe(modelId)
+        : mod.capabilities(modelId);
+    } catch {
+      caps = await resolveProviderCapabilities(modelId);
+    }
+  } else {
+    caps = await resolveProviderCapabilities(modelId);
   }
 
-  // Cache by adapter key
-  const adapterKey = resolveAdapterKey(modelId);
   const cache = getCache();
   cache[adapterKey] = caps;
   writeCapabilityCache(cache);

package/lib/providers/auth-manager.mjs

@@ -1,15 +1,23 @@
-// lib/providers/auth-manager.mjs
-// OAuth refresh and token lifecycle management
+/**
+ * lib/providers/auth-manager.mjs — Token lifecycle and refresh dispatch.
+ *
+ * Provider-agnostic store and contract for credential rotation. The actual
+ * refresh flow (OAuth, JWT, vendor-specific) lives in a registered adapter;
+ * dispatch goes to the adapter's `refresh(state)` and the result is persisted
+ * back to the auth store. Adapters lacking a refresh implementation leave the
+ * operator on a reauthenticate-manually path — the safe agnostic default.
+ */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
 
-const AUTH_DIR = path.join(homedir(), '.construct', 'auth');
-
-try {
-  fs.mkdirSync(AUTH_DIR, { recursive: true, mode: 0o700 });
-} catch { /* ignore */ }
+function authDir() {
+  const home = process.env.HOME || homedir();
+  const dir = path.join(home, '.construct', 'auth');
+  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* ignore */ }
+  return dir;
+}
 
 const PROVIDER_CONFIGS = {
   github: {
@@ -28,9 +36,20 @@ const PROVIDER_CONFIGS = {
   },
 };
 
+const refreshAdapters = new Map();
+
+/**
+ * Register a refresh adapter for a provider. Contract:
+ *   adapter(state) -> Promise<{ success, token, refreshToken?, expiresAt? }>
+ * If no adapter is registered, refresh returns a manual-reauth instruction.
+ */
+export function registerRefreshAdapter(provider, adapter) {
+  if (typeof adapter === 'function') refreshAdapters.set(provider, adapter);
+}
+
 export function loadAuthState(provider) {
   try {
-    const file = path.join(AUTH_DIR, `${provider}.json`);
+    const file = path.join(authDir(), `${provider}.json`);
     if (fs.existsSync(file)) {
       return JSON.parse(fs.readFileSync(file, 'utf8'));
     }
@@ -40,7 +59,7 @@ export function loadAuthState(provider) {
 
 export function saveAuthState(provider, state) {
   try {
-    const file = path.join(AUTH_DIR, `${provider}.json`);
+    const file = path.join(authDir(), `${provider}.json`);
     fs.writeFileSync(file, JSON.stringify(state, null, 2), { mode: 0o600 });
     return true;
   } catch {
@@ -111,16 +130,38 @@ async function refreshToken(provider) {
   if (!config?.refreshable) {
     return { success: false, error: 'Provider does not support refresh' };
   }
-  
+
   const state = loadAuthState(provider);
   if (!state?.refreshToken) {
     return { success: false, error: 'No refresh token available' };
   }
-  
-  // Provider-specific refresh logic would go here
-  // For now, just indicate refresh is needed
-  return {
-    success: false,
-    error: 'Token refresh required - reauthenticate manually',
-  };
+
+  const adapter = refreshAdapters.get(provider);
+  if (!adapter) {
+    return {
+      success: false,
+      error: 'Token refresh required - reauthenticate manually',
+    };
+  }
+
+  try {
+    const result = await adapter(state);
+    if (result?.success && result.token) {
+      const next = {
+        ...state,
+        token: result.token,
+        refreshToken: result.refreshToken || state.refreshToken,
+        expiresAt: result.expiresAt || null,
+        rotatedAt: new Date().toISOString(),
+      };
+      saveAuthState(provider, next);
+      return { success: true, expiresAt: next.expiresAt };
+    }
+    return {
+      success: false,
+      error: result?.error || 'Refresh adapter returned no token',
+    };
+  } catch (err) {
+    return { success: false, error: `Refresh adapter threw: ${err.message}` };
+  }
 }

package/lib/reflect.mjs

@@ -8,10 +8,11 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import { join, resolve, basename } from 'node:path';
 import { execSync } from 'node:child_process';
-import { addObservation } from './observation-store.mjs';
+import { addObservation, listObservations } from './observation-store.mjs';
 import { loadConstructEnv } from './env-config.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS, inferKnowledgeTarget } from './knowledge/layout.mjs';
 import { extractSessionObservation } from './reflect/extractor.mjs';
+import { readContextState, contextSummaryLine } from './context-state.mjs';
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
 const USER_ENV_PATH = join(HOME, '.construct', 'config.env');
@@ -47,12 +48,19 @@ export async function runReflectCli(args) {
     target = `knowledge/${target}`;
   }
 
-  // If no summary provided, try to get it from stdin or prompt
+  let summarySource = 'cli';
   if (!summary) {
-    // For now, we'll require explicit summary - in future could read from chat context
-    console.error('Error: --summary=<text> is required to capture improvement feedback');
-    console.error('Example: construct reflect --target=internal --summary="Improve Slack channel intent parsing to handle edge cases"');
-    process.exit(1);
+    const derived = deriveSummaryFromContext(process.cwd());
+    if (derived) {
+      summary = derived;
+      summarySource = 'auto-derived';
+      console.error(`Note: --summary not provided; using auto-derived summary from .cx/context.md and recent observations.`);
+      console.error(`Captured summary: "${summary.slice(0, 180)}${summary.length > 180 ? '…' : ''}"`);
+    } else {
+      console.error('Error: --summary=<text> is required (no .cx/context.md or recent session summaries to derive from)');
+      console.error('Example: construct reflect --target=internal --summary="Improve Slack channel intent parsing to handle edge cases"');
+      process.exit(1);
+    }
   }
 
   // Resolve the knowledge directory for this target
@@ -110,15 +118,14 @@ export async function runReflectCli(args) {
   // Write the file
   writeFileSync(filePath, content);
 
-  // Record an observation about this feedback
-  const observationSummary = `[reflect] Improvement feedback captured: ${summary.slice(0, 100)}${summary.length > 100 ? '...' : ''}`;
+  const observationSummary = `[reflect] Improvement feedback captured (${summarySource}): ${summary.slice(0, 100)}${summary.length > 100 ? '...' : ''}`;
   addObservation(process.cwd(), {
     role: 'construct',
-    category: 'insight', // Feedback is typically an insight unless it's about a problem
+    category: 'insight',
     summary: observationSummary,
-    content: `Feedback captured via construct reflect:\n\n${summary}\n\nStored as: ${filePath}\nTarget: ${knowledgeSubdir}/`,
-    tags: ['reflect', 'improvement-feedback', `knowledge:${knowledgeSubdir}`],
-    confidence: 0.9,
+    content: `Feedback captured via construct reflect (${summarySource}):\n\n${summary}\n\nStored as: ${filePath}\nTarget: ${knowledgeSubdir}/`,
+    tags: ['reflect', 'improvement-feedback', `knowledge:${knowledgeSubdir}`, `source:${summarySource}`],
+    confidence: summarySource === 'auto-derived' ? 0.65 : 0.9,
     source: 'reflect-command',
   });
 
@@ -186,6 +193,36 @@ export async function runReflectAuto({ transcriptPath, cwd, sessionId, durationM
   return result?.id ?? null;
 }
 
+/**
+ * Derive a one-paragraph reflect summary from durable session state — the
+ * context.md digest first, then the most recent session-summary observation.
+ * Returns null when neither source yields useful content.
+ */
+export function deriveSummaryFromContext(cwd) {
+  const parts = [];
+
+  try {
+    const state = readContextState(cwd);
+    const line = contextSummaryLine(state);
+    if (line && line.trim().length > 20) parts.push(line.trim());
+  } catch { /* best effort */ }
+
+  try {
+    const recent = listObservations(cwd, { limit: 5 }) || [];
+    const sessionSummary = recent.find((o) => Array.isArray(o.tags) && o.tags.includes('session-summary'));
+    if (sessionSummary?.summary) {
+      const text = String(sessionSummary.summary).replace(/^\[[^\]]+\]\s*/, '').trim();
+      if (text.length > 20 && !parts.some((p) => p.includes(text.slice(0, 40)))) {
+        parts.push(text);
+      }
+    }
+  } catch { /* best effort */ }
+
+  if (parts.length === 0) return null;
+  const joined = parts.join(' — ');
+  return joined.length > 600 ? joined.slice(0, 580) + '…' : joined;
+}
+
 function safeProject(cwd) {
   try { return basename(cwd) || null; } catch { return null; }
 }

package/lib/server/index.mjs

@@ -8,6 +8,7 @@
  * Runs on port 4242 (overridable via PORT env var), bound to 127.0.0.1.
  */
 import { createServer } from 'http';
+import { registerBoundary } from '../boundary.mjs';
 import { readFileSync, writeFileSync, statSync, watch, existsSync, readdirSync, mkdirSync, renameSync, chmodSync, appendFileSync } from 'fs';
 import { spawnSync } from 'child_process';
 import { join, extname, relative, normalize, dirname } from 'path';
@@ -1115,44 +1116,36 @@ const server = createServer(async (req, res) => {
       const chunks = [];
       await new Promise((resolve, reject) => { req.on('data', c => chunks.push(c)); req.on('end', resolve); req.on('error', reject); });
       const body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
-      
-      const { parentInstance, parentUrl, childInstanceId } = body;
-      
+
+      const { parentInstance, parentUrl, childInstanceId, nonce, signature } = body;
+
       if (!parentInstance || !parentUrl) {
         res.writeHead(400, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'parentInstance and parentUrl are required' }));
         return;
       }
-      
-      // In a real implementation, this would:
-      // - Validate the parent is a legitimate Construct instance
-      // - Store the parent registration in a boundary configuration
-      // - Set up communication channels between parent and child
-      // - Configure isolation boundaries
-      
-      // For now, just acknowledge the registration
-      const configDir = join(HOME, '.construct');
-      if (!existsSync(configDir)) {
-        mkdirSync(configDir, { recursive: true });
-      }
-      
-      const boundaryConfig = {
+
+      const result = await registerBoundary({
         parentInstance,
         parentUrl,
-        childInstanceId: childInstanceId || env.CONSTRUCT_INSTANCE_ID || 'default',
-        registeredAt: new Date().toISOString(),
-        boundaryVersion: '1.0'
-      };
-      
-      const boundaryConfigPath = join(configDir, 'boundary-config.json');
-      writeFileSync(boundaryConfigPath, JSON.stringify(boundaryConfig, null, 2));
-      
+        childInstanceId: childInstanceId || process.env.CONSTRUCT_INSTANCE_ID || 'default',
+        nonce,
+        signature,
+        sharedSecret: process.env.CONSTRUCT_BOUNDARY_SECRET || null,
+      });
+
+      if (!result.ok) {
+        res.writeHead(result.status || 400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: result.error }));
+        return;
+      }
+
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ 
+      res.end(JSON.stringify({
         success: true,
         message: 'Boundary registration accepted',
-        boundaryConfig,
-        boundaryConfigPath
+        boundaryConfig: result.config,
+        boundaryConfigPath: result.path,
       }));
     } catch (err) {
       res.writeHead(500, { 'Content-Type': 'application/json' });
@@ -2243,3 +2236,4 @@ process.on('SIGINT', () => shutdown('SIGINT'));
 onEmbedNotification((event) => {
   notifyClients({ type: 'toast', ...event });
 });
+

package/lib/session-store.mjs

@@ -19,6 +19,7 @@ import path from "node:path";
 import { cosineSimilarity, rankByBm25 } from "./storage/embeddings.mjs";
 import { embedSync as embedText } from "./storage/embeddings-legacy.mjs";
 import { withFileLockSync } from "./storage/file-lock.mjs";
+import { ensureCxDir } from "./project-init-shared.mjs";
 
 const SESSIONS_DIR = ".cx/sessions";
 const INDEX_FILE = "index.json";
@@ -29,7 +30,8 @@ const MAX_DECISIONS = 20;
 const MAX_FILES = 50;
 const MAX_OPEN_QUESTIONS = 10;
 
-function ensureDir(dir) {
+function ensureDir(dir, rootDir = null) {
+  if (rootDir) ensureCxDir(rootDir);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
 
@@ -52,7 +54,7 @@ function readVectors(rootDir) {
 }
 
 function writeVectors(rootDir, records) {
-  ensureDir(sessionsDir(rootDir));
+  ensureDir(sessionsDir(rootDir), rootDir);
   const target = vectorsPath(rootDir);
   withFileLockSync(target, () => {
     fs.writeFileSync(target, JSON.stringify(records.slice(0, MAX_INDEX_ENTRIES), null, 2) + "\n");
@@ -86,7 +88,7 @@ function readIndex(rootDir) {
 }
 
 function writeIndex(rootDir, entries) {
-  ensureDir(sessionsDir(rootDir));
+  ensureDir(sessionsDir(rootDir), rootDir);
   const trimmed = entries.slice(0, MAX_INDEX_ENTRIES);
   const target = indexPath(rootDir);
   withFileLockSync(target, () => {
@@ -137,7 +139,7 @@ export function createSession(rootDir, {
     taskSnapshot: [],
   };
 
-  ensureDir(sessionsDir(rootDir));
+  ensureDir(sessionsDir(rootDir), rootDir);
   fs.writeFileSync(
     path.join(sessionsDir(rootDir), `${id}.json`),
     JSON.stringify(record, null, 2) + "\n"

package/lib/setup.mjs

@@ -420,7 +420,7 @@ function ensureOpenCodeConfig() {
 // repo but never executed by git. Idempotent: leaves a user-set value alone
 // rather than clobbering it.
 
-function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
+export function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
   const hooksDir = path.join(cwd, '.beads', 'hooks');
   if (!fs.existsSync(path.join(hooksDir, 'pre-commit'))) {
     return { status: 'skipped', reason: 'no .beads/hooks/pre-commit in this directory' };
@@ -435,10 +435,21 @@ function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
   if (currentValue === desired) {
     return { status: 'ok', message: 'core.hooksPath already wired to .beads/hooks' };
   }
-  if (currentValue && currentValue !== desired) {
+
+  // Treat the git default (`.git/hooks` or an absolute path to it) as
+  // equivalent to unset. A user who has accepted the default has not made an
+  // active choice that justifies "leave alone" semantics; without this branch
+  // an install that happens to land while `.git/hooks` is already in play
+  // leaves policy gates inactive permanently.
+  const isGitDefault =
+    !currentValue ||
+    currentValue === '.git/hooks' ||
+    currentValue === path.join(cwd, '.git', 'hooks') ||
+    currentValue.replace(/\/+$/, '').endsWith(`${path.sep}.git${path.sep}hooks`);
+  if (!isGitDefault) {
     return {
       status: 'warning',
-      message: `core.hooksPath is set to '${currentValue}'. Leaving alone — set to '.beads/hooks' to activate Construct policy gates.`,
+      message: `core.hooksPath is set to '${currentValue}'. Leaving alone. Set to '.beads/hooks' to activate Construct policy gates.`,
     };
   }
   const result = spawnSync('git', ['config', 'core.hooksPath', desired], { cwd, stdio: 'pipe', encoding: 'utf8' });

package/lib/telemetry/client.mjs

@@ -10,6 +10,7 @@ import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 import { createIngestClient } from './ingest.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 const DEFAULT_MAX_BATCH = 50;
 
@@ -55,7 +56,10 @@ function appendLocalTelemetry(type, body, { rootDir, env = process.env, onError
   const projectRoot = resolveProjectRoot({ rootDir, env });
   const dir = join(projectRoot, '.cx', 'traces');
   try {
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    if (!existsSync(dir)) {
+      ensureCxDir(projectRoot);
+      mkdirSync(dir, { recursive: true });
+    }
     appendFileSync(join(dir, `${traceShard()}.jsonl`), `${JSON.stringify({
       traceId: body?.traceId || body?.id || randomUUID(),
       spanId: body?.id || randomUUID(),

package/lib/version.mjs

@@ -0,0 +1,51 @@
+/**
+ * lib/version.mjs — Single source of truth for the installed Construct version.
+ *
+ * Reads package.json once per process and caches. Surfaces:
+ *   - bin/construct (`--version`, `construct version`)
+ *   - construct status (header)
+ *   - migration runner (compatibility check against artifact schema versions)
+ *   - doctor watchers (advisory drift against published npm tag)
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const PKG_PATH = join(ROOT, 'package.json');
+
+let _cached = null;
+
+export function getInstalledVersion() {
+  if (_cached) return _cached;
+  try {
+    const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8'));
+    _cached = { version: pkg.version || '0.0.0', name: pkg.name || 'construct', pkgPath: PKG_PATH };
+  } catch {
+    _cached = { version: '0.0.0', name: 'construct', pkgPath: PKG_PATH };
+  }
+  return _cached;
+}
+
+/**
+ * Parse a semver string into { major, minor, patch }. Returns null on failure.
+ */
+export function parseSemver(s) {
+  const match = String(s || '').match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+/**
+ * Compare two semver strings. Returns -1 / 0 / 1.
+ */
+export function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return 0;
+  if (pa.major !== pb.major) return pa.major < pb.major ? -1 : 1;
+  if (pa.minor !== pb.minor) return pa.minor < pb.minor ? -1 : 1;
+  if (pa.patch !== pb.patch) return pa.patch < pb.patch ? -1 : 1;
+  return 0;
+}

package/lib/worker/trace.mjs

@@ -31,6 +31,7 @@ import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 
 import { createTelemetryClient } from '../telemetry/client.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 const TRACE_SUBDIR = '.cx/traces';
 
@@ -150,7 +151,10 @@ export function emitTraceEvent({
   }
 
   const dir = traceDir(rootDir);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  if (!existsSync(dir)) {
+    ensureCxDir(rootDir);
+    mkdirSync(dir, { recursive: true });
+  }
 
   const event = {
     traceId: traceId || newTraceId(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
@@ -50,12 +50,15 @@
     "docs:dev": "npm --prefix apps/docs run dev",
     "docs:build": "npm --prefix apps/docs run build",
     "lint:comments": "node ./bin/construct lint:comments",
+    "lint:contracts": "node ./bin/construct lint:contracts",
+    "lint:agents": "node ./bin/construct lint:agents",
     "lint:prose": "node scripts/lint-prose.mjs",
     "lint:profiles": "node scripts/lint-profiles.mjs",
     "learning:status": "node scripts/learning-status.mjs",
     "lint:templates": "node scripts/lint-commits-pr.mjs",
     "eval:routing": "node scripts/eval/score-intent-classifier.mjs",
     "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",
     "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/personas/construct.md

@@ -5,7 +5,9 @@ Defines the single user-facing AI interface and its session-start behavior,
 routing rules, approval boundaries, and output contract. Loaded by sync-agents
 and emitted to every supported platform.
 -->
-You are Construct. the single AI interface for everything from a quick question to a full software lifecycle. The user talks only to you; internal routing and specialist dispatch are implementation detail.
+You are Construct. The user talks only to you; internal routing and specialist dispatch are implementation detail.
+
+**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
 

package/platforms/claude/CLAUDE.md

@@ -1,4 +1,4 @@
-# Construct — Claude Code Integration
+# Construct: Claude Code Integration
 
 This project uses Construct. Personas and specialists are defined in `agents/registry.json` and synced to Claude Code via `construct sync`.
 
@@ -6,11 +6,11 @@ This project uses Construct. Personas and specialists are defined in `agents/reg
 
 Construct is the only intended user-facing surface.
 
-- **Planning** — requirements, strategy, architecture
-- **Implementation** — builds features and fixes bugs
-- **Validation** — quality gates, security, accessibility
-- **Research** — docs, debugging, codebase exploration
-- **Operations** — releases, dev servers, health checks
+- **Planning**: requirements, strategy, architecture
+- **Implementation**: builds features and fixes bugs
+- **Validation**: quality gates, security, accessibility
+- **Research**: docs, debugging, codebase exploration
+- **Operations**: releases, dev servers, health checks
 
 ## Usage
 

package/rules/common/agents.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/agents.md — platform-agnostic agent orchestration guidance.
+rules/common/agents.md: platform-agnostic agent orchestration guidance.
 
 Defines when to route to specialist agents, parallel execution rules,
 and multi-perspective analysis patterns. Does not reference specific
@@ -9,7 +9,7 @@ platform agent types or config paths.
 
 ## Immediate Agent Usage
 
-No user prompt needed — match the task to the right specialist:
+No user prompt needed: match the task to the right specialist:
 1. Complex feature requests - planning specialist
 2. Code just written/modified - code review specialist
 3. Bug fix or new feature - TDD specialist

package/rules/common/beads-hygiene.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/beads-hygiene.md — Beads issue tracker hygiene contract.
+rules/common/beads-hygiene.md: Beads issue tracker hygiene contract.
 
 Beads is the system of record for durable work in this project. Status drifts
 when issues are not updated alongside the code, so every agent and persona
@@ -7,16 +7,16 @@ operating in Construct treats hygiene as part of the work, not as cleanup.
 Loaded by AGENTS.md, CLAUDE.md, the construct persona, and the engineer /
 operator / planner role overlays.
 -->
-# Beads Hygiene — Project Contract
+# Beads Hygiene: Project Contract
 
-Beads (`bd`) is the canonical durable tracker for Construct. Beads only earn their keep when their state matches the world. Stale "open" issues pollute `bd ready`, hide real work, and let agents propose work that already shipped. Every agent — human or AI, on any platform — is responsible for keeping the tracker honest.
+Beads (`bd`) is the canonical durable tracker for Construct. Beads only earn their keep when their state matches the world. Stale "open" issues pollute `bd ready`, hide real work, and let agents propose work that already shipped. Every agent (human or AI, on any platform) is responsible for keeping the tracker honest.
 
 ## When to update beads
 
 | Event | Required action |
 |---|---|
 | About to start non-trivial work | A Beads issue exists. `bd ready` to find or `bd create` if missing. `bd update <id> --claim` before edits. |
-| Work lands on `main` | `bd close <id> --reason="Landed in PR #N — verified: <file:line evidence>"`. Do not wait for someone else to notice. |
+| Work lands on `main` | `bd close <id> --reason="Landed in PR #N. Verified: <file:line evidence>"`. Do not wait for someone else to notice. |
 | Direction reverses mid-work | `bd supersede <old-id> --with=<new-id>`. Do not edit the old description in place. |
 | Issue scope expands | Update the description and acceptance criteria in the same change that broadens scope. |
 | A blocker is discovered | Add the dependency with `bd dep add <id> <depends-on>` so the readiness queue reflects reality. |
@@ -27,10 +27,10 @@ Beads (`bd`) is the canonical durable tracker for Construct. Beads only earn the
 
 Run before planning, before claiming work, before proposing changes:
 
-1. `bd ready` — surface unblocked work.
-2. `bd list --status=in_progress` — verify nothing has been left mid-flight by an earlier session.
-3. `bd stale` — surface anything untouched past the staleness window.
-4. Cross-check the open list against `git log --oneline -20 origin/main` — close anything whose work actually landed.
+1. `bd ready`: surface unblocked work.
+2. `bd list --status=in_progress`: verify nothing has been left mid-flight by an earlier session.
+3. `bd stale`: surface anything untouched past the staleness window.
+4. Cross-check the open list against `git log --oneline -20 origin/main`: close anything whose work actually landed.
 
 If any of these surface drift, fix it before starting new work. Drift you observe and ignore becomes drift the next agent inherits.
 
@@ -40,14 +40,14 @@ After the code changes land in main:
 
 1. The bead the work was claimed against is closed with evidence in the reason.
 2. Any beads superseded by the change are marked superseded, not left open.
-3. New beads exist for follow-up work that was discovered but not done — file them in the same session, not "later".
+3. New beads exist for follow-up work that was discovered but not done: file them in the same session, not "later".
 4. `bd doctor` and `bd preflight` should run before push and report clean.
 
 ## What goes in a bead
 
 | Field | Standard |
 |---|---|
-| Title | Imperative, scoped, parseable. "PR 3 — `construct intake` CLI" beats "intake CLI". |
+| Title | Imperative, scoped, parseable. "PR 3: `construct intake` CLI" beats "intake CLI". |
 | Description | Why the bead exists + what success looks like. State the new shape directly. Do not preserve a "current behavior must keep working" goal unless the user explicitly asked for migration. |
 | Acceptance criteria | Numbered, binary checks. A reviewer can answer pass/fail without re-reading the description. |
 | Dependencies | Wire `bd dep add` whenever order matters. Implicit ordering rots into parallel work that breaks each other. |
@@ -72,4 +72,4 @@ There is no authorized bypass. Beads hygiene is a release gate. If the tooling i
 
 ## Automation
 
-Project-level automation is tracked in the beads queue — auto-close on merge, pre-push `bd preflight` gate, weekly drift report, memory-contradiction detection. Until that ships, hygiene is a per-session discipline.
+Project-level automation is tracked in the beads queue: auto-close on merge, pre-push `bd preflight` gate, weekly drift report, memory-contradiction detection. Until that ships, hygiene is a per-session discipline.

package/rules/common/code-review.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/code-review.md — when and how to conduct code reviews.
+rules/common/code-review.md: when and how to conduct code reviews.
 
 Defines mandatory review triggers, severity levels, approval criteria,
 and references coding-style.md and security.md for checklists.

package/rules/common/coding-style.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/coding-style.md — language-agnostic coding standards.
+rules/common/coding-style.md: language-agnostic coding standards.
 
 Covers immutability, core principles (KISS/DRY/YAGNI), file organization,
 error handling, input validation, naming conventions, and quality checklist.