@geraldmaron/construct 1.0.5 → 1.0.6

package/commands/review/code.md

@@ -1,10 +1,10 @@
 <!--
-commands/review/code.md — Code review — correctness, regressions, security, test coverage
+commands/review/code.md (Code review) correctness, regressions, security, test coverage
 
-Code review — correctness, regressions, security, test coverage
+Code review: correctness, regressions, security, test coverage
 -->
 ---
-description: Code review — correctness, regressions, security, test coverage
+description: Code review: correctness, regressions, security, test coverage
 ---
 
 You are Construct. Review: $ARGUMENTS
@@ -12,10 +12,10 @@ You are Construct. Review: $ARGUMENTS
 If no target specified, review all uncommitted changes (`git diff HEAD`).
 
 Check in order:
-1. Correctness — does it do what it's supposed to?
-2. Regression — does it break anything that was working?
-3. Security — injection, auth, secrets, data exposure
-4. Coverage — are there tests for changed or new behavior?
-5. Maintainability — can someone unfamiliar understand it?
+1. Correctness: does it do what it's supposed to?
+2. Regression: does it break anything that was working?
+3. Security: injection, auth, secrets, data exposure
+4. Coverage: are there tests for changed or new behavior?
+5. Maintainability: can someone unfamiliar understand it?
 
 Rate each finding: CRITICAL / HIGH / MEDIUM / LOW. State clearly if no CRITICAL or HIGH findings exist.

package/commands/review/quality.md

@@ -1,10 +1,10 @@
 <!--
-commands/review/quality.md — Quality audit — complexity, naming, duplication, dead code, maintainability
+commands/review/quality.md (Quality audit) complexity, naming, duplication, dead code, maintainability
 
-Quality audit — complexity, naming, duplication, dead code, maintainability
+Quality audit: complexity, naming, duplication, dead code, maintainability
 -->
 ---
-description: Quality audit — complexity, naming, duplication, dead code, maintainability
+description: Quality audit: complexity, naming, duplication, dead code, maintainability
 ---
 
 You are Construct. Audit quality for: $ARGUMENTS
@@ -16,4 +16,4 @@ Check:
 - Unused exports, unreachable branches, stale imports
 - Coupling, unclear data flow
 
-Rate findings: CRITICAL / HIGH / MEDIUM / LOW. Describe the fix — do not rewrite unprompted.
+Rate findings: CRITICAL / HIGH / MEDIUM / LOW. Describe the fix: do not rewrite unprompted.

package/commands/review/security.md

@@ -1,10 +1,10 @@
 <!--
-commands/review/security.md — Security scan — secrets, auth, injection, data exposure, dependency risk
+commands/review/security.md (Security scan) secrets, auth, injection, data exposure, dependency risk
 
-Security scan — secrets, auth, injection, data exposure, dependency risk
+Security scan: secrets, auth, injection, data exposure, dependency risk
 -->
 ---
-description: Security scan — secrets, auth, injection, data exposure, dependency risk
+description: Security scan: secrets, auth, injection, data exposure, dependency risk
 ---
 
 You are Construct. Scan: $ARGUMENTS

package/commands/ship/ready.md

@@ -1,10 +1,10 @@
 <!--
-commands/ship/ready.md — Pre-release check — is this ready to ship?
+commands/ship/ready.md (Pre-release check) is this ready to ship?
 
-Pre-release check — is this ready to ship?
+Pre-release check: is this ready to ship?
 -->
 ---
-description: Pre-release check — is this ready to ship?
+description: Pre-release check: is this ready to ship?
 ---
 
 You are Construct. Check if the following is ready: $ARGUMENTS

package/commands/ship/release.md

@@ -1,10 +1,10 @@
 <!--
-commands/ship/release.md — Release — plan rollout, changelog, rollback, and post-release verification
+commands/ship/release.md (Release) plan rollout, changelog, rollback, and post-release verification
 
-Release — plan rollout, changelog, rollback, and post-release verification
+Release: plan rollout, changelog, rollback, and post-release verification
 -->
 ---
-description: Release — plan rollout, changelog, rollback, and post-release verification
+description: Release: plan rollout, changelog, rollback, and post-release verification
 ---
 
 You are Construct. Release the following: $ARGUMENTS

package/commands/ship/status.md

@@ -1,16 +1,16 @@
 <!--
-commands/ship/status.md — Status — current project state, workflow, uncommitted changes, recent activity
+commands/ship/status.md (Status) current project state, workflow, uncommitted changes, recent activity
 
-Status — current project state, workflow, uncommitted changes, recent activity
+Status: current project state, workflow, uncommitted changes, recent activity
 -->
 ---
-description: Status — current project state, workflow, uncommitted changes, recent activity
+description: Status: current project state, workflow, uncommitted changes, recent activity
 ---
 
 You are Construct. Report status for: $ARGUMENTS
 
 Check and report:
-1. Tracker and `plan.md` state — active slices, blockers, and ownership boundaries
+1. Tracker and `plan.md` state: active slices, blockers, and ownership boundaries
 2. Uncommitted changes via `git status`
 3. Recent commits via `git log --oneline -10`
 4. Active branch and relationship to main

package/commands/understand/docs.md

@@ -1,10 +1,10 @@
 <!--
-commands/understand/docs.md — Look up documentation — current behavior from primary sources, not training memory
+commands/understand/docs.md (Look up documentation) current behavior from primary sources, not training memory
 
-Look up documentation — current behavior from primary sources, not training memory
+Look up documentation: current behavior from primary sources, not training memory
 -->
 ---
-description: Look up documentation — current behavior from primary sources, not training memory
+description: Look up documentation: current behavior from primary sources, not training memory
 ---
 
 You are Construct. Look up: $ARGUMENTS

package/commands/understand/this.md

@@ -1,15 +1,15 @@
 <!--
-commands/understand/this.md — Explore and understand something — trace execution paths, map structure, gather evidence
+commands/understand/this.md (Explore and understand something) trace execution paths, map structure, gather evidence
 
-Explore and understand something — trace execution paths, map structure, gather evidence
+Explore and understand something: trace execution paths, map structure, gather evidence
 -->
 ---
-description: Explore and understand something — trace execution paths, map structure, gather evidence
+description: Explore and understand something: trace execution paths, map structure, gather evidence
 ---
 
 You are Construct. Explore and explain: $ARGUMENTS
 
-Gather evidence — do not propose solutions unless asked.
+Gather evidence: do not propose solutions unless asked.
 
 1. Search for the specific symbol, pattern, or behavior
 2. Trace the execution path from entry point to outcome

package/commands/understand/why.md

@@ -1,18 +1,18 @@
 <!--
-commands/understand/why.md — Investigate a failure — why is this broken, what is the root cause
+commands/understand/why.md (Investigate a failure) why is this broken, what is the root cause
 
-Investigate a failure — why is this broken, what is the root cause
+Investigate a failure: why is this broken, what is the root cause
 -->
 ---
-description: Investigate a failure — why is this broken, what is the root cause
+description: Investigate a failure: why is this broken, what is the root cause
 ---
 
 You are Construct. Investigate: $ARGUMENTS
 
-1. Capture — exact error, stack trace, reproduction steps
-2. Reproduce — confirm you can trigger the failure consistently
-3. Isolate — narrow to the smallest failing case
-4. Trace — follow data and control flow to where the invariant breaks
-5. Root cause — the one upstream cause that, if fixed, prevents the failure
+1. Capture: exact error, stack trace, reproduction steps
+2. Reproduce: confirm you can trigger the failure consistently
+3. Isolate: narrow to the smallest failing case
+4. Trace: follow data and control flow to where the invariant breaks
+5. Root cause: the one upstream cause that, if fixed, prevents the failure
 
 Do not plan a fix until root cause is confirmed. If you cannot reproduce, say so immediately and ask for more context.

package/commands/work/clean.md

@@ -1,10 +1,10 @@
 <!--
-commands/work/clean.md — Remove AI-generated code smells — verbosity, hedging, dead comments, generic names
+commands/work/clean.md (Remove AI-generated code smells) verbosity, hedging, dead comments, generic names
 
-Remove AI-generated code smells — verbosity, hedging, dead comments, generic names
+Remove AI-generated code smells: verbosity, hedging, dead comments, generic names
 -->
 ---
-description: Remove AI-generated code smells — verbosity, hedging, dead comments, generic names
+description: Remove AI-generated code smells: verbosity, hedging, dead comments, generic names
 ---
 
 You are cx-reviewer identifying AI slop in: $ARGUMENTS
@@ -13,17 +13,17 @@ Then dispatch cx-engineer to apply the fixes.
 
 ## What to remove
 
-1. **Obvious comments** — `// This function calculates X` when the function is named `calculateX`
-2. **Hedging names** — `result`, `data`, `temp`, `item`, `obj`, `value`, `response` — rename to reflect what they actually contain
-3. **Debug artifacts** — `console.log`, `print`, `debugger`, leftover logging statements
-4. **Unnecessary wrapping** — functions that do nothing except call one other function with no transformation
-5. **Dead TODO blocks** — `// TODO: remove later`, `// FIXME: clean this up`, stale commented-out code
-6. **Restated types** — `const userArray: User[] = []` → name already says it's a list, annotation adds nothing
-7. **Over-specified assertions** — test assertions that restate the implementation rather than the behavior
-8. **Swallowed errors** — `catch (e) {}` or `catch (e) { return null }` with no context or logging
-9. **Single-use abstractions** — helper created for one call site that could just be inline
-10. **Padded error messages** — `"An error occurred while attempting to process your request"` → `"Failed to process request"`
-11. **Boilerplate docstrings** — JSDoc/docstrings that only restate the parameter names
+1. **Obvious comments**: `// This function calculates X` when the function is named `calculateX`
+2. **Hedging names** (`result`, `data`, `temp`, `item`, `obj`, `value`, `response`) rename to reflect what they actually contain
+3. **Debug artifacts**: `console.log`, `print`, `debugger`, leftover logging statements
+4. **Unnecessary wrapping**: functions that do nothing except call one other function with no transformation
+5. **Dead TODO blocks**: `// TODO: remove later`, `// FIXME: clean this up`, stale commented-out code
+6. **Restated types**: `const userArray: User[] = []` → name already says it's a list, annotation adds nothing
+7. **Over-specified assertions**: test assertions that restate the implementation rather than the behavior
+8. **Swallowed errors**: `catch (e) {}` or `catch (e) { return null }` with no context or logging
+9. **Single-use abstractions**: helper created for one call site that could just be inline
+10. **Padded error messages**: `"An error occurred while attempting to process your request"` → `"Failed to process request"`
+11. **Boilerplate docstrings**: JSDoc/docstrings that only restate the parameter names
 
 ## Output
 

package/commands/work/drive.md

@@ -1,10 +1,10 @@
 <!--
-commands/work/drive.md — Full autonomous execution — explore, plan, implement, verify, loop until done
+commands/work/drive.md (Full autonomous execution) explore, plan, implement, verify, loop until done
 
-Full autonomous execution — explore, plan, implement, verify, loop until done
+Full autonomous execution: explore, plan, implement, verify, loop until done
 -->
 ---
-description: Full autonomous execution — explore, plan, implement, verify, loop until done
+description: Full autonomous execution: explore, plan, implement, verify, loop until done
 ---
 
 You are Construct in drive mode. Execute $ARGUMENTS fully and autonomously without stopping for confirmation.
@@ -16,11 +16,11 @@ This command turns off planning confirmation, but it does not override validatio
 
 ## Execution Loop
 
-**Step 1 — Explore** (cx-explorer)
+**Step 1: Explore** (cx-explorer)
 Map the codebase areas relevant to the task. Identify entry points, dependencies, and affected modules.
 
-**Step 2 — Plan** (cx-architect)
-Produce a structured plan using the canonical Construct plan format (see `commands/plan/feature.md` — `### T{N} — Title` sections with fielded sub-bullets). Save it to `.cx/plans/{slug}-plan.md`, align `plan.md` to the active tracker-linked slice of work, and identify tasks that can run in parallel by inspecting `dependsOn`.
+**Step 2: Plan** (cx-architect)
+Produce a structured plan using the canonical Construct plan format (see `commands/plan/feature.md` (`### T{N}) Title` sections with fielded sub-bullets). Save it to `.cx/plans/{slug}-plan.md`, align `plan.md` to the active tracker-linked slice of work, and identify tasks that can run in parallel by inspecting `dependsOn`.
 
 Initialize `.cx/drive-state.json`:
 ```json
@@ -45,16 +45,16 @@ As acceptance criteria are verified, record evidence:
 }
 ```
 
-**Step 3 — Implement** (cx-engineer)
+**Step 3: Implement** (cx-engineer)
 Execute tasks. Run independent tasks in parallel where possible. One agent per file to avoid conflicts.
 
-**Step 4 — Validate** (cx-reviewer + cx-security in parallel)
+**Step 4: Validate** (cx-reviewer + cx-security in parallel)
 Review all changes. Flag CRITICAL or HIGH findings. Security reviews all auth, input handling, and data paths.
 
-**Step 5 — Loop**
+**Step 5: Loop**
 If any acceptance criterion is unmet or any CRITICAL/HIGH finding exists, return to Step 3 and address it.
 
-**Step 6 — Done**
+**Step 6: Done**
 Only stop when ALL of the following are true:
 - Every workflow task is `done`
 - Every acceptance criterion has verification evidence

package/commands/work/optimize-prompts.md

@@ -1,10 +1,10 @@
 <!--
-commands/work/optimize-prompts.md — Prompt optimization command.
+commands/work/optimize-prompts.md: Prompt optimization command.
 
 Runs the closed-loop prompt optimization workflow using telemetry trace data.
 -->
 ---
-description: Closed-loop prompt optimization — read telemetry traces, diagnose failures, push improved version to staging
+description: Closed-loop prompt optimization: read telemetry traces, diagnose failures, push improved version to staging
 ---
 
 You are cx-trace-reviewer running a prompt optimization cycle for: $ARGUMENTS
@@ -18,13 +18,13 @@ Optimize prompt fragments and overlays, not the runtime orchestration policy. If
 
 ## Required steps
 
-1. **Read current prompt** — read the agent's prompt from `agents/registry.json` (or its `promptFile`)
-2. **Fetch recent scores** — GET `{CONSTRUCT_TELEMETRY_URL}/api/public/scores?name=quality&limit=200`
-3. **Skip agents with fewer than 20 scored traces** — insufficient signal; note them but do not optimize
-4. **Diagnose failure patterns** — analyze low-scoring traces, identify top 3 recurring patterns
-5. **Generate improved prompt** — targeted edits that address failures without breaking high-scoring behaviors
-6. **Push to staging** — update the prompt in a staging marker comment; log the candidate via `cx_trace` with `promptVersion: staging-{timestamp}`
-7. **Report** — for each agent: before/after median score estimate, patterns addressed, staging version note
+1. **Read current prompt**: read the agent's prompt from `agents/registry.json` (or its `promptFile`)
+2. **Fetch recent scores**: GET `{CONSTRUCT_TELEMETRY_URL}/api/public/scores?name=quality&limit=200`
+3. **Skip agents with fewer than 20 scored traces**: insufficient signal; note them but do not optimize
+4. **Diagnose failure patterns**: analyze low-scoring traces, identify top 3 recurring patterns
+5. **Generate improved prompt**: targeted edits that address failures without breaking high-scoring behaviors
+6. **Push to staging**: update the prompt in a staging marker comment; log the candidate via `cx_trace` with `promptVersion: staging-{timestamp}`
+7. **Report**: for each agent: before/after median score estimate, patterns addressed, staging version note
 
 ## Output
 

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

@@ -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',
   },
   {
@@ -166,7 +166,7 @@ export const CLI_COMMANDS = [
       { 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="..."]', desc: 'Scaffold a draft profile + requirements brief under .cx/profiles/draft-<id>/' },
+      { 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' },

package/lib/flavors/loader.mjs

@@ -130,7 +130,7 @@ export function validateFlavor(filePath) {
     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 (run scripts/migrate-flavors.mjs)`);
+    errors.push(`${filePath}: profiles must be a non-empty array; add a frontmatter line like \`profiles: [rnd]\``);
   }
   return errors;
 }