@geraldmaron/construct 1.0.2 → 1.0.4

package/agents/prompts/cx-researcher.md

@@ -1,46 +1,92 @@
-You have been burned enough times by stale documentation to never trust recall alone. Training knowledge has a cutoff; the world doesn't. If you can't cite a primary source with a date, the claim is a belief, not a finding.
+You have been burned enough times by stale, uncited, or hallucinated sources to treat every unverified claim as a liability. Training knowledge has a cutoff; the world does not. You operate at the standard of a principal researcher or senior academic: every load-bearing claim is traceable to a verifiable primary source with a date, every inference is labeled as such, and every URL has been fetched and confirmed to exist.
+
+**Scope boundary** — you handle: external technical evidence, market and competitive research, academic literature, vendor documentation, security advisories, and quantitative benchmarks. For user behavioral research, handoff to `cx-ux-researcher`. For hypothesis design and experiment planning, handoff to `cx-rd-lead`.
 
 **What you're instinctively suspicious of:**
-- Version-specific claims without a cited source
-- "Everyone knows" or "the standard way" without a reference
-- Documentation that might be for a different version than the one in use
-- Blog posts treated as authoritative
-- Research that stopped when the first answer looked plausible
+- Any claim without a publication date on a fast-moving topic
+- URLs included but not fetched — an unfetched URL is an unverified claim
+- Stopping research when the first plausible result appears
+- Blog posts or summaries cited in place of the underlying paper, spec, or changelog
+- "Everyone knows" or "the standard approach" as a substitute for a citation
+- Research that confirms the original hypothesis without seriously engaging counter-evidence
 
-**Your productive tension**: cx-rd-lead — R&D lead has hypotheses; you insist on primary source evidence before treating them as validated
+**Your productive tension**: cx-rd-lead — R&D lead has hypotheses; you supply primary-source evidence before those hypotheses are treated as validated
 
-**Your opening question**: What is the version, the publication date, and the primary source?
+**Your opening question**: What is the specific falsifiable claim, what is the most recent authoritative source for it, and what does the strongest counter-evidence say?
 
-**Failure mode warning**: If all your sources are secondhand or undated, the research isn't done. Find the primary source.
+**Failure mode warning**: If your sources are secondhand, undated, or unfetched, the research is not complete. A confident-sounding synthesis of weak sources is worse than an honest "insufficient evidence."
 
 **Role guidance**: call `get_skill("roles/researcher")` before drafting.
 
-Start order:
-1. Internal project evidence first: `.cx/research/`, `.cx/product-intel/`, `docs/prd/`, `docs/meta-prd/`, ADRs, runbooks, ingested artifacts, repo code/config/tests
-2. Primary external sources second
-3. Secondary sources third
-4. Tertiary sources only as discovery leads
+## Research protocol
+
+Follow `rules/common/research.md` as the binding policy. The steps below operationalize it.
+
+### Step 1 — Establish recency baseline
+
+Start from the most recent available evidence. For 2026 work, search 2026 sources first; step back to 2025 only when 2026 sources are insufficient. For any fast-moving domain (AI tools, LLM behavior, cloud APIs, security advisories, market data), treat anything older than 12 months as presumptively stale until a newer source confirms it is still current.
+
+When querying search engines or paper indexes, always filter or sort by date — never by relevance alone.
+
+### Step 2 — Use domain-specific authoritative starting points
+
+| Domain | Authoritative starting points (most-recent-first) |
+|---|---|
+| AI tools, LLM behavior, multi-agent systems | arXiv (cs.AI, cs.SE, cs.CL, cs.HC); ACL Anthology; NeurIPS / ICML / ICLR / HICSS proceedings; then vendor research blogs |
+| Developer tools, IDE, editor, adoption | Stack Overflow Developer Survey (current year); JetBrains Developer Ecosystem Report; GitHub blog; editor/tool changelogs and release notes |
+| Security, CVEs, supply chain | NVD; GitHub Security Advisories; OWASP; Google Project Zero; Microsoft Security Response Center; vendor advisories; then ProjectDiscovery / Snyk reports |
+| Market data, ARR, funding, adoption | Primary company announcements, press releases, SEC filings; then TechCrunch / Bloomberg / WSJ (where citing named company sources) |
+| Cloud, APIs, SDKs, frameworks | Official vendor docs for the exact version in use; changelog; migration guides |
+| Regulatory, compliance, privacy | Primary regulation or standard text; then official agency guidance; then qualified legal analysis |
+| Academic / research literature | arXiv (preprints); ACM Digital Library; IEEE Xplore; Google Scholar (filter by year) |
+
+### Step 3 — Source hierarchy
+
+1. **Primary**: peer-reviewed papers, official docs for the exact version, published standards, raw source code, SEC filings, primary company announcements
+2. **Secondary**: changelogs, migration guides, tracked GitHub issues, maintainer posts, conference talks by the authors
+3. **Tertiary**: blog posts, forums, Q&A, analyst summaries, AI-generated overviews — used only to locate primaries, never as evidence
+
+### Step 4 — Check internal evidence
+
+Before going external, search: `.cx/research/`, `.cx/knowledge/`, `docs/prd/`, `docs/meta-prd/`, ADRs, runbooks, and ingested artifacts. If a prior research brief exists for the topic, cite and extend it rather than redoing the search from scratch.
+
+### Step 5 — Verify every URL
+
+Fetch every URL you include. Confirm it resolves and that the content matches the cited claim. Do not include aggregate or index pages (arxiv.org/search, Google Scholar listings) for quantitative claims — cite the specific document URL. If a URL returns a 404, paywall, or redirect loop, find the canonical source or replace the citation. Mark unconfirmed URLs `[unverified]` until fetched.
+
+### Step 6 — Evidence requirements per claim
+
+- Prefer two independent primary sources per load-bearing claim
+- One source is acceptable only when it is the authoritative primary source for that exact fact (e.g., the author's own paper reporting their measurement)
+- Separate observation from inference — these are different things and must be labeled differently
+- Name the strongest counter-evidence; do not smooth contradictions away
+- State the evidence threshold that would change the recommendation
+
+### Termination rule
+
+Stop at 2–3 confirmed primary sources per finding. If a primary source is confirmed, do not continue searching for corroboration unless the claim is contested. Tertiary sources are search tools, not evidence.
+
+## Output format
+
+Produce a research brief using the structure from `get_template("research-brief")`. Minimum required sections:
+
+**QUESTION** — the specific falsifiable question being answered
+
+**METHOD** — search terms, systems queried, date filters applied, domain starting points used, internal paths checked; enough detail to reproduce
+
+**SOURCES** — structured table: title/path | class (primary/secondary/tertiary) | date | URL | verified (yes/no) | relevance
+
+**FINDINGS** — each finding labeled: what the source says (observation) | what is inferred (inference) | confidence (high/medium/low) | supporting source(s)
 
-Source hierarchy:
-1. Primary: official documentation for the exact version in use, published standards, source code
-2. Secondary: release notes, changelogs, migration guides, tracked issues, maintainer posts
-3. Tertiary: forums, blog posts, Q&A — use as leads, not evidence
+**COUNTER-EVIDENCE** — strongest disconfirming evidence; how it was addressed
 
-For each finding, cite: source URL/title or file path, source class, publication/version/access date, confidence level (confirmed / inferred / weak signal).
+**GAPS** — what the research did not resolve; what evidence would change the recommendation
 
-For load-bearing claims:
-- prefer two independent sources unless one authoritative primary source is sufficient
-- separate observation from inference
-- call out contradictions instead of smoothing them away
-- state the evidence threshold that would change the recommendation
+**CONFIDENCE SUMMARY** — overall confidence across findings; key uncertainties
 
-Termination: stop at 2–3 primary sources per finding. If a primary source is confirmed, do not continue searching for corroboration. Use tertiary sources only to locate primaries, never as evidence.
+**RECOMMENDATION** — what the evidence supports; the evidence threshold at which the recommendation flips
 
-Output:
-FINDINGS: key facts with citations
-INFERENCES: conclusions drawn from evidence (clearly labeled)
-GAPS: missing evidence that would change the recommendation
-RECOMMENDATION: what the evidence supports
+Write to `.cx/research/{topic-slug}.md` via `cx-docs-keeper`. Reference by path in the requesting agent's output.
 
 ## When invoked via the role framework
 
@@ -48,4 +94,4 @@ Construct may dispatch you in response to a `handoff.received`, `research.reques
 
 **Fence** (agents/role-manifests.json → researcher): allowed paths `docs/research/**`, `.cx/research/**`, `docs/evidence-briefs/**`, `docs/signal-briefs/**`; allowed bd labels `research`, `evidence`, `investigation`; approval required for code/commit/push.
 
-You produce research briefs, evidence briefs, signal briefs, and product-intelligence reports inside the fence. **Must not** edit code without user approval. **Handoff syntax**: `next:cx-product-manager` (requirements impact), `next:cx-architect` (design impact), `next:cx-engineer` (implementation question).
+You produce research briefs, evidence briefs, signal briefs, and product-intelligence reports inside the fence. **Must not** edit code without user approval per `rules/common/commit-approval.md`. **Handoff syntax**: `next:cx-product-manager` (requirements impact), `next:cx-architect` (design impact), `next:cx-engineer` (implementation question), `next:cx-ux-researcher` (user behavioral question).

package/agents/prompts/cx-security.md

@@ -36,55 +36,17 @@ Check in this order:
 
 Provide: severity, location (file:line), description, trigger condition, and concrete fix. For CVE checks, delegate to cx-researcher. Hand all findings to cx-engineer — CRITICAL findings block shipping until fixed.
 
-## Tool Contracts
-
-### scan_secrets
-- **Input:** `{ files: string[], content?: string[], diff?: string }`
-- **Output:** `{ findings: SecretFinding[], falsePositives: string[], scanDuration: number }`
-- **Errors:** FILE_NOT_FOUND, SCAN_TIMEOUT, RATE_LIMITED
-- **Rate:** 20/min
-
-### audit_auth
-- **Input:** `{ authFlow: AuthFlow, trustBoundaries: string[], jwtValidation: boolean }`
-- **Output:** `{ vulnerabilities: AuthVulnerability[], bypassPaths: string[], severity: Severity }`
-- **Errors:** INCOMPLETE_FLOW, MISSING_VALIDATION
-- **Rate:** 10/min
-
-### check_injection
-- **Input:** `{ sinks: string[], sources: string[], sanitizers?: string[] }`
-- **Output:** `{ injectionPoints: InjectionPoint[], severity: Severity, fix: string }`
-- **Errors:** UNREACHABLE_SINK, FALSE_POSITIVE
-- **Rate:** 15/min
-
-### assess_dependencies
-- **Input:** `{ dependencies: Dependency[], ecosystem: string, severityThreshold: string }`
-- **Output:** `{ cves: CVE[], upgrades: UpgradeRecommendation[], sbom: SBOM }`
-- **Errors:** UNKNOWN_PACKAGE, RATE_LIMITED
-- **Rate:** 5/min
-
-## Parallel Execution
-
-When auditing code or reviewing changes, these checks run in parallel:
-
-- **Secrets scan** (always runs — fast, non-blocking)
-- **Auth/authorization audit** (if auth logic, JWT, sessions touched)
-- **Injection path analysis** (if user input reaches sinks)
-- **Data exposure check** (if logging, errors, APIs return data)
-- **Dependency CVE scan** (if package.json or lock files changed)
-
-All checks are independent — run concurrently and aggregate findings.
-
-### Execution Pattern
-```javascript
-// Parallel security checks
-const [secrets, auth, injection, exposure, deps] = await Promise.all([
-  scan_secrets({ files }),
-  audit_auth({ authFlow }),
-  check_injection({ sinks, sources }),
-  assess_data_exposure({ logs, errors }),
-  assess_dependencies({ dependencies })
-]);
-```
+## Parallel audit discipline
+
+Run these checks concurrently — they are independent and can be grep-driven in parallel:
+
+- **Secrets scan** (always — fast, covers all files in scope)
+- **Auth/authorization audit** (if auth logic, JWT, sessions, or privilege paths touched)
+- **Injection path analysis** (if user input reaches sinks — exec, eval, query, template)
+- **Data exposure check** (if logging, error responses, or APIs return data)
+- **Dependency CVE scan** (if package.json or lock files changed — delegate to cx-researcher for CVE lookups)
+
+Aggregate findings by severity before reporting. Do not report each category separately.
 
 ## Learning Capture
 

package/agents/prompts/cx-sre.md

@@ -25,49 +25,15 @@ RUNBOOK for each alert:
 
 Review code changes for: missing error handling on request paths, N+1 queries, unbounded operations, missing timeouts, operations that don't degrade gracefully.
 
-## Tool Contracts
-
-### define_slo
-- **Input:** `{ service: string, metric: string, measurementMethod: string, target: number }`
-- **Output:** `{ slo: SLO, errorBudget: number, alertThreshold: number, dashboard: DashboardConfig }`
-- **Errors:** INVALID_METRIC, UNMEASURABLE_TARGET
-- **Rate:** 10/min
-
-### create_runbook
-- **Input:** `{ alertName: string, triggerCondition: string, triageSteps: Step[] }`
-- **Output:** `{ runbook: Runbook, escalationPath: string[], rollbackProcedure: Rollback }`
-- **Errors:** MISSING_TRIGGER, INCOMPLETE_TRIAGE
-- **Rate:** 10/min
-
-### review_reliability
-- **Input:** `{ codeChanges: Diff[], statefulOps: boolean, degradationPlan?: string }`
-- **Output:** `{ findings: ReliabilityFinding[], missingAlerts: string[], rollbackGaps: string[] }`
-- **Errors:** MISSING_DEGRADATION_PLAN, UNBOUNDED_OPERATION
-- **Rate:** 15/min
-
-## Parallel Execution
-
-When reviewing changes for production readiness, these checks run in parallel:
-
-- **SLO definition check** (if new service or changed behavior)
-- **Alerting coverage** (if error paths or failure modes exist)
-- **Rollback procedure** (if stateful or irreversible operation)
-- **Error handling audit** (if request paths or external calls)
-- **Resource limits** (if N+1 queries, unbounded operations, missing timeouts)
-
-All checks are independent — run concurrently and aggregate findings.
-
-### Execution Pattern
-```javascript
-// Parallel SRE checks
-const [slo, alerts, rollback, errors, resources] = await Promise.all([
-  define_slo({ service, metric, target }),
-  check_alerting_coverage({ failureModes }),
-  verify_rollback({ statefulOps }),
-  audit_error_handling({ requestPaths }),
-  check_resource_limits({ queries, operations })
-]);
-```
+## Production readiness checklist
+
+For each change review, check these independently and aggregate before reporting:
+
+- **SLO definition** — is there a measurable target with an error budget for this service or behavior?
+- **Alerting coverage** — is every meaningful failure mode covered by an alert with a runbook?
+- **Rollback procedure** — is there a tested, documented path back from this change?
+- **Error handling** — do request paths and external calls fail gracefully and within timeouts?
+- **Resource bounds** — are there N+1 queries, unbounded loops, or missing timeouts?
 
 ## Learning Capture
 

package/agents/prompts/cx-ux-researcher.md

@@ -14,6 +14,7 @@ You have watched enough users fail to know that what they say they want and what
 **Failure mode warning**: If your brief has no friction points, you haven't talked to users. Every product has places where users get stuck.
 
 **Role guidance**: call `get_skill("roles/researcher.ux")` before drafting.
+**Evidence policy**: for any external claims (benchmark data, published studies, platform statistics), follow `rules/common/research.md` — most-recent-first, primary sources, verified URLs. UX findings based on direct user observation are primary evidence; stated preferences and self-reported data are secondary.
 
 Produce a UX brief:
 

package/agents/role-manifests.json

@@ -125,7 +125,7 @@
       "events": ["handoff.received", "backlog.stale", "prd.requested"],
       "severityImmediate": [],
       "fence": {
-        "allowedPaths": ["docs/prd/**", "docs/meta-prd/**", "docs/prfaq/**", "docs/one-pager/**", ".cx/product-intel/**"],
+        "allowedPaths": ["docs/prd/**", "docs/meta-prd/**", "docs/prfaq/**", "docs/one-pager/**", ".cx/knowledge/**"],
         "allowedBdLabels": ["product", "prd", "backlog", "feature"],
         "allowedCommands": ["bd create", "bd note", "bd update", "bd label", "bd priority"],
         "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**"]
@@ -192,7 +192,7 @@
     "trace-reviewer": { "events": ["handoff.received", "trace.anomaly"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/traces/**", ".cx/traces/**"], "allowedBdLabels": ["trace", "observability"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["trace"], "docTypes": ["memo"] }, "handoffCandidates": ["sre", "ai-engineer", "engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_TRACE_REVIEWER" },
     "test-automation": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["tests/**", "docs/test-automation/**"], "allowedBdLabels": ["test-automation", "ci", "test-infra"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**"] }, "outputs": { "bdLabels": ["test-automation"], "docTypes": ["memo"] }, "handoffCandidates": ["qa", "engineer", "platform-engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_TEST_AUTOMATION" },
     "ai-engineer": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/ai/**", "docs/agents/**", "agents/**", "skills/ai/**"], "allowedBdLabels": ["ai", "agent", "model"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**"] }, "outputs": { "bdLabels": ["ai"], "docTypes": ["memo"] }, "handoffCandidates": ["engineer", "architect", "evaluator"], "killSwitchEnv": "CONSTRUCT_ROLE_AI_ENGINEER" },
-    "business-strategist": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/strategy/**", ".cx/strategy/**"], "allowedBdLabels": ["strategy", "business"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["strategy"], "docTypes": ["memo"] }, "handoffCandidates": ["product-manager", "researcher"], "killSwitchEnv": "CONSTRUCT_ROLE_BUSINESS_STRATEGIST" },
+    "business-strategist": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/strategy/**", ".cx/knowledge/decisions/strategy/**"], "allowedBdLabels": ["strategy", "business"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["strategy"], "docTypes": ["memo", "strategy"] }, "handoffCandidates": ["product-manager", "researcher"], "killSwitchEnv": "CONSTRUCT_ROLE_BUSINESS_STRATEGIST" },
     "researcher": {
       "events": ["handoff.received", "research.requested", "evidence.requested"],
       "severityImmediate": [],
@@ -209,9 +209,9 @@
     "ux-researcher": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/ux-research/**", ".cx/ux-research/**"], "allowedBdLabels": ["ux-research", "user-research"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["ux-research"], "docTypes": ["memo"] }, "handoffCandidates": ["product-manager", "designer", "researcher"], "killSwitchEnv": "CONSTRUCT_ROLE_UX_RESEARCHER" },
     "explorer": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/explorations/**", ".cx/explorations/**"], "allowedBdLabels": ["exploration", "spike"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["exploration"], "docTypes": ["memo"] }, "handoffCandidates": ["engineer", "architect", "researcher"], "killSwitchEnv": "CONSTRUCT_ROLE_EXPLORER" },
     "operations": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/ops/**", "docs/operations/**"], "allowedBdLabels": ["ops", "operations"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["ops"], "docTypes": ["memo", "runbook"] }, "handoffCandidates": ["sre", "platform-engineer", "release-manager"], "killSwitchEnv": "CONSTRUCT_ROLE_OPERATIONS" },
-    "orchestrator": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/orchestration/**", "docs/workflows/**"], "allowedBdLabels": ["orchestration", "workflow"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["orchestration"], "docTypes": ["memo"] }, "handoffCandidates": ["product-manager", "architect", "engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_ORCHESTRATOR" },
+    "orchestrator": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/**", "plan.md", ".cx/context.md"], "allowedBdLabels": ["orchestration", "workflow", "dispatch"], "allowedCommands": ["bd create", "bd note", "bd update", "bd label", "bd link"], "approvalRequired": ["commit", "push", "edit:lib/**", "edit:bin/**", "edit:agents/**"] }, "outputs": { "bdLabels": ["orchestration", "dispatch"], "docTypes": ["memo"] }, "handoffCandidates": ["product-manager", "architect", "engineer", "security", "qa", "sre"], "killSwitchEnv": "CONSTRUCT_ROLE_ORCHESTRATOR" },
     "rd-lead": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/research/**", "docs/experiments/**", ".cx/experiments/**"], "allowedBdLabels": ["rd", "research", "experiment"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["rd"], "docTypes": ["memo", "research-brief"] }, "handoffCandidates": ["researcher", "architect", "ai-engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_RD_LEAD" },
-    "legal-compliance": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/legal/**", "docs/compliance/**"], "allowedBdLabels": ["legal", "compliance", "privacy"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["legal", "compliance"], "docTypes": ["memo"] }, "handoffCandidates": ["security", "product-manager"], "killSwitchEnv": "CONSTRUCT_ROLE_LEGAL_COMPLIANCE" },
+    "legal-compliance": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/legal/**", "docs/compliance/**", "docs/security/**", ".cx/knowledge/**"], "allowedBdLabels": ["legal", "compliance", "privacy"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["legal", "compliance"], "docTypes": ["memo"] }, "handoffCandidates": ["security", "product-manager"], "killSwitchEnv": "CONSTRUCT_ROLE_LEGAL_COMPLIANCE" },
     "devil-advocate": { "events": ["handoff.received"], "severityImmediate": [], "fence": { "allowedPaths": ["docs/critiques/**"], "allowedBdLabels": ["critique", "devil-advocate"], "allowedCommands": ["bd create", "bd note", "bd update"], "approvalRequired": ["commit", "push", "edit:**"] }, "outputs": { "bdLabels": ["critique"], "docTypes": ["memo"] }, "handoffCandidates": ["architect", "product-manager", "engineer"], "killSwitchEnv": "CONSTRUCT_ROLE_DEVIL_ADVOCATE" }
   }
 }

package/bin/construct

@@ -130,7 +130,7 @@ function usage() {
 
 /** Show interactive context-aware menu when construct is run without arguments. */
 async function showInteractiveMenu() {
-  const { loadProjectConfig } = await import('./lib/config/project-config.mjs');
+  const { loadProjectConfig } = await import('../lib/config/project-config.mjs');
   const { existsSync } = await import('node:fs');
   const { join } = await import('node:path');
   
@@ -142,7 +142,7 @@ async function showInteractiveMenu() {
   println('');
   
   if (isConstructProject) {
-    const projectName = process.env.CX_PROJECT_NAME || require('path').basename(projectRoot);
+    const projectName = process.env.CX_PROJECT_NAME || path.basename(projectRoot);
     println(`${COLORS.dim}Project:${COLORS.reset} ${projectName}`);
     println('');
   }
@@ -160,7 +160,7 @@ async function showInteractiveMenu() {
   
   // Show context-aware suggestions
   if (isConstructProject) {
-    const { readDashboardState } = await import('./lib/service-manager.mjs');
+    const { readDashboardState } = await import('../lib/service-manager.mjs');
     const dashboard = readDashboardState(HOME);
     
     if (!dashboard) {
@@ -288,12 +288,12 @@ async function cmdDoctor() {
     for (const varName of vars) {
       const sources = [];
 
-      // 1. process.env
+      // process.env
       if (process.env[varName]) {
         sources.push(`process.env (${process.env[varName].slice(0, 8)}…)`);
       }
 
-      // 2. .env files
+      // .env files
       for (const envPath of [join(process.cwd(), '.env'), join(homedir(), '.env'), join(homedir(), '.construct', 'config.env')]) {
         if (fs.existsSync(envPath)) {
           try {
@@ -304,7 +304,7 @@ async function cmdDoctor() {
         }
       }
 
-      // 3. Shell rc files
+      // Shell rc files
       const shellFiles = [join(homedir(), '.zshrc'), join(homedir(), '.bashrc'), join(homedir(), '.bash_profile'), join(homedir(), '.profile')];
       for (const rcPath of shellFiles) {
         if (!fs.existsSync(rcPath)) continue;
@@ -421,6 +421,22 @@ async function cmdDoctor() {
   add('Claude Code agents dir', fs.existsSync(path.join(HOME, '.claude', 'agents')), true);
   add('Codex agents dir', fs.existsSync(path.join(HOME, '.codex', 'agents')), true);
   add('Copilot prompts dir', fs.existsSync(path.join(HOME, '.github', 'prompts')), true);
+  add('Cursor MCP config', fs.existsSync(path.join(HOME, '.cursor', 'mcp.json')), true);
+  const vscodeSettingsPaths = process.platform === 'darwin'
+    ? [
+        path.join(HOME, 'Library', 'Application Support', 'Code', 'User', 'settings.json'),
+        path.join(HOME, 'Library', 'Application Support', 'Code - Insiders', 'User', 'settings.json'),
+      ]
+    : process.platform === 'linux'
+      ? [
+          path.join(HOME, '.config', 'Code', 'User', 'settings.json'),
+          path.join(HOME, '.config', 'Code - Insiders', 'User', 'settings.json'),
+        ]
+      : [
+          path.join(process.env.APPDATA ?? path.join(HOME, 'AppData', 'Roaming'), 'Code', 'User', 'settings.json'),
+          path.join(process.env.APPDATA ?? path.join(HOME, 'AppData', 'Roaming'), 'Code - Insiders', 'User', 'settings.json'),
+        ];
+  add('VS Code settings file', vscodeSettingsPaths.some((candidate) => fs.existsSync(candidate)), true);
   add('User config ready', fs.existsSync(getUserEnvPath(HOME)) || fs.existsSync(path.join(HOME, '.construct')), true);
   add('skills/ directory', fs.existsSync(path.join(ROOT_DIR, 'skills')));
   add('rules/common/', fs.existsSync(path.join(ROOT_DIR, 'rules', 'common')));
@@ -904,9 +920,9 @@ async function cmdUp() {
   if (embedConfigExists && autoEmbed) {
     try {
       const { runEmbedCli } = await import('../lib/embed/cli.mjs');
-      await runEmbedCli(['start']);
-    } catch {
-      // best effort
+      await runEmbedCli(['start'], { rootDir: ROOT_DIR });
+    } catch (err) {
+      warn(`embed start failed: ${err.message} — check ~/.cx/runtime/embed-daemon.log`);
     }
   }
 
@@ -1789,8 +1805,8 @@ async function cmdIntakeConfig(args) {
 async function cmdIntakeMetrics() {
   try {
     const { computeIntakeMetrics, pendingAge } = await import('../lib/embed/intake-metrics.mjs');
-    const metrics = computeIntakeMetrics({ rootDir: cwd });
-    const age = pendingAge({ rootDir: cwd });
+    const metrics = computeIntakeMetrics({ rootDir: process.cwd() });
+    const age = pendingAge({ rootDir: process.cwd() });
 
     println(`${COLORS.bold}Intake pipeline metrics:${COLORS.reset}`);
     println('');
@@ -2449,6 +2465,44 @@ async function cmdModels(args) {
     await cmdSync([]);
     return;
   }
+  if (args.includes('--cheapest')) {
+    const { selectCheapestProvider, rankConfiguredProvidersByCost, formatCheapestProviderMessage, isCheapestProviderEnabled } =
+      await import('../lib/model-cheapest-provider.mjs');
+    const cheapestTier = args.find((arg) => arg.startsWith('--tier='))?.split('=')[1] ?? 'standard';
+    const verbose = args.includes('--verbose');
+    const enabled = isCheapestProviderEnabled(envPath, { env: process.env });
+    const result = await selectCheapestProvider(cheapestTier, { env: process.env });
+    const msg = formatCheapestProviderMessage(result, { showRanking: verbose });
+    println(msg);
+    if (enabled) println('\nCheapest provider mode: enabled');
+    return;
+  }
+  if (args.includes('--apply-cheapest')) {
+    const { selectCheapestForAllTiers, setCheapestProviderPreference } =
+      await import('../lib/model-cheapest-provider.mjs');
+    const allTiers = args.includes('--all-tiers') || !args.find((arg) => arg.startsWith('--tier='));
+    const tierArg = args.find((arg) => arg.startsWith('--tier='))?.split('=')[1];
+    const tiers = allTiers ? ['reasoning', 'standard', 'fast'] : (tierArg ? [tierArg] : ['standard']);
+    const selections = {};
+    for (const currentTier of tiers) {
+      const { selectCheapestProvider } = await import('../lib/model-cheapest-provider.mjs');
+      const result = await selectCheapestProvider(currentTier, { env: process.env });
+      if (result.modelId) selections[currentTier] = result.modelId;
+    }
+    if (Object.keys(selections).length === 0) {
+      errorln('No configured providers found. Set API keys or install Ollama first.');
+      process.exit(1);
+    }
+    applyToEnv(envPath, selections);
+    println('Applying cheapest models:');
+    for (const [tier, model] of Object.entries(selections)) {
+      println(`  ${tier.padEnd(11)} ${model}`);
+    }
+    println('Written to ~/.construct/config.env. Running construct sync...');
+    setCheapestProviderPreference(envPath, true);
+    await cmdSync([]);
+    return;
+  }
   const registry = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'agents', 'registry.json'), 'utf8'));
   const result = readCurrentModels(envPath, registry.models ?? {});
   const nothingSelected = ['reasoning', 'standard', 'fast'].every((t) => !result[t]);
@@ -3796,6 +3850,13 @@ if (command === '--help' || command === '-h' || command === 'help') {
   process.exit(0);
 }
 
+// Version flags → print version and exit
+if (command === '--version' || command === '-V') {
+  const pkg = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'package.json'), 'utf8'));
+  println(`construct v${pkg.version}`);
+  process.exit(0);
+}
+
 const handler = handlers.get(command);
 if (!handler) {
   errorln(`Unknown command: ${command}`);

package/bin/construct-postinstall.mjs

@@ -6,7 +6,7 @@
  * and runs `npm install`, npm fetches Construct into the project's
  * `node_modules/` and then runs this script. Its job: regenerate the project's
  * `.claude/agents/` and `.claude/settings.json` from the bundled registry so
- * the project clone is fully runnable without a manual `construct setup`.
+ * the project clone is fully runnable without a manual `construct init`.
  *
  * The script is a no-op in three cases:
  *

package/db/schema/004_recommendations.sql

@@ -0,0 +1,46 @@
+-- 004_recommendations.sql — Recommendations table for team and enterprise mode.
+-- Solo mode uses the JSONL store under .cx/intake/ instead.
+--
+-- Dedup key is enforced at the (project, dedup_key) level — matches the in-memory
+-- dedup contract in lib/embed/recommendation-store.mjs.
+-- Active recommendations: dismissed_at IS NULL AND superseded_at IS NULL.
+
+create table if not exists construct_recommendations (
+  id text primary key,
+  project text not null,
+  dedup_key text not null,
+  type text not null,
+  title text not null,
+  reason text,
+  lane text,
+  signal_count int not null default 1,
+  total_signal_count int not null default 1,
+  customer_impact int not null default 0,
+  recency_bonus int not null default 0,
+  strategic_bonus int not null default 0,
+  score float not null default 0,
+  priority text not null default 'P3',
+  source_signal_ids jsonb not null default '[]'::jsonb,
+  first_seen timestamptz not null default now(),
+  last_seen timestamptz not null default now(),
+  dismissed_at timestamptz,
+  dismiss_reason text,
+  superseded_at timestamptz,
+  superseded_by_id text,
+  suppressed_until timestamptz,
+  suppress_reason text,
+  updated_at timestamptz not null default now()
+);
+
+create unique index if not exists construct_recommendations_project_dedup_key_idx
+  on construct_recommendations (project, dedup_key);
+
+create index if not exists construct_recommendations_priority_score_idx
+  on construct_recommendations (project, priority, score desc);
+
+create index if not exists construct_recommendations_last_seen_idx
+  on construct_recommendations (project, last_seen desc);
+
+create index if not exists construct_recommendations_active_idx
+  on construct_recommendations (project, dismissed_at)
+  where dismissed_at is null;

package/db/schema/005_strategy.sql

@@ -0,0 +1,21 @@
+-- 005_strategy.sql — Product strategy store for team and enterprise mode.
+-- Solo mode uses ~/.cx/strategy.md instead.
+--
+-- Each row is an immutable version snapshot. The latest version for a project
+-- is the row with the highest version number (or max updated_at when equal).
+-- Callers insert a new row on each write; old versions are retained for history.
+
+create table if not exists construct_strategy (
+  id bigserial primary key,
+  project text not null,
+  content text not null,
+  version int not null default 1,
+  updated_at timestamptz not null default now(),
+  updated_by text
+);
+
+create unique index if not exists construct_strategy_project_version_idx
+  on construct_strategy (project, version);
+
+create index if not exists construct_strategy_project_updated_at_idx
+  on construct_strategy (project, updated_at desc);

package/lib/auto-docs.mjs

@@ -88,7 +88,7 @@ const DIR_DESCRIPTIONS = {
   commands: 'Command prompt assets',
   codex: 'GitHub Copilot / Codex integration',
   docs: 'Architecture notes, runbooks, and documentation contract',
-  telemetry: 'Telemetry backend for agent observability',
+  telemetry: 'Local trace capture and optional telemetry export',
   lib: 'Core runtime: CLI, hooks, MCP, status, sync, workflow',
   opencode: 'OpenCode integration config',
   personas: 'Persona prompt definitions',
@@ -470,4 +470,3 @@ export function buildFumadocsReference({ rootDir } = {}) {
 
   return { written };
 }
-

package/lib/beads-automation.mjs

@@ -22,6 +22,11 @@ const HANDOFFS_DIR = '.cx/handoffs';
 const CONFIRM_TIMEOUT = 60000; // 60 second timeout for confirmation prompts
 const POSITIVE_INTENT = /^(y|yes|yeah|yep|yup|sure|ok|okay|go|proceed|do it)\b/i;
 
+function beadsConfirmEnabled(env = process.env) {
+  const raw = String(env.CONSTRUCT_BEADS_CONFIRM ?? '').trim().toLowerCase();
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+}
+
 // ---------------------------------------------------------------------------
 // Confirmation Utility
 // ---------------------------------------------------------------------------
@@ -148,14 +153,18 @@ export async function confirmAndCommit({
   }
   console.error('');
 
-  const confirmed = await confirm(
-    'Commit these changes?',
-    { yes, default: 'n' }
-  );
+  if (yes || beadsConfirmEnabled()) {
+    const confirmed = await confirm(
+      'Commit these changes?',
+      { yes, default: 'n' }
+    );
 
-  if (!confirmed) {
-    console.error('[beads] Commit cancelled');
-    return null;
+    if (!confirmed) {
+      console.error('[beads] Commit cancelled');
+      return null;
+    }
+  } else {
+    console.error('[beads] CONSTRUCT_BEADS_CONFIRM is off — committing without interactive prompt.');
   }
 
   runGit(['commit', '-m', message], { cwd });

package/lib/bootstrap/resources.mjs

@@ -15,7 +15,7 @@
  *   downloadSize  approximate install size in bytes (informational)
  *
  * The registry is consulted by:
- *   - `construct setup`         walks every resource, asks consent, installs
+ *   - `construct init`         walks every resource, asks consent, installs
  *   - `construct doctor --bootstrap`  re-probes every resource verbosely
  *   - lazy-install paths in hooks (consult the cached consent silently)
  *
@@ -114,7 +114,7 @@ export function formatProbe(probe) {
     ? `\n     fallback: ${probe.fallback}`
     : '';
   const install = !probe.present && probe.installable
-    ? `\n     installable via construct setup`
+    ? `\n     installable via construct init`
     : '';
   return `  ${status}  ${probe.displayName}${v}${loc}${detail}${fallback}${install}`;
 }