@geraldmaron/construct 1.0.4 → 1.0.6

package/commands/work/parallel-review.md

@@ -1,21 +1,21 @@
 <!--
-commands/work/parallel-review.md — Adversarial parallel review — 5 reviewers must agree before output ships
+commands/work/parallel-review.md (Adversarial parallel review) 5 reviewers must agree before output ships
 
-Adversarial parallel review — 5 reviewers must agree before output ships
+Adversarial parallel review: 5 reviewers must agree before output ships
 -->
 ---
-description: Adversarial parallel review — 5 reviewers must agree before output ships
+description: Adversarial parallel review: 5 reviewers must agree before output ships
 ---
 
 You are Construct running a parallel adversarial review of: $ARGUMENTS
 
 Dispatch the following 5 review roles concurrently:
 
-1. **cx-reviewer** — Correctness and logic: does it do what it claims? Are there off-by-ones, edge cases, or control flow bugs?
-2. **cx-security** — Vulnerabilities and data exposure: injection, auth bypass, secret leakage, SSRF, unvalidated input
-3. **cx-qa** — Test coverage and edge cases: what's untested? What inputs would break this?
-4. **cx-devil-advocate** — Assumption stress-test: what are we assuming that could be wrong? What failure modes are unaddressed?
-5. **cx-accessibility** (UI changes) or **cx-trace-reviewer** (non-UI) — Inclusive UX or performance bottlenecks
+1. **cx-reviewer**: Correctness and logic: does it do what it claims? Are there off-by-ones, edge cases, or control flow bugs?
+2. **cx-security**: Vulnerabilities and data exposure: injection, auth bypass, secret leakage, SSRF, unvalidated input
+3. **cx-qa**: Test coverage and edge cases: what's untested? What inputs would break this?
+4. **cx-devil-advocate**: Assumption stress-test: what are we assuming that could be wrong? What failure modes are unaddressed?
+5. **cx-accessibility** (UI changes) or **cx-trace-reviewer** (non-UI): Inclusive UX or performance bottlenecks
 
 ## Merge Gate
 

package/db/schema/006_graph.sql

@@ -0,0 +1,24 @@
+-- 006_graph.sql. GraphRAG community columns for entities.
+--
+-- Phase C9 foundations. Adds community_id (label propagation output) and a
+-- community summary table so the Pg-backed deployment can query communities
+-- without a JSONL scan. Solo-mode JSONL remains the source of truth; this
+-- table is the projection.
+
+ALTER TABLE construct_entities
+  ADD COLUMN IF NOT EXISTS community_id text,
+  ADD COLUMN IF NOT EXISTS community_size int;
+
+CREATE INDEX IF NOT EXISTS idx_entities_community ON construct_entities(project, community_id);
+
+CREATE TABLE IF NOT EXISTS construct_entity_communities (
+  community_id text NOT NULL,
+  project text NOT NULL,
+  size int NOT NULL DEFAULT 0,
+  top_members jsonb DEFAULT '[]'::jsonb,
+  summary text,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (project, community_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_communities_size ON construct_entity_communities(project, size DESC);

package/examples/provider-plugin/README.md

@@ -1,4 +1,4 @@
-# Hello World — Construct provider plugin example
+# Hello World: Construct provider plugin example
 
 A minimal reference implementation of the [Construct provider contract](../../docs/providers/authoring.md). Returns canned data; no external credentials required.
 
@@ -18,16 +18,16 @@ construct provider test hello-world --query "greet"
 ## What this shows
 
 - The factory function signature (`create({ env })`)
-- `meta` — id, displayName, capabilities
-- `configSchema` — JSON Schema for provider settings
-- `health()` — always-healthy health check
-- `read()` — look up a single item by id
-- `search()` — full-text filter over canned items
+- `meta`: id, displayName, capabilities
+- `configSchema`: JSON Schema for provider settings
+- `health()`: always-healthy health check
+- `read()`: look up a single item by id
+- `search()`: full-text filter over canned items
 
 ## Adapting for real providers
 
 1. Replace the `ITEMS` constant with real API calls.
-2. Add auth logic in `create()` — read tokens from `env` or `config`.
+2. Add auth logic in `create()`: read tokens from `env` or `config`.
 3. Add `watch()` and/or `webhook()` if your source supports push.
 4. Publish as an npm package and register via `construct provider plugins add <package>`.
 

package/examples/seed-observations/README.md

@@ -1,5 +1,5 @@
 <!--
-examples/seed-observations/README.md — seed corpus for Construct's in-tree memory layer.
+examples/seed-observations/README.md: seed corpus for Construct's in-tree memory layer.
 
 Run `construct bootstrap` to import these files into the local observation and entity stores.
 The seed corpus gives the hybrid BM25 + cosine retrieval a meaningful starting signal
@@ -25,14 +25,14 @@ This corpus seeds the Construct memory layer with high-value starting knowledge.
 construct bootstrap
 ```
 
-Imports all three files into the local observation store. Safe to re-run — duplicate
+Imports all three files into the local observation store. Safe to re-run: duplicate
 observations are deduplicated by content hash.
 
 ## Payoff Timeline
 
-- **0 sessions** — retrieval is cold; seed corpus provides baseline recall
-- **5 sessions** — personal patterns start surfacing; seed corpus still dominant
-- **20 sessions** — personal patterns dominate; seed corpus recedes to backstop
-- **50+ sessions** — retrieval is fully personalized; seed corpus rarely surfaces
+- **0 sessions**: retrieval is cold; seed corpus provides baseline recall
+- **5 sessions**: personal patterns start surfacing; seed corpus still dominant
+- **20 sessions**: personal patterns dominate; seed corpus recedes to backstop
+- **50+ sessions**: retrieval is fully personalized; seed corpus rarely surfaces
 
 Run `construct memory stats` to see whether memory is paying off.

package/examples/seed-observations/anti-patterns.md

@@ -1,5 +1,5 @@
 <!--
-examples/seed-observations/anti-patterns.md — recurring mistakes for Construct memory seed corpus.
+examples/seed-observations/anti-patterns.md: recurring mistakes for Construct memory seed corpus.
 
 Each entry becomes one observation in the store with category "anti-pattern". Imported via
 `construct bootstrap`.
@@ -9,36 +9,36 @@ Each entry becomes one observation in the store with category "anti-pattern". Im
 
 ## Context Waste
 
-**Reading the whole file to find one function** — Use Grep to locate the line number, then Read with offset/limit to read only that section. Reading a 500-line file to find a 10-line function burns ~5k tokens.
+**Reading the whole file to find one function**: Use Grep to locate the line number, then Read with offset/limit to read only that section. Reading a 500-line file to find a 10-line function burns ~5k tokens.
 
-**Re-reading already-loaded files** — If the file content is already in context, reading it again is pure waste. Check context before issuing another Read.
+**Re-reading already-loaded files**: If the file content is already in context, reading it again is pure waste. Check context before issuing another Read.
 
-**Sequential tool calls that could be parallel** — Issuing Glob, then Read, then Grep one at a time when they're independent triples the latency. Batch independent calls in one message.
+**Sequential tool calls that could be parallel**: Issuing Glob, then Read, then Grep one at a time when they're independent triples the latency. Batch independent calls in one message.
 
 ## Code Authoring
 
-**Guessing a function signature** — Never guess an API or function signature. Read the source or check the docs first. Wrong signatures produce runtime errors that cost a full round-trip to fix.
+**Guessing a function signature**: Never guess an API or function signature. Read the source or check the docs first. Wrong signatures produce runtime errors that cost a full round-trip to fix.
 
-**Editing without reading** — Issuing an Edit without a prior Read produces "oldString not found" failures when the file differs from assumptions. Always read first.
+**Editing without reading**: Issuing an Edit without a prior Read produces "oldString not found" failures when the file differs from assumptions. Always read first.
 
-**Creating new files instead of editing existing ones** — Adding a new file when the logic belongs in an existing one fragments the codebase. Check for the right home first.
+**Creating new files instead of editing existing ones**: Adding a new file when the logic belongs in an existing one fragments the codebase. Check for the right home first.
 
-**Commenting what the code already says** — `// increment counter` above `count++` adds noise. Comments earn their place by explaining non-obvious constraints, not restating syntax.
+**Commenting what the code already says**: `// increment counter` above `count++` adds noise. Comments earn their place by explaining non-obvious constraints, not restating syntax.
 
 ## Testing
 
-**Testing the mock instead of the behavior** — A test that only verifies that a mock was called doesn't confirm the real behavior. Prefer integration-level assertions over spy counts.
+**Testing the mock instead of the behavior**: A test that only verifies that a mock was called doesn't confirm the real behavior. Prefer integration-level assertions over spy counts.
 
-**Skipping the failing test to make CI green** — Skipping tests hides regressions. Fix the failure or delete the test with a comment explaining why it no longer applies.
+**Skipping the failing test to make CI green**: Skipping tests hides regressions. Fix the failure or delete the test with a comment explaining why it no longer applies.
 
 ## Git
 
-**Amending a pushed commit** — `git commit --amend` after a push requires force-push, which rewrites shared history. Use a new commit instead.
+**Amending a pushed commit**: `git commit --amend` after a push requires force-push, which rewrites shared history. Use a new commit instead.
 
-**Committing without running tests** — Tests exist to catch regressions before they land on main. A green build is the only signal that a change is safe to ship.
+**Committing without running tests**: Tests exist to catch regressions before they land on main. A green build is the only signal that a change is safe to ship.
 
 ## Agent Behavior
 
-**Stopping without surfacing incomplete tasks** — An agent that stops while tasks are `in_progress` or have unmet acceptance criteria leaves the user without visibility. Surface the state before stopping.
+**Stopping without surfacing incomplete tasks**: An agent that stops while tasks are `in_progress` or have unmet acceptance criteria leaves the user without visibility. Surface the state before stopping.
 
-**Making assumptions about user intent** — When a requirement is ambiguous, ask one targeted question rather than guessing and building the wrong thing.
+**Making assumptions about user intent**: When a requirement is ambiguous, ask one targeted question rather than guessing and building the wrong thing.

package/examples/seed-observations/decisions.md

@@ -1,5 +1,5 @@
 <!--
-examples/seed-observations/decisions.md — key architectural decisions for Construct memory seed corpus.
+examples/seed-observations/decisions.md: key architectural decisions for Construct memory seed corpus.
 
 Each entry becomes one observation in the store with category "decision". Imported via
 `construct bootstrap`.
@@ -13,7 +13,7 @@ Each entry becomes one observation in the store with category "decision". Import
 
 ## Two-Phase Sync with Lockfile
 
-`construct sync` writes to `.cx/sync-staging/` first, then atomically renames into place. A lockfile at `.cx/sync.lock` prevents concurrent runs from corrupting the output. This makes partial syncs impossible — either the full sync lands or nothing does.
+`construct sync` writes to `.cx/sync-staging/` first, then atomically renames into place. A lockfile at `.cx/sync.lock` prevents concurrent runs from corrupting the output. This makes partial syncs impossible: either the full sync lands or nothing does.
 
 ## Hook Ceiling: 30
 
@@ -25,7 +25,7 @@ The memory layer uses a hashing bag-of-words cosine similarity for dense recall
 
 ## Tiered Session-Start Injection
 
-Session-start injects context in three tiers: Tier 1 (always — header, branch, status), Tier 2 (when fresh and meaningful — workflow, observations, context.md), Tier 3 (hint-only — efficiency snapshot, skill scope). This caps injection size and avoids loading the model with stale or irrelevant context on every session.
+Session-start injects context in three tiers: Tier 1 (always (header, branch, status), Tier 2 (when fresh and meaningful) workflow, observations, context.md), Tier 3 (hint-only: efficiency snapshot, skill scope). This caps injection size and avoids loading the model with stale or irrelevant context on every session.
 
 ## Declarative Policy Rules
 
@@ -33,4 +33,4 @@ Hook guards for workflow, drive, bootstrap, and task behavior are expressed as Y
 
 ## Registry as Single Source of Truth
 
-`agents/registry.json` is the canonical definition for all agents on all platforms (Claude Code, OpenCode, Codex, Copilot). `construct sync` regenerates all platform-specific files from the registry. Never edit generated files directly — edits are overwritten on the next sync.
+`agents/registry.json` is the canonical definition for all agents on all platforms (Claude Code, OpenCode, Codex, Copilot). `construct sync` regenerates all platform-specific files from the registry. Never edit generated files directly: edits are overwritten on the next sync.

package/examples/seed-observations/patterns.md

@@ -1,5 +1,5 @@
 <!--
-examples/seed-observations/patterns.md — engineering patterns for Construct memory seed corpus.
+examples/seed-observations/patterns.md: engineering patterns for Construct memory seed corpus.
 
 Each entry becomes one observation in the store. Format: ## Category, then pattern entries
 with **Pattern name** and description. Imported via `construct bootstrap`.
@@ -9,34 +9,34 @@ with **Pattern name** and description. Imported via `construct bootstrap`.
 
 ## Code Quality
 
-**Read before edit** — Always read the target file with the Read tool before writing or editing. Editing without reading produces stale edits that fail with "oldString not found".
+**Read before edit**: Always read the target file with the Read tool before writing or editing. Editing without reading produces stale edits that fail with "oldString not found".
 
-**Parallel tool calls for independent work** — When two tool calls don't depend on each other's output, issue them in the same message. Cuts wall time roughly in half for multi-file operations.
+**Parallel tool calls for independent work**: When two tool calls don't depend on each other's output, issue them in the same message. Cuts wall time roughly in half for multi-file operations.
 
-**Probe before bulk read** — Use Glob or Grep to identify which files are relevant before reading them. Bulk-reading 10 files to find the one that matters burns context and slows response.
+**Probe before bulk read**: Use Glob or Grep to identify which files are relevant before reading them. Bulk-reading 10 files to find the one that matters burns context and slows response.
 
-**Edit smallest possible diff** — Target the exact lines that need to change. Large oldString blocks with unchanged surrounding context are fragile when the file is modified concurrently.
+**Edit smallest possible diff**: Target the exact lines that need to change. Large oldString blocks with unchanged surrounding context are fragile when the file is modified concurrently.
 
 ## Testing
 
-**Run targeted test first** — Before running the full suite, run only the affected test file. Faster feedback loop; full suite confirms no regressions.
+**Run targeted test first**: Before running the full suite, run only the affected test file. Faster feedback loop; full suite confirms no regressions.
 
-**Assert the contract, not the implementation** — Tests that check internal state (private variables, call counts) break on refactors that don't change behavior. Test the public output.
+**Assert the contract, not the implementation**: Tests that check internal state (private variables, call counts) break on refactors that don't change behavior. Test the public output.
 
-**Table-driven tests for edge cases** — When a function has many input/output pairs to verify, a single table-driven test is more maintainable than N separate `it()` blocks.
+**Table-driven tests for edge cases**: When a function has many input/output pairs to verify, a single table-driven test is more maintainable than N separate `it()` blocks.
 
 ## Git Discipline
 
-**Branch, test, merge** — Never commit directly to main. Branch for every feature or fix, verify tests pass, then merge.
+**Branch, test, merge**: Never commit directly to main. Branch for every feature or fix, verify tests pass, then merge.
 
-**Commit message: why, not what** — The diff already shows what changed. The commit message should explain why. "fix dry-run bypass" is less useful than "fix: dry-run skipped mkdirp calls, causing 31 phantom files in test home".
+**Commit message: why, not what**: The diff already shows what changed. The commit message should explain why. "fix dry-run bypass" is less useful than "fix: dry-run skipped mkdirp calls, causing 31 phantom files in test home".
 
-**Atomic commits** — One logical change per commit. Mixing a bug fix with a refactor makes bisect and revert painful.
+**Atomic commits**: One logical change per commit. Mixing a bug fix with a refactor makes bisect and revert painful.
 
 ## Agent Dispatch
 
-**Route through Construct** — Construct is the single dispatch point. Invoking specialist agents directly bypasses context injection and workflow tracking.
+**Route through Construct**: Construct is the single dispatch point. Invoking specialist agents directly bypasses context injection and workflow tracking.
 
-**Subagent for isolated subtasks** — Use Task tool dispatch when a subtask has a clear input/output contract and doesn't need the parent conversation history. Keeps the main context lean.
+**Subagent for isolated subtasks**: Use Task tool dispatch when a subtask has a clear input/output contract and doesn't need the parent conversation history. Keeps the main context lean.
 
-**Timeout specialist calls** — Agent dispatch without a timeout can block indefinitely. Set `timeout: 120_000` as a floor; use 300_000 for heavy analysis tasks.
+**Timeout specialist calls**: Agent dispatch without a timeout can block indefinitely. Set `timeout: 120_000` as a floor; use 300_000 for heavy analysis tasks.

package/lib/auto-docs.mjs

@@ -71,7 +71,7 @@ function buildCoreDocsContract() {
     '| `docs/README.md` | Docs index and maintenance contract | Core docs set or maintenance expectations change |',
     '| `docs/concepts/architecture.md` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
     '',
-    '`plan.md` is a local working document. `construct init` creates it for the active session, but it is gitignored and not committed — durable work belongs in the tracker (Beads or external).',
+    '`plan.md` is a local working document. `construct init` creates it for the active session, but it is gitignored and not committed; durable work belongs in the tracker (Beads or external).',
     '',
     'Tracker hierarchy: external tracker (prefer Beads) for durable work, `plan.md` for the local working plan, and cass-memory via MCP `memory` for cross-session recall.',
     '',
@@ -82,7 +82,7 @@ function buildCoreDocsContract() {
 
 const DIR_DESCRIPTIONS = {
   agents: 'Registry and generated platform adapter chains',
-  apps: 'User-facing apps shipped from this repo (e.g., apps/docs/ — Fumadocs docs site)',
+  apps: 'User-facing apps shipped from this repo (e.g. apps/docs/, the Fumadocs docs site)',
   bin: 'CLI entrypoint (`construct`)',
   claude: 'Claude Code integration (agents, settings template)',
   commands: 'Command prompt assets',
@@ -160,9 +160,14 @@ function buildAgentsTable(rootDir) {
 
   const rows = ['| Agent | Tier | Purpose |', '|---|---|---|'];
   for (const agent of agents.slice(0, 30)) {
-    const name = agent.id ?? agent.name ?? '—';
-    const tier = agent.tier ?? agent.model_tier ?? '—';
-    const purpose = (agent.description ?? agent.purpose ?? '').split('\n')[0].slice(0, 80);
+    const name = agent.id ?? agent.name ?? 'n/a';
+    const tier = agent.tier ?? agent.model_tier ?? 'n/a';
+    // Strip em-dashes from descriptions so the prose lint stays clean across
+    // AUTO regen. Em-dashes are allowed in the registry's source descriptions
+    // but never in the rendered markdown.
+    const purpose = (agent.description ?? agent.purpose ?? '')
+      .split('\n')[0].slice(0, 80)
+      .replace(/ — /g, '. ').replace(/—/g, ',');
     rows.push(`| \`${name}\` | ${tier} | ${purpose} |`);
   }
   if (agents.length > 30) rows.push(`| *(+${agents.length - 30} more)* | | |`);

package/lib/cli-commands.mjs

@@ -92,7 +92,7 @@ export const CLI_COMMANDS = [
     emoji: '📥',
     category: 'Core',
     core: true,
-    description: 'View and process R&D intake queue',
+    description: 'View and process the active profile\'s intake queue (queue label varies by profile)',
     usage: 'construct intake list|show|done|skip',
   },
   {
@@ -128,6 +128,50 @@ export const CLI_COMMANDS = [
       { name: 'search <query>', desc: 'Search customer profiles by name/alias' },
     ],
   },
+  {
+    name: 'knowledge',
+    emoji: '🧠',
+    category: 'Work',
+    core: false,
+    description: 'Query, index, or add to the project knowledge base',
+    usage: 'construct knowledge trends|index|add',
+    subcommands: [
+      { name: 'trends', desc: 'Show trend report across observations and artifacts' },
+      { name: 'index', desc: 'Rebuild the local RAG corpus over .cx/ artifacts' },
+      { name: 'add --source=research --slug=<id> --topic="..." [--source-url=<url>]', desc: 'Persist a research finding into .cx/knowledge/external/research/' },
+    ],
+  },
+  {
+    name: 'sandbox',
+    emoji: '🧪',
+    category: 'Core',
+    core: true,
+    description: 'Isolated tmpdir-based environment for QA / specialist dry-runs',
+    usage: 'construct sandbox create|list|delete|prune [--profile=<id>]',
+    subcommands: [
+      { name: 'create [--profile=<id>]', desc: 'Create a new sandbox under ~/.cx/sandboxes/' },
+      { name: 'list', desc: 'List existing sandboxes, newest first' },
+      { name: 'delete <id>', desc: 'Remove one sandbox by id' },
+      { name: 'prune [--days=N]', desc: 'Remove sandboxes older than N days (default 7)' },
+    ],
+  },
+  {
+    name: 'profile',
+    emoji: '🧭',
+    category: 'Core',
+    core: true,
+    description: 'Manage the active org profile and its lifecycle (draft, promote, archive, health)',
+    usage: 'construct profile show|list|set|create|drafts|archive|health',
+    subcommands: [
+      { name: 'show', desc: 'Show the active profile' },
+      { name: 'list', desc: 'List curated profiles' },
+      { name: 'set <id>', desc: 'Switch the active profile (writes construct.config.json)' },
+      { name: 'create <id> [--display=…] [--role=…] [--department=…] [--yes|--dry-run]', desc: 'Scaffold a draft profile; previews and confirms by default, prompts interactively when no flags' },
+      { name: 'drafts', desc: 'List in-progress draft profiles' },
+      { name: 'archive <id> --reason="..."', desc: 'Move a curated profile into archive/profiles/<id>/' },
+      { name: 'health <id> [--days=N]', desc: 'Per-profile observation + outcome rollup' },
+    ],
+  },
   {
     name: 'workspace',
     emoji: '🏢',

package/lib/comment-lint.mjs

@@ -42,7 +42,13 @@ function requiresHeader(rel) {
   if (rel.startsWith('lib/server/static/')) {
     return { required: false, type: null };
   }
-  const type = (jsMatch && ext !== '.html') ? 'js' : (jsMatch || mdMatch) ? 'md' : null;
+  // Markdown files always get markdown-style headers, even if the directory
+  // glob (e.g. ^tests/) primarily targets JS sources. Without this, .md docs
+  // co-located with .mjs tests were forced into /** */ format.
+  let type;
+  if (ext === '.md') type = mdMatch || jsMatch ? 'md' : null;
+  else if (jsMatch && ext !== '.html') type = 'js';
+  else type = (jsMatch || mdMatch) ? 'md' : null;
   return { required: jsMatch || mdMatch, type };
 }
 

package/lib/config/schema.mjs

@@ -20,6 +20,7 @@ export const CONFIG_SCHEMA_VERSION = 1;
 
 export const DEPLOYMENT_MODES = ['solo', 'team', 'enterprise'];
 export const MCP_BROKER_VALUES = ['auto', 'on', 'off'];
+export const DEFAULT_PROFILE_ID = 'rnd';
 
 export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   version: CONFIG_SCHEMA_VERSION,
@@ -31,6 +32,7 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
     tenantId: null,
   }),
   providers: Object.freeze({}),
+  profile: DEFAULT_PROFILE_ID,
   autoEmbed: false,
   telemetry: Object.freeze({
     enabled: true,
@@ -77,6 +79,7 @@ export const FIELD_RULES = {
     },
   },
   providers: { type: 'object', required: false },
+  profile: { type: 'string', required: false, maxLength: 40 },
   autoEmbed: { type: 'boolean', required: false },
   telemetry: {
     type: 'object',

package/lib/flavors/loader.mjs

@@ -0,0 +1,136 @@
+/**
+ * lib/flavors/loader.mjs — Role flavor overlay loader and validator.
+ *
+ * Reads frontmatter from skills/roles/<role>.<flavor>.md files, exposes:
+ *   - listFlavors(role?, profile?) — overlays that apply to role and profile
+ *   - validateFlavor(path) — frontmatter conformance check against the schema
+ *   - perRoleFlavorCount(profile) — flavor counts per role for cap enforcement
+ *
+ * The cap is enforced at sync time and in lint-prose's sibling lint-flavors.
+ * Six flavors per role per profile is the current ceiling; bumping requires
+ * an ADR. Existing roles like qa already have 6, so the cap is set tight.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..');
+const FLAVORS_DIR = path.join(REPO_ROOT, 'skills', 'roles');
+
+export const FLAVOR_CAP_PER_ROLE_PER_PROFILE = 6;
+
+// Files may start with an HTML comment block before the YAML frontmatter.
+// The /m flag lets ^ match line-start so we find the YAML wherever it sits.
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/m;
+
+function parseFrontmatter(content) {
+  const m = FRONTMATTER_RE.exec(content);
+  if (!m) return null;
+  const out = {};
+  let currentArrayKey = null;
+  for (const rawLine of m[1].split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!line.trim()) continue;
+    if (currentArrayKey && /^\s*-\s+/.test(line)) {
+      out[currentArrayKey].push(line.replace(/^\s*-\s+/, '').trim());
+      continue;
+    }
+    currentArrayKey = null;
+    const kv = /^([a-z_]+):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    const [, key, valueRaw] = kv;
+    const value = valueRaw.trim();
+    if (value === '') {
+      out[key] = [];
+      currentArrayKey = key;
+    } else if (value.startsWith('[') && value.endsWith(']')) {
+      const items = value.slice(1, -1).split(',').map((s) => s.trim()).filter(Boolean);
+      out[key] = items;
+    } else if (value === 'null') {
+      out[key] = null;
+    } else if (/^-?\d+$/.test(value)) {
+      out[key] = Number(value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Read and parse every overlay in skills/roles/. Returns { path, frontmatter }
+ * tuples. Files without parseable frontmatter are skipped silently.
+ */
+export function listAllFlavors() {
+  if (!fs.existsSync(FLAVORS_DIR)) return [];
+  const out = [];
+  for (const f of fs.readdirSync(FLAVORS_DIR)) {
+    if (!f.endsWith('.md') || f === 'README.md') continue;
+    const full = path.join(FLAVORS_DIR, f);
+    const content = fs.readFileSync(full, 'utf8');
+    const fm = parseFrontmatter(content);
+    if (fm) out.push({ path: full, file: f, frontmatter: fm });
+  }
+  return out;
+}
+
+/**
+ * Return overlays that match the given role (any-flavor for that role) and
+ * apply to the given profile. Pass undefined for either to skip that filter.
+ */
+export function listFlavors({ role, profile } = {}) {
+  return listAllFlavors().filter(({ frontmatter }) => {
+    if (role) {
+      const roleId = frontmatter.role || '';
+      const baseRole = roleId.split('.')[0];
+      if (baseRole !== role && roleId !== role) return false;
+    }
+    if (profile) {
+      const profiles = frontmatter.profiles;
+      if (!Array.isArray(profiles) || profiles.length === 0) return true;
+      if (!profiles.includes(profile)) return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * Count flavor overlays per base role for a given profile.
+ * Returns { [baseRole]: count }. Excludes the canonical base file (e.g.
+ * architect.md) so only true flavors count toward the cap.
+ */
+export function perRoleFlavorCount(profile = 'rnd') {
+  const counts = {};
+  for (const entry of listFlavors({ profile })) {
+    const roleId = entry.frontmatter.role || '';
+    const isFlavor = roleId.includes('.');
+    if (!isFlavor) continue;
+    const base = roleId.split('.')[0];
+    counts[base] = (counts[base] || 0) + 1;
+  }
+  return counts;
+}
+
+/**
+ * Validate one overlay's frontmatter against the schema invariants. Returns
+ * an array of error strings; empty array means valid.
+ */
+export function validateFlavor(filePath) {
+  const errors = [];
+  if (!fs.existsSync(filePath)) return [`file not found: ${filePath}`];
+  const content = fs.readFileSync(filePath, 'utf8');
+  const fm = parseFrontmatter(content);
+  if (!fm) return [`${filePath}: missing or unparseable frontmatter`];
+
+  if (!fm.role || !/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)?$/.test(fm.role)) {
+    errors.push(`${filePath}: invalid role "${fm.role}"`);
+  }
+  if (!Array.isArray(fm.applies_to) || fm.applies_to.length === 0) {
+    errors.push(`${filePath}: applies_to must be a non-empty array`);
+  }
+  if (!Array.isArray(fm.profiles) || fm.profiles.length === 0) {
+    errors.push(`${filePath}: profiles must be a non-empty array; add a frontmatter line like \`profiles: [rnd]\``);
+  }
+  return errors;
+}

package/lib/hooks/agent-tracker.mjs

@@ -119,7 +119,7 @@ try {
     if (success !== null) {
       const learningDir = join(cxDir, 'learning', agentName);
       mkdirSync(learningDir, { recursive: true });
-      
+
       const learningFile = join(learningDir, `${Date.now()}-${success ? 'success' : 'failure'}.json`);
       const learningEntry = {
         agent: agentName,
@@ -127,13 +127,32 @@ try {
         description,
         outcome,
         timestamp: new Date().toISOString(),
-        // Extract potential patterns from description
         keywords: extractKeywords(description),
         taskType: classifyTaskType(description)
       };
-      
+
       writeFileSync(learningFile, JSON.stringify(learningEntry, null, 2) + '\n');
     }
+
+    // A3 outcome capture: record the per-project outcome JSONL that feeds
+    // .cx/outcomes/_summary.json and the classifier's tiebreaker. Best-effort;
+    // any failure leaves the existing telemetry paths above untouched.
+    if (success !== null) {
+      try {
+        const { recordOutcome } = await import('../outcomes/record.mjs');
+        const { resolveActiveProfile } = await import('../profiles/loader.mjs');
+        const roleId = agentName.replace(/^cx-/, '');
+        const projectCwd = input?.cwd || process.cwd();
+        const activeProfile = resolveActiveProfile(projectCwd);
+        recordOutcome(projectCwd, {
+          role: roleId,
+          success,
+          notes: outcome,
+          source: 'agent-tracker',
+          profile: activeProfile?.id ?? null,
+        });
+      } catch { /* best effort */ }
+    }
   }
   
 } catch (error) {

package/lib/hooks/pre-push-gate.mjs

@@ -189,13 +189,26 @@ function runNpmGate(projectDir) {
   const jobs = [];
   if (hasTest || hasCi) jobs.push({ label: 'tests', cmd: runner, args: ['run', testScript],                  timeout: 90_000 });
   if (hasBuild)         jobs.push({ label: 'build', cmd: runner, args: ['run', 'build'],                     timeout: 120_000 });
-  jobs.push({                       label: 'audit', cmd: 'npm',  args: ['audit', '--omit=dev', '--audit-level=high'], timeout: 30_000 });
+  // Use the project's package manager for audit so the lockfile format matches.
+  const auditArgs = runner === 'pnpm'
+    ? ['audit', '--prod', '--audit-level=high']
+    : runner === 'yarn'
+      ? ['npm-audit', '--groups', 'dependencies', '--level', 'high']
+      : ['audit', '--omit=dev', '--audit-level=high'];
+  jobs.push({                       label: 'audit', cmd: runner, args: auditArgs, timeout: 30_000 });
 
   if (existsSync(join(projectDir, 'bin/construct'))) {
     jobs.push({ label: 'evals', cmd: 'node', args: ['bin/construct', 'evals', 'retrieval'], timeout: 60_000 });
     jobs.push({ label: 'docs',  cmd: 'node', args: ['bin/construct', 'docs:verify'],        timeout: 15_000 });
   }
 
+  if (existsSync(join(projectDir, 'scripts/lint-prose.mjs'))) {
+    jobs.push({ label: 'prose',    cmd: 'node', args: ['scripts/lint-prose.mjs'],         timeout: 15_000 });
+  }
+  if (existsSync(join(projectDir, 'scripts/lint-profiles.mjs'))) {
+    jobs.push({ label: 'profiles', cmd: 'node', args: ['scripts/lint-profiles.mjs', '--quiet'], timeout: 15_000 });
+  }
+
   return { projectDir, jobs };
 }
 

package/lib/hooks/session-optimize.mjs

@@ -128,8 +128,9 @@ function optimizeAgent(agentName) {
   const startTime = Date.now();
   
   try {
-    // Run construct optimize with auto-apply (no --dry-run)
-    const result = spawnSync(CONSTRUCT_BIN, ['optimize', agentName, `--days=${OPTIMIZATION_DAYS}`], {
+    // Preview only. The new contract requires an explicit --apply from the
+    // operator; hook-driven runs must never modify prompt files.
+    const result = spawnSync(CONSTRUCT_BIN, ['optimize', agentName, `--days=${OPTIMIZATION_DAYS}`, '--dry-run'], {
       cwd,
       encoding: 'utf8',
       timeout: 300000, // 5 minutes timeout for optimization