@geraldmaron/construct 1.0.5 → 1.0.6

package/lib/mcp/tools/profile.mjs

@@ -0,0 +1,270 @@
+/**
+ * lib/mcp/tools/profile.mjs — MCP wrappers for the org-profile + learning surfaces.
+ *
+ * Bridges PR #67 capabilities (profiles, outcomes, sandboxes, knowledge_add,
+ * learning status) so subagents talking through the construct-mcp server can
+ * read the same state the CLI exposes. Operator-only surfaces (optimize_apply,
+ * optimize_rollback) remain CLI-only and are not registered here.
+ *
+ * Pattern: each export is a thin schema-validated wrapper around the existing
+ * lib/* function the CLI already uses. Errors return `{ error: string }` so
+ * the MCP dispatcher hands a structured failure back instead of crashing.
+ * Destructive operations (profile_archive) require `confirm: true`, matching
+ * the storage_reset / delete_ingested_artifacts pattern in tools/storage.mjs.
+ */
+import { resolve } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  loadProfile,
+  listProfiles,
+  loadCustomProfile,
+  resolveActiveProfile,
+} from '../../profiles/loader.mjs';
+import {
+  createDraftProfile,
+  listDrafts,
+  archiveProfile,
+  profileHealth,
+} from '../../profiles/lifecycle.mjs';
+import { recordOutcome } from '../../outcomes/record.mjs';
+import { aggregateOutcomes, readSummary } from '../../outcomes/aggregate.mjs';
+import { addResearchFinding } from '../../knowledge/research-store.mjs';
+import { askGlobal } from '../../knowledge/graph.mjs';
+import { listSandboxes } from '../../sandbox.mjs';
+
+function cwdOf(args) {
+  return args && args.cwd ? resolve(String(args.cwd)) : process.cwd();
+}
+
+// Read-only: active profile.
+
+export function profileShow(args = {}) {
+  const cwd = cwdOf(args);
+  const profile = resolveActiveProfile(cwd, args.id ? String(args.id) : null);
+  return {
+    id: profile.id,
+    displayName: profile.displayName ?? profile.id,
+    tagline: profile.tagline ?? null,
+    custom: profile.custom === true,
+    roles: Array.isArray(profile.roles) ? profile.roles : [],
+    departments: Array.isArray(profile.departments)
+      ? profile.departments.map((d) => ({ id: d.id, displayName: d.displayName, roleCount: Array.isArray(d.roles) ? d.roles.length : 0 }))
+      : [],
+    intake: {
+      types: profile.intake?.types ?? [],
+      stages: profile.intake?.stages ?? [],
+    },
+    docTemplates: profile.docTemplates ?? [],
+    hooks: profile.hooks ?? null,
+    rebrand: profile.rebrand ?? null,
+  };
+}
+
+// Read-only: catalog summary.
+
+export function profileList() {
+  return {
+    profiles: listProfiles().map((id) => {
+      const p = loadProfile(id);
+      return p
+        ? {
+            id: p.id,
+            displayName: p.displayName ?? p.id,
+            tagline: p.tagline ?? null,
+            roleCount: Array.isArray(p.roles) ? p.roles.length : 0,
+            departmentCount: Array.isArray(p.departments) ? p.departments.length : 0,
+          }
+        : { id, error: 'failed to parse' };
+    }),
+  };
+}
+
+// Read-only: drafts + custom profile under .cx/.
+
+export function profileDrafts(args = {}) {
+  const cwd = cwdOf(args);
+  const drafts = listDrafts(cwd).map((d) => ({
+    id: d.id,
+    dir: d.dir,
+    hasProfile: d.hasProfile,
+    hasBrief: d.hasBrief,
+  }));
+  const custom = loadCustomProfile(cwd);
+  return {
+    drafts,
+    custom: custom ? { id: custom.id, displayName: custom.displayName ?? custom.id } : null,
+  };
+}
+
+// Read-only: per-profile health rollup.
+
+export function profileHealthTool(args = {}) {
+  const cwd = cwdOf(args);
+  const id = args.id ? String(args.id) : resolveActiveProfile(cwd).id;
+  const windowDays = Number.isFinite(args.window_days) ? Number(args.window_days) : 30;
+  return { id, windowDays, ...profileHealth(cwd, id, { windowDays }) };
+}
+
+// Read-only: outcomes rollup. Optional aggregate=true rebuilds _summary.json.
+
+export function outcomesSummary(args = {}) {
+  const cwd = cwdOf(args);
+  if (args.aggregate === true) {
+    try { aggregateOutcomes(cwd); } catch (err) { return { error: `aggregate failed: ${err.message}` }; }
+  }
+  const summary = readSummary(cwd);
+  if (!summary) return { roles: {}, note: 'no outcomes recorded yet' };
+  return summary;
+}
+
+// Mutating, gated: append an outcome line.
+
+export function outcomesRecord(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'outcomes_record requires confirm=true to write durable state' };
+  }
+  const cwd = cwdOf(args);
+  if (!args.role || typeof args.success !== 'boolean') {
+    return { error: 'outcomes_record requires role:string and success:boolean' };
+  }
+  const profile = args.profile ? String(args.profile) : resolveActiveProfile(cwd)?.id;
+  const file = recordOutcome(cwd, {
+    role: String(args.role),
+    intakeId: args.intake_id ? String(args.intake_id) : null,
+    profile,
+    success: !!args.success,
+    escalated: !!args.escalated,
+    durationMs: Number.isFinite(args.duration_ms) ? Number(args.duration_ms) : null,
+    notes: args.notes ? String(args.notes) : null,
+    source: args.source ? String(args.source) : 'mcp',
+  });
+  if (!file) return { error: 'outcomes_record: write failed' };
+  return { ok: true, file };
+}
+
+// Mutating, gated: persist a research finding.
+
+export async function knowledgeAdd(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'knowledge_add requires confirm=true to write durable state' };
+  }
+  const cwd = cwdOf(args);
+  try {
+    const res = await addResearchFinding({
+      cwd,
+      slug: String(args.slug || ''),
+      topic: String(args.topic || ''),
+      body: String(args.body || ''),
+      confidence: args.confidence ? String(args.confidence) : 'inferred',
+      sources: Array.isArray(args.sources) ? args.sources : [],
+      ttlDays: Number.isFinite(args.ttl_days) ? Number(args.ttl_days) : undefined,
+    });
+    return { ok: true, path: res.path, bytes: res.bytes };
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+}
+
+// Mutating, gated: scaffold a draft profile.
+
+export function profileCreate(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'profile_create requires confirm=true to scaffold files' };
+  }
+  const cwd = cwdOf(args);
+  if (!args.id) return { error: 'profile_create requires id:string' };
+  try {
+    const res = createDraftProfile({
+      cwd,
+      id: String(args.id),
+      displayName: args.display_name ? String(args.display_name) : undefined,
+      seedRoles: Array.isArray(args.seed_roles) ? args.seed_roles.map(String) : [],
+      seedDepartments: Array.isArray(args.seed_departments) ? args.seed_departments : [],
+    });
+    return {
+      ok: true,
+      dir: res.dir,
+      briefPath: res.briefPath,
+      draftPath: res.draftPath,
+      personaPaths: res.personaPaths,
+      departmentPaths: res.departmentPaths,
+    };
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+}
+
+// Mutating, gated, destructive: archive a curated profile.
+
+export function profileArchive(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'profile_archive requires confirm=true (destructive: moves files into archive/profiles/)' };
+  }
+  if (!args.id || !args.reason || String(args.reason).trim().length < 8) {
+    return { error: 'profile_archive requires id:string and reason:string (>=8 chars)' };
+  }
+  try {
+    return { ok: true, ...archiveProfile({ id: String(args.id), reason: String(args.reason) }) };
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+}
+
+// Read-only: sandbox roster.
+
+export function sandboxList() {
+  return { sandboxes: listSandboxes() };
+}
+
+// Read-only: GraphRAG global query over the entity graph.
+
+export function knowledgeGraphAsk(args = {}) {
+  const cwd = cwdOf(args);
+  if (!args.query || typeof args.query !== 'string') {
+    return { error: 'knowledge_graph_ask requires query:string' };
+  }
+  const topK = Number.isFinite(args.top_k) ? Number(args.top_k) : 5;
+  const minSize = Number.isFinite(args.min_size) ? Number(args.min_size) : undefined;
+  return askGlobal({ query: String(args.query), rootDir: cwd, topK, ...(minSize !== undefined ? { minSize } : {}) });
+}
+
+// Read-only: learning dashboard mirror.
+
+export function learningStatus(args = {}) {
+  const cwd = cwdOf(args);
+
+  let observations = { total: 0, last24h: 0 };
+  try {
+    const idxPath = join(cwd, '.cx', 'observations', 'index.json');
+    if (existsSync(idxPath)) {
+      const idx = JSON.parse(readFileSync(idxPath, 'utf8'));
+      if (Array.isArray(idx)) {
+        const since = Date.now() - 24 * 60 * 60 * 1000;
+        observations = {
+          total: idx.length,
+          last24h: idx.filter((e) => Date.parse(e?.createdAt) >= since).length,
+        };
+      }
+    }
+  } catch { /* best effort */ }
+
+  let researchCount = 0;
+  try {
+    const dir = join(cwd, '.cx', 'knowledge', 'external', 'research');
+    if (existsSync(dir)) {
+      researchCount = readdirSync(dir).filter((f) => f.endsWith('.md')).length;
+    }
+  } catch { /* best effort */ }
+
+  const profile = resolveActiveProfile(cwd);
+  const outcomes = readSummary(cwd) || { roles: {} };
+
+  return {
+    profile: { id: profile.id, displayName: profile.displayName ?? profile.id, custom: profile.custom === true },
+    observations,
+    research: { count: researchCount },
+    outcomes,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {

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.

package/rules/common/comments.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/comments.md — Construct comment convention for JS/TS/MJS source files.
+rules/common/comments.md: Construct comment convention for JS/TS/MJS source files.
 
 Defines the two allowed comment forms (file header, section context block) and
 what is never allowed (inline narration, trailing comments, mid-function notes).
@@ -37,12 +37,12 @@ The blank line between the comment and the code is required. It signals "this co
 
 ## What is never allowed
 
-- **Inline trailing comments** — `const x = 1; // increment` — delete them
-- **Mid-function narration** — a comment in the middle of a function body that describes what the next line does — delete it; rename the variable or extract a function instead
-- **Between-group labels** — `// Language patterns`, `// Dashboard`, `// Step 1:` — delete them
-- **Narrative voice** — `// We weight BM25`, `// Now test the keys`, `// This correctly scores` — delete them
-- **Point-in-time notes** — `// X removed`, `// previously`, `// no longer` — belongs in git log
-- **Noise sentinels** — `// ok`, `// best effort`, `// skip` — delete them; use `/* non-critical */` inline only when the catch clause would otherwise look like a bug
+- **Inline trailing comments** (`const x = 1; // increment`) delete them
+- **Mid-function narration** (a comment in the middle of a function body that describes what the next line does) delete it; rename the variable or extract a function instead
+- **Between-group labels** (`// Language patterns`, `// Dashboard`, `// Step 1:`) delete them
+- **Narrative voice** (`// We weight BM25`, `// Now test the keys`, `// This correctly scores`) delete them
+- **Point-in-time notes** (`// X removed`, `// previously`, `// no longer`) belongs in git log
+- **Noise sentinels** (`// ok`, `// best effort`, `// skip`) delete them; use `/* non-critical */` inline only when the catch clause would otherwise look like a bug
 
 ## SLA annotations (hooks only)
 
@@ -54,5 +54,5 @@ The blank line between the comment and the code is required. It signals "this co
 
 ## Rule of thumb
 
-Delete the comment. If the section becomes harder to understand, the comment earns its place — as a block before it, with a blank line after. If it reads just as clearly without, it stays deleted.
+Delete the comment. If the section becomes harder to understand, the comment earns its place: as a block before it, with a blank line after. If it reads just as clearly without, it stays deleted.
 

package/rules/common/commit-approval.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/commit-approval.md — conversational approval rule for mutating git operations.
+rules/common/commit-approval.md: conversational approval rule for mutating git operations.
 
 Behavioral rule, not a hook. The agent asks and waits for a yes; the user
 replies in chat. Infrastructure stays out of the way.
@@ -19,7 +19,7 @@ Before running any of these Bash tool calls:
 The agent must:
 
 1. **State the working branch** so the user sees the scope.
-2. **Show the proposed action verbatim** — for a commit, the full proposed message (subject and body) formatted exactly as it will appear in `git log`. For a push, the target refspec. For a merge, the PR number and merge mode (`--squash`, `--rebase`, etc.).
+2. **Show the proposed action verbatim**: for a commit, the full proposed message (subject and body) formatted exactly as it will appear in `git log`. For a push, the target refspec. For a merge, the PR number and merge mode (`--squash`, `--rebase`, etc.).
 3. **Ask for confirmation** and wait for a yes before executing.
 
 A yes from the user in chat is the approval. No marker file, no CLI command, no special syntax.
@@ -41,13 +41,13 @@ Then stop and wait.
 
 ## Exceptions
 
-- **The user explicitly tells the agent to run a defined sequence** ("commit, push, and merge when ready"). That single yes covers the named batch — but only the actions named, in the order named. A new commit triggered later (e.g. by a CI fix or follow-up edit) is its own approval gate.
+- **The user explicitly tells the agent to run a defined sequence** ("commit, push, and merge when ready"). That single yes covers the named batch: but only the actions named, in the order named. A new commit triggered later (e.g. by a CI fix or follow-up edit) is its own approval gate.
 - **Read-only git operations** (`git status`, `git log`, `git diff`, `git fetch`, `git branch`, `git show`) don't need approval.
 
 A "yes" from earlier in the session does NOT carry forward to subsequent commits. Each new commit message must be shown and approved.
 
 ## Why this is a rule, not a hook
 
-A hook that blocked every commit turned out to be over-restrictive — it required a separate command invocation to write a marker file each time, which added friction without much safety beyond the agent just following the rule. The agent is the one producing commit messages; asking in chat is the right interface.
+A hook that blocked every commit turned out to be over-restrictive: it required a separate command invocation to write a marker file each time, which added friction without much safety beyond the agent just following the rule. The agent is the one producing commit messages; asking in chat is the right interface.
 
 If the agent ever commits without asking, that's a correctness bug. Surface it in the session and raise a follow-up to catch the regression.

package/rules/common/cx-agent-routing.md

@@ -1,11 +1,11 @@
 <!--
-rules/common/cx-agent-routing.md — auto-trigger routing rules for cx-* specialist agents.
+rules/common/cx-agent-routing.md: auto-trigger routing rules for cx-* specialist agents.
 
 Defines when to route directly to a cx-* specialist vs through Construct orchestration.
 Covers intent-based routing table, complexity gate, and routing rules.
 Loaded by rule-loading systems that look for cx-agent-routing in the rules hierarchy.
 -->
-# cx-* Agent Routing — Auto-trigger Rules
+# cx-* Agent Routing: Auto-trigger Rules
 
 When a request matches the trigger patterns below, automatically route to the corresponding cx-* specialist or persona before responding.
 

package/rules/common/cx-skill-routing.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/cx-skill-routing.md — Redirect to canonical skill routing table.
+rules/common/cx-skill-routing.md: Redirect to canonical skill routing table.
 -->
 # cx-* Skill Routing
 
@@ -7,5 +7,5 @@ rules/common/cx-skill-routing.md — Redirect to canonical skill routing table.
 >
 > All skill routing keywords, domain tables, and routing rules live there.
 > This file exists only as a named entry point for rule-loading systems that
-> look for `cx-skill-routing.md`. Do not add routing entries here — update
+> look for `cx-skill-routing.md`. Do not add routing entries here: update
 > `skills/routing.md` instead.

package/rules/common/development-workflow.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/development-workflow.md — feature implementation pipeline.
+rules/common/development-workflow.md: feature implementation pipeline.
 
 Defines the research-plan-TDD-review-commit workflow that runs before
 git operations. References testing.md, code-review.md, git-workflow.md.

package/rules/common/doc-ownership.md

@@ -1,9 +1,9 @@
 <!--
-rules/common/doc-ownership.md — which specialist owns which document type.
+rules/common/doc-ownership.md: which specialist owns which document type.
 
 Prevents the orchestrator (or any general persona) from authoring specialist
 documents directly. Routing authorship to the owning role is how research,
-framing, and domain scrutiny actually fire — writing a PRD without the
+framing, and domain scrutiny actually fire: writing a PRD without the
 product manager bypasses those checks entirely.
 -->
 # Document Ownership

package/rules/common/efficiency.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/efficiency.md — session context and tool-use efficiency standards.
+rules/common/efficiency.md: session context and tool-use efficiency standards.
 
 Applies to all agents operating in a Construct session. Violations compound context
 cost and reduce throughput. These rules are enforced by read-tracker.mjs and surfaced
@@ -19,7 +19,7 @@ Signals that a re-read is warranted:
 - An external process (Bash, a subagent) may have modified it.
 - The last read was in a prior session (context was compacted).
 
-Do not re-read to verify — trust the in-context state. If staleness is a concern,
+Do not re-read to verify: trust the in-context state. If staleness is a concern,
 check the file hash via `read-tracker.mjs` state rather than re-reading the full file.
 
 **Threshold:** more than 3 reads of the same file within a session without an intervening
@@ -54,4 +54,4 @@ re-running the command.
 Each Task dispatch creates a subagent context. Dispatch a specialist when the task
 benefits from a structurally different view (architecture suspicion, security scan,
 coverage gap analysis). Do not dispatch for tasks that fit within a single focused
-pass — the round-trip cost exceeds the benefit.
+pass: the round-trip cost exceeds the benefit.

package/rules/common/framing.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/framing.md — how to frame a problem before acting on it.
+rules/common/framing.md: how to frame a problem before acting on it.
 
 Establishes the hard separation between execution artifacts (tickets, chat
 transcripts, existing docs) and sources of truth (the underlying problem).

package/rules/common/git-workflow.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/git-workflow.md — commit message format and PR workflow.
+rules/common/git-workflow.md: commit message format and PR workflow.
 
 Defines conventional commit types and pull request creation steps.
 -->

package/rules/common/patterns.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/patterns.md — reusable design patterns and skeleton project strategy.
+rules/common/patterns.md: reusable design patterns and skeleton project strategy.
 
 Covers skeleton project evaluation, repository pattern, and API response format.
 -->

package/rules/common/performance.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/performance.md — model-agnostic performance and context management rules.
+rules/common/performance.md: model-agnostic performance and context management rules.
 
 Defines model selection tiers, context window management heuristics,
 and build troubleshooting steps. No platform-specific tool names or config paths.

package/rules/common/release-gates.md

@@ -1,12 +1,12 @@
 <!--
-rules/common/release-gates.md — Hard release gates for Construct work.
+rules/common/release-gates.md: Hard release gates for Construct work.
 
 Defines the blocking contracts every agent and persona must satisfy locally
 before any commit, push, or "done" claim. Loaded by the construct persona,
 AGENTS.md, and the engineer/reviewer/operator role overlays. Enforcement is at
-the prompt level — CI is a backstop, not the primary gate.
+the prompt level: CI is a backstop, not the primary gate.
 -->
-# Release Gates — Hard Contracts
+# Release Gates: Hard Contracts
 
 These are blocking gates. Every agent, persona, and harness session working in or shipping Construct must satisfy them locally **before** any commit, push, or "done" claim. CI is a backstop, not the primary check.
 
@@ -20,7 +20,7 @@ Run these before declaring work done. Pasting the output into the PR body or `bd
 |---|---|---|
 | Tests | `npm test` | 0 failed, 0 unexpected skips |
 | Comment policy | `node bin/construct lint:comments` | 0 errors AND 0 warnings |
-| Doc verification | `node bin/construct docs:verify` | "All documentation checks passed" — no warnings either |
+| Doc verification | `node bin/construct docs:verify` | "All documentation checks passed": no warnings either |
 | AUTO doc drift | `node bin/construct docs:update --check` | "Docs are up to date" |
 | Template policy | `npm run lint:templates` | "Template policy: clean." |
 
@@ -34,9 +34,9 @@ npm run release:check
 
 The repo enforces `.gitmessage` and `.github/pull_request_template.md`. Both are validated by `scripts/lint-commits-pr.mjs` (the `lint-templates` CI job) and fail the build on any deviation.
 
-Commit subjects must match `type(scope): subject` — type from {feat, fix, refactor, perf, docs, test, chore, ci, build, style}, imperative mood, ≤72 chars, no trailing period, lowercase after the colon. Run `git config commit.template .gitmessage` once per clone to load the template into your editor.
+Commit subjects must match `type(scope): subject`: type from {feat, fix, refactor, perf, docs, test, chore, ci, build, style}, imperative mood, ≤72 chars, no trailing period, lowercase after the colon. Run `git config commit.template .gitmessage` once per clone to load the template into your editor.
 
-PR descriptions must keep all six headings — Summary, Beads issue, Doc updates included, Local gates, Test plan, Risks / rollback — with at least one checked box in both the "Doc updates" and "Local gates" sections. Empty templates fail.
+PR descriptions must keep all six headings (Summary, Beads issue, Doc updates included, Local gates, Test plan, Risks / rollback) with at least one checked box in both the "Doc updates" and "Local gates" sections. Empty templates fail.
 
 Forbidden in commit messages: `Co-Authored-By: Claude*` trailers (unless the user explicitly asks), `--no-verify`, `--no-gpg-sign`. Forbidden in PR bodies: deleting the required headings, leaving every gate box unchecked.
 
@@ -47,7 +47,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.
-4. **Beads close on green.** `bd close <id>` happens after CI is green and the work is verified — not before.
+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

@@ -1,5 +1,5 @@
 <!--
-rules/common/research.md — canonical research and evidence policy for Construct.
+rules/common/research.md: canonical research and evidence policy for Construct.
 
 Defines how research starts, which sources to prefer, how claims are verified,
 and what must be recorded so findings are reproducible. Applies to research,
@@ -14,9 +14,9 @@ Construct treats research as a reproducible evidence-gathering process, not free
 
 Research always starts from the most recent available evidence.
 
-- Default to sources from the current year before earlier years — always search most-recent-first.
+- Default to sources from the current year before earlier years: always search most-recent-first.
 - For fast-moving topics (AI tools, LLM behavior, cloud APIs, security advisories, market data), treat anything older than 12 months as presumptively stale unless a newer source confirms it is still accurate.
-- When using a search engine or index, always filter or sort by date — do not rely on relevance ranking alone.
+- When using a search engine or index, always filter or sort by date: do not rely on relevance ranking alone.
 - State the publication or access date for every external source. If a source has no date, treat its confidence as `low` until recency is established another way.
 
 ## 2. Domain-specific starting points
@@ -67,7 +67,7 @@ Record:
 Every URL cited in a committed document must be verified before the document is published.
 
 - Fetch the URL. Confirm it resolves and the content matches the cited claim.
-- Do not cite aggregate or index pages (e.g., arxiv.org search results, Google Scholar listings) for quantitative claims — cite the specific paper or article URL.
+- Do not cite aggregate or index pages (e.g., arxiv.org search results, Google Scholar listings) for quantitative claims: cite the specific paper or article URL.
 - If a URL returns a 404, paywall, or redirect loop, find the canonical source or replace the citation.
 - Unverified URLs must be marked `[unverified]` until confirmed.