@geraldmaron/construct 1.0.21 → 1.0.24

package/specialists/registry.json

@@ -12,7 +12,8 @@
     "permissions": {
       "edit": "allow",
       "bash": "allow",
-      "webfetch": "allow"
+      "webfetch": "allow",
+      "websearch": "allow"
     },
     "claudeTools": "Read,Grep,Glob,LS,Edit,Write,Bash,WebSearch,WebFetch,summarize_diff,scan_file,project_context,memory_create_entities,list_skills,get_skill,search_skills,list_teams,get_team,memory_search,memory_add_observations,cx_trace,cx_score",
     "promptFile": "personas/construct.md",
@@ -417,7 +418,7 @@
       "modelTier": "standard",
       "reasoningEffort": "medium",
       "codexSandbox": "read-only",
-      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score",
+      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score,get_template,list_templates",
       "promptFile": "specialists/prompts/cx-evaluator.md",
       "embedOrientation": {
         "focusAreas": [
@@ -628,7 +629,7 @@
       "modelTier": "reasoning",
       "reasoningEffort": "high",
       "codexSandbox": "read-only",
-      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations",
+      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,get_template,list_templates",
       "promptFile": "specialists/prompts/cx-devil-advocate.md",
       "embedOrientation": {
         "focusAreas": [
@@ -673,7 +674,7 @@
       "modelTier": "reasoning",
       "reasoningEffort": "high",
       "codexSandbox": "read-only",
-      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score",
+      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score,get_template,list_templates",
       "promptFile": "specialists/prompts/cx-reviewer.md",
       "embedOrientation": {
         "focusAreas": [
@@ -716,7 +717,7 @@
       "modelTier": "reasoning",
       "reasoningEffort": "high",
       "codexSandbox": "read-only",
-      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score",
+      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score,get_template,list_templates",
       "promptFile": "specialists/prompts/cx-security.md",
       "embedOrientation": {
         "focusAreas": [
@@ -776,7 +777,7 @@
       "modelTier": "standard",
       "reasoningEffort": "medium",
       "codexSandbox": "workspace-write",
-      "claudeTools": "Read,Grep,Glob,LS,Edit,Write,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score",
+      "claudeTools": "Read,Grep,Glob,LS,Edit,Write,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score,get_template,list_templates",
       "promptFile": "specialists/prompts/cx-qa.md",
       "embedOrientation": {
         "focusAreas": [
@@ -824,7 +825,7 @@
       "modelTier": "reasoning",
       "reasoningEffort": "high",
       "codexSandbox": "workspace-write",
-      "claudeTools": "Read,Grep,Glob,LS,Bash,Edit,WebSearch,WebFetch,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score",
+      "claudeTools": "Read,Grep,Glob,LS,Bash,Edit,WebSearch,WebFetch,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score,get_template,list_templates",
       "promptFile": "specialists/prompts/cx-debugger.md",
       "embedOrientation": {
         "focusAreas": [
@@ -987,7 +988,7 @@
       "modelTier": "standard",
       "reasoningEffort": "medium",
       "codexSandbox": "read-only",
-      "claudeTools": "Read,Grep,Glob,LS,WebSearch,WebFetch,list_skills,get_skill,search_skills,memory_search,memory_add_observations",
+      "claudeTools": "Read,Grep,Glob,LS,WebSearch,WebFetch,list_skills,get_skill,search_skills,memory_search,memory_add_observations,get_template,list_templates",
       "promptFile": "specialists/prompts/cx-legal-compliance.md",
       "embedOrientation": {
         "focusAreas": [
@@ -1179,7 +1180,7 @@
       "modelTier": "standard",
       "reasoningEffort": "medium",
       "codexSandbox": "read-only",
-      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations",
+      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,get_template,list_templates",
       "promptFile": "specialists/prompts/cx-accessibility.md",
       "embedOrientation": {
         "focusAreas": [
@@ -1227,7 +1228,7 @@
       "modelTier": "fast",
       "reasoningEffort": "medium",
       "codexSandbox": "read-only",
-      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations",
+      "claudeTools": "Read,Grep,Glob,LS,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,get_template,list_templates",
       "promptFile": "specialists/prompts/cx-explorer.md",
       "embedOrientation": {
         "focusAreas": [
@@ -1266,7 +1267,7 @@
       "description": "Tracks fleet-level performance patterns — stable median scores can hide high-variance agents that are failing silently.",
       "modelTier": "reasoning",
       "reasoningEffort": "high",
-      "claudeTools": "Read,Write,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score",
+      "claudeTools": "Read,Write,Bash,list_skills,get_skill,search_skills,memory_search,memory_add_observations,cx_trace,cx_score,get_template,list_templates",
       "promptFile": "specialists/prompts/cx-trace-reviewer.md",
       "embedOrientation": {
         "focusAreas": [
@@ -1427,8 +1428,8 @@
       "options": {
         "baseURL": "https://openrouter.ai/api/v1",
         "headers": {
-          "HTTP-Referer": "__OPENROUTER_REFERER__",
-          "X-Title": "__OPENROUTER_TITLE__"
+          "HTTP-Referer": "https://github.com/geraldmaron/construct",
+          "X-Title": "Construct"
         }
       },
       "models": {
@@ -1462,23 +1463,15 @@
       "command": "npx",
       "args": [
         "-y",
-        "@upstash/context7-mcp@latest"
+        "@upstash/context7-mcp@3.1.0"
       ],
       "description": "Library and framework documentation lookup"
     },
-    "playwright": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@playwright/mcp@latest"
-      ],
-      "description": "Browser automation and E2E testing"
-    },
     "github": {
       "type": "url",
       "url": "https://api.githubcopilot.com/mcp/",
       "headers": {
-        "Authorization": "Bearer __GITHUB_TOKEN__"
+        "Authorization": "Bearer {env:GITHUB_TOKEN}"
       },
       "description": "GitHub API: issues, PRs, code search"
     },
@@ -1486,7 +1479,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@modelcontextprotocol/server-sequential-thinking"
+        "@modelcontextprotocol/server-sequential-thinking@2025.12.18"
       ],
       "description": "Complex multi-step reasoning chains"
     },
@@ -1500,17 +1493,18 @@
   },
   "sharedGuidance": [
     "Session Resumption: start every new chat by grounding in project_context, memory_search, AGENTS.md, plan.md, and the relevant repo docs. Apply results silently — never ask the user to repeat information that memory already holds.",
-    "Memory recording: after completing meaningful work, call memory_add_observations to record what you learned. Record: patterns discovered (category: pattern), decisions made with rationale (category: decision), anti-patterns found (category: anti-pattern), and open questions (category: insight). Summaries must be ≥30 characters and specific — avoid placeholders like 'task done' or 'completed'.",
-    "Project Identification: identify the current project from the workspace (basename of CWD) or memory MCP. Focus your expertise on the target repository you are currently in.",
-    "Loop guard: if you observe the same command or tool call being attempted more than 3 times with identical arguments and no state change, stop immediately and surface what blocked progress and what decision is needed.",
+    "Memory recording: after meaningful work, call memory_add_observations to record patterns, decisions with rationale, anti-patterns, and open questions. Summaries must be specific and ≥30 characters — avoid placeholders.",
+    "Project Identification: identify the current project from the workspace or memory MCP, and focus on that target repository.",
+    "Loop guard: if the same command or tool call is attempted 3+ times with identical arguments and no state change, stop and surface what blocked progress and what decision is needed.",
     "Circuit breaker: after 3 failed attempts at the same approach, stop all edits. Revert to last known working state. Document what was tried and escalate to the user with full context.",
-    "Worker task contract: specialists return exactly one terminal state: DONE (with files changed and verification evidence), BLOCKED (with concrete blocker and attempted steps), or NEEDS_MAIN_INPUT ({ taskKey, worker, blocker, question, safeDefault, context }). Never conduct user interviews from child sessions.",
-    "Tool naming contract: use the exact tool names exposed by the current host — never emit names from other vendors catalogs. Claude-trained models map edits→edit, writes→write, shell→bash. OpenAI-trained models map python/code interpreter→unavailable, shell→bash, apply_patch→edit/write. The bash tool requires both command and description string fields: {\"command\":\"...\",\"description\":\"why this command is needed\"}. Prefer rg over find/grep. If a needed tool is not listed, use the closest available primitive.",
-    "Observability: you MUST call cx_trace at the start of every new task using your agent name as the name field and the user goal as input. Construct attaches promptName/promptFile/promptHash automatically. If the tool is unavailable, log the failure and continue — telemetry must never block execution.",
-    "Quality scoring: after producing a significant deliverable, you MUST call cx_score with name=quality, value 0.0-1.0, and a brief comment explaining the score. Use the trace_id returned by cx_trace.",
-    "Model failover: if you hit a rate-limit error (HTTP 429), provider quota message, or model unavailability, the PostToolUseFailure hook may run construct models --apply. Surface whether fallback ran, then retry only after the model assignment changed.",
+    "Worker task contract: specialists return exactly one terminal state — DONE (files + verification), BLOCKED (blocker + attempts), or NEEDS_MAIN_INPUT (per the `construct-to-orchestrator` shape in specialists/contracts.json). Never interview the user from a child session.",
+    "Tool naming contract: use the exact tool names exposed by the current host; never emit names from other vendors' catalogs. The bash tool requires both command and description string fields. Prefer rg over find/grep. If a needed tool is missing, use the closest available primitive.",
+    "Observability: you MUST call cx_trace at the start of every new task with your agent name and the user goal. Construct attaches prompt provenance automatically. If the tool is unavailable, log and continue — telemetry must never block execution.",
+    "Quality scoring: after a significant deliverable, you MUST call cx_score with `name=quality`, a 0.0–1.0 value, a brief comment, and the `trace_id` returned by cx_trace.",
+    "Model failover: on rate-limit / quota / model-unavailability errors, the PostToolUseFailure hook may switch model assignments. Surface whether fallback ran; retry only after assignments changed.",
     "Detailed orchestration reference (execution contract, handoff template, intent/category classification, parallel dispatch, horizontal routing, efficiency discipline) is in skills/operating/orchestration-reference.md — call get_skill(\"operating/orchestration-reference\") when you need it.",
-    "Agent contracts: explicit producer→consumer service contracts live in specialists/contracts.json (loaded via lib/specialist-contracts.mjs). Call the agent_contract MCP tool at handoff time to look up input.mustContain, preconditions, output shape, and postconditions for the current pair. routeRequest returns contractChain alongside specialists."
+    "Agent contracts: typed producer→consumer contracts live in `specialists/contracts.json`. Call the `agent_contract` MCP tool at handoff to fetch the current shape; `routeRequest` returns `contractChain` alongside `specialists`.",
+    "Tool invisibility: a deliverable artifact is about the user's project, never about the tooling that produced it. In artifact content never name Construct, the `cx-*` specialist role ids, or internal orchestration mechanics (task-packets, orchestration_run, dispatch chains) — unless the subject project IS Construct itself. A metric owner is a real role on the user's team, never a `cx-*` id. Provenance goes in a comment or handoff, not the deliverable's prose. See rules/common/tool-invisibility.md."
   ],
   "platformGuidance": {
     "opencode": [
@@ -1519,9 +1513,7 @@
       "OpenCode subagents are not primary chat surfaces. If you are running as a subagent and you need user input, do not prompt the user from the child session. Return a concise NEEDS_MAIN_INPUT packet containing the blocker, exact question, safe default, and current task/session context so the primary persona can ask the user and resume.",
       "If a subagent returns NEEDS_MAIN_INPUT, the primary persona must ask the user in the main session, update the tracker or plan with the blocker, then resume or re-dispatch the specialist with the answer.",
       "Provider fallback is not guaranteed inside OpenCode provider/session failures. If you see a provider quota or usage-limit error, run or ask the main session to run `construct models --apply` after confirming an OpenRouter key is available, then retry after sync changes model assignments.",
-      "Use OpenCode's native plugin, agent, command, and hook surfaces as the orchestration substrate. Visible handoff blocks are fallback/debug artifacts, not the workflow itself.",
-      "Loop guard: if you observe the same command or tool call being attempted more than 3 times with identical arguments and no state change, stop immediately and surface what blocked progress.",
-      "If the memory MCP is available, call search_nodes with the current project name before starting work to retrieve prior session context."
+      "Use OpenCode's native plugin, agent, command, and hook surfaces as the orchestration substrate. Visible handoff blocks are fallback/debug artifacts, not the workflow itself."
     ],
     "claude": [
       "Follow workspace instructions, project-level CLAUDE.md, agent definitions in ~/.claude/specialists/, slash commands, and hooks. Project-level instructions override global ones.",

package/templates/distribution/run.mjs

@@ -14,30 +14,38 @@
  *      and the launcher invokes its `bin/construct`. Used for development
  *      and smoke tests; not consulted in normal runs.
  *
- *   1. Workspace `node_modules/@geraldmaron/construct/bin/construct` — if a
+ *   1. Self-repo — if this launcher is staged inside the Construct source
+ *      checkout itself (the project's own `package.json` is
+ *      `@geraldmaron/construct` and `bin/construct` is present), invoke that
+ *      `bin/construct` directly. Without this, the Construct repo's own hooks
+ *      would dead-end at npx/global resolution and fail every session.
+ *
+ *   2. Workspace `node_modules/@geraldmaron/construct/bin/construct` — if a
  *      `npm install` has materialised Construct in this project's node_modules,
  *      use that. Fastest, no network.
  *
- *   2. `npx -p @geraldmaron/construct@<version> construct …` — if Node ≥ 18
+ *   3. `npx -p @geraldmaron/construct@<version> construct …` — if Node ≥ 18
  *      is on PATH but the package isn't installed locally. npx caches the
  *      package after the first run. The version pin comes from
- *      `.construct/version` next to this file.
+ *      `.construct/version` next to this file. The pin is probed first; if it
+ *      cannot be resolved (offline, or the version is unpublished/yanked) the
+ *      launcher defers to the resolvers below instead of dead-ending here.
  *
- *   3. Globally installed `construct` on PATH — if neither of the above
+ *   4. Globally installed `construct` on PATH — if neither of the above
  *      hit but the user has installed Construct globally.
  *
- *   4. Cached binary at `.construct/cache/bin/construct-<os>-<arch>` — if
+ *   5. Cached binary at `.construct/cache/bin/construct-<os>-<arch>` — if
  *      a previous bootstrap downloaded the matching single-file binary
  *      from GitHub Releases.
  *
- *   5. Docker container — if the docker daemon is reachable, invoke
+ *   6. Docker container — if the docker daemon is reachable, invoke
  *      `ghcr.io/geraldmaron/construct:<pinned-version>` with the project
  *      bind-mounted at /work. Lets language-agnostic projects (no Node,
  *      no global construct, no binary) still execute hooks. Disable with
  *      `CONSTRUCT_DISABLE_DOCKER=1` for environments where docker is
  *      reachable but undesirable (e.g. CI runners that prefer fail-fast).
  *
- *   6. Print a precise error with the exact install commands and exit
+ *   7. Print a precise error with the exact install commands and exit
  *      with the documented exit code (127 = command not found).
  *
  * The launcher is intentionally tiny and dependency-free so it never
@@ -99,6 +107,18 @@ function tryDevPath() {
   return true;
 }
 
+function trySelfRepo() {
+  const candidate = join(PROJECT_ROOT, 'bin', 'construct');
+  if (!isExecutable(candidate)) return false;
+  let pkgName = null;
+  try {
+    pkgName = JSON.parse(readFileSync(join(PROJECT_ROOT, 'package.json'), 'utf8')).name;
+  } catch { return false; }
+  if (pkgName !== '@geraldmaron/construct') return false;
+  runForeground(process.execPath, [candidate, ...process.argv.slice(2)]);
+  return true;
+}
+
 function tryNodeModules() {
   const candidate = join(
     PROJECT_ROOT,
@@ -112,6 +132,14 @@ function tryNodeModules() {
 function tryNpx(version) {
   if (!commandOnPath('npx')) return false;
   const spec = version ? `@geraldmaron/construct@${version}` : '@geraldmaron/construct';
+
+  // npx exits non-zero when the pinned version is unpublished/yanked or the registry
+  // is unreachable. runForeground hands the process to npx and exits with its status,
+  // so that failure can never fall through to the global/cache/Docker resolvers below.
+  // Confirm the spec resolves first; on a miss, defer instead of dead-ending the chain.
+
+  const probe = spawnSync('npm', ['view', spec, 'version'], { stdio: 'ignore', timeout: 8000 });
+  if (probe.status !== 0) return false;
   runForeground('npx', ['-p', spec, '--', 'construct', ...process.argv.slice(2)]);
   return true;
 }
@@ -179,6 +207,7 @@ function fail() {
 const version = readPinnedVersion();
 
 if (tryDevPath()) { /* spawned */ }
+else if (trySelfRepo()) { /* spawned */ }
 else if (tryNodeModules()) { /* spawned */ }
 else if (tryNpx(version)) { /* spawned */ }
 else if (tryGlobal()) { /* spawned */ }

package/templates/docs/accessibility-audit.md

@@ -0,0 +1,56 @@
+# Accessibility Audit: {scope-title}
+
+- **Date**: {YYYY-MM-DD}
+- **Auditor**: cx-accessibility (or named human)
+- **Scope**: {pages / flows / components / PR}
+- **Baseline**: WCAG 2.1 AA (unless otherwise specified)
+- **Assistive technology used**: {VoiceOver / NVDA / JAWS / TalkBack / Switch Control / Voice Control / keyboard-only}
+- **Verdict**: ACCESSIBLE | ISSUES_FOUND | BLOCKED
+- **Status**: draft | final
+
+<!--
+Accessibility is measured by using the product, not reading the spec. Every finding cites a
+WCAG criterion AND a concrete repro step (keyboard sequence, screen-reader output,
+contrast measurement). A claim about assistive-tech behavior you didn't actually exercise
+is `unverified` — not a finding.
+-->
+
+## Flows tested
+<!-- The user flows actually walked through, end-to-end, with the assistive tech named above. A flow that wasn't walked isn't "passed"; it's "not tested." -->
+
+## Findings
+
+| WCAG Criterion | Severity | Element / Location | Repro Steps | Recommended Fix |
+|---|---|---|---|---|
+| {1.4.3 Contrast, 2.1.1 Keyboard, 4.1.2 Name/Role/Value, ...} | critical / high / medium / low | `{selector or path:line}` | {keystroke sequence + observed result} | {smallest change that restores compliance} |
+
+## High-impact areas
+
+- [ ] **Forms**: labels, error association, required-field signaling, autocomplete, focus management on validation
+- [ ] **Images and media**: alt text correctness, captions, transcripts, decorative-vs-informative classification
+- [ ] **Navigation**: keyboard order, skip links, landmarks, focus traps in modals
+- [ ] **Motion and animation**: prefers-reduced-motion honored, no flashing >3 Hz, no purely-motion conveyors of meaning
+- [ ] **Dynamic content**: live regions, status messages, async update announcements
+- [ ] **Color and contrast**: text contrast meets AA, meaning not carried by color alone
+- [ ] **Keyboard navigation**: every interactive element reachable and operable; no keyboard traps
+- [ ] **Screen reader**: every interactive element exposes a name, role, and value; relationships announced
+
+<!-- Tick what was actually exercised. An unticked box is "not audited," not "passed." -->
+
+## Contrast measurements
+<!-- Where contrast was checked, the measured ratio, the threshold, and pass / fail. Include the tool used (browser devtools, axe, manual measurement). -->
+
+## Keyboard navigation
+<!-- Sequence walked, traps found, focus-visible state. A keyboard audit that doesn't report focus indicators is incomplete. -->
+
+## Screen reader behavior
+<!-- For each non-trivial element: what was announced vs. what should have been. Quote the verbatim AT output where possible. -->
+
+## Out of scope
+<!-- Flows or surfaces not exercised. Future audits will need to cover them. -->
+
+## Handoff
+
+- design fixes → `next:cx-designer`
+- code fixes → `next:cx-engineer`
+- review of remediation → `next:cx-reviewer`

package/templates/docs/architecture-review.md

@@ -0,0 +1,59 @@
+# Architecture Review: {system-or-component}
+
+- **Date**: {YYYY-MM-DD}
+- **Reviewer**: cx-architect (or named human)
+- **Subject**: {existing design / proposed change / PR}
+- **Related**: {ADR, RFC, PRD ids — link the design this review evaluates}
+- **Verdict**: APPROVE | APPROVE_WITH_CONDITIONS | REJECT | NEEDS_REVISION
+- **Status**: draft | final
+
+<!--
+An architecture review evaluates an existing or proposed design — distinct from an ADR (a
+new decision record) or RFC (a proposal). Every concern cites the design property it
+violates and the failure mode it enables. "I don't like it" is not a concern; "this couples
+X and Y in a way that prevents Z" is.
+-->
+
+## Summary
+<!-- 2–4 sentences: what was reviewed, the top-level verdict, the single most important concern. -->
+
+## Design intent
+<!-- Restate what the design is trying to achieve, in the reviewer's words. If the design's intent can't be stated clearly from the artifact, that itself is a finding. -->
+
+## Trade-offs evaluated
+
+| Trade-off | Option chosen | Rationale | Cost | Reversibility |
+|---|---|---|---|---|
+| {axis — e.g. consistency vs. availability} | {what the design picked} | {why} | {what's given up} | reversible / costly to reverse / one-way door |
+
+## Interface contracts
+
+| Interface | Inputs | Outputs | Error cases | Backwards compatibility |
+|---|---|---|---|---|
+| `{name}` | {types / shapes} | {types / shapes} | {failure modes + retry semantics} | {breaking / non-breaking + version policy} |
+
+## Non-functional assessment
+
+- **Scalability**: {expected load → actual capacity, with bottleneck}
+- **Reliability**: {failure modes, blast radius, recovery}
+- **Observability**: {what is traced, what is alerted, what isn't and why}
+- **Security**: {trust boundaries, attack surface, sensitive data flow}
+- **Operability**: {who runs this, how do they intervene, what's the runbook}
+
+## Concerns
+
+| Severity | Concern | Property violated | Failure mode enabled | Recommended change |
+|---|---|---|---|---|
+| critical / high / medium / low | {one-line statement} | {the design property — e.g. "single-writer per partition"} | {what breaks when this is violated} | {smallest change that restores the property} |
+
+## Conditions for approval
+<!-- If APPROVE_WITH_CONDITIONS, the conditions go here. Each condition is verifiable; the verdict flips back to NEEDS_REVISION if any condition isn't met. -->
+
+## Rejected alternatives considered
+<!-- Designs evaluated but not chosen, with the reason. An ADR-worthy review names the alternatives the original artifact didn't consider. -->
+
+## Handoff
+
+- changes to implement → `next:cx-engineer` or `next:cx-platform-engineer`
+- ADR follow-up → `next:cx-architect` (capture the decision)
+- security re-review → `next:cx-security`

package/templates/docs/code-review-report.md

@@ -0,0 +1,46 @@
+# Code Review Report: {pr-title-or-bd-id}
+
+- **Date**: {YYYY-MM-DD}
+- **Reviewer**: cx-reviewer (or named human)
+- **Scope**: {files / commits / PR / bd-id}
+- **Verdict**: APPROVED | CHANGES_REQUESTED | BLOCKED
+- **Status**: draft | final
+
+<!--
+A review is not approval theater. Every finding cites file:line from the diff and a concrete
+failure scenario; severity is the impact, not the surface. Happy-path checks are not review.
+-->
+
+## Summary
+<!-- 2–4 sentences: what was reviewed, the top-level verdict, what most matters. Plain language. If there are no findings, say so explicitly. -->
+
+## Findings
+
+| Severity | File:Line | Issue | Recommended Fix |
+|---|---|---|---|
+| critical / high / medium / low / nit | `path/to/file.ext:NNN` | {what's wrong, with the failure mode it enables} | {smallest safe change, or "discuss"} |
+
+<!--
+Severity contract:
+  - critical: shipping this regresses correctness, security, or data integrity. Block.
+  - high: likely to cause defects in production within weeks. Fix before merge.
+  - medium: real risk under specific conditions. Fix before merge, or open a tracked follow-up.
+  - low: code-quality / maintainability cost. Optional.
+  - nit: cosmetic; reviewer preference. Always optional.
+-->
+
+## Conditions the author did not test for
+<!-- The point of review: name the inputs, states, and edge cases the diff doesn't account for. One bullet each, with file:line where the gap lives. -->
+
+## Required changes
+<!-- The minimum delta before this can merge. Empty if APPROVED. -->
+
+## Verification
+<!-- How a reviewer (or CI) would confirm the changes land safely. Reference the test name, the trace id, or the command that proves it. -->
+
+## Handoff
+<!-- Where this report goes next. Bare bd-label form so it works across hosts:
+  - findings to address → `next:cx-engineer`
+  - security concern → `next:cx-security`
+  - design / contract concern → `next:cx-architect`
+-->

package/templates/docs/construct_guide.md

@@ -14,22 +14,22 @@ You added Construct as a dev dependency. That gave you:
 
 You don't need to manage any of that: it all runs locally.
 
-## Files Construct created in your project
+## Files Construct created or manages
 
-You'll see these in `git status`:
+Generated tooling (`.construct/`, `.claude/`, `.cx/`, `plan.md`) is gitignored; the user-owned files (`AGENTS.md`, `docs/`) are the ones committed as project content.
 
 | Path | What it is | Touch? |
 |---|---|---|
-| `.construct/` | Launcher for hooks. Don't edit. Regenerated on `npm install`. | No |
-| `.claude/agents/` | The 29 persona definitions. Regenerated on `npm install`. | No |
-| `.claude/commands/` | Slash commands. Regenerated on `npm install`. | No |
-| `.claude/settings.json` | Hooks + MCP server config. Construct keys are managed; your additions are preserved. | Carefully |
-| `.cx/` | Per-project session state (active work, recent decisions). Construct writes here. | Read-mostly |
+| `.construct/` | Launcher for hooks. Don't edit. Regenerated on `npm install`. Gitignored. | No |
+| `.claude/agents/` | The persona definitions. Regenerated on `npm install`. Gitignored. | No |
+| `.claude/commands/` | Slash commands. Regenerated on `npm install`. Gitignored. | No |
+| `.claude/settings.json` | Hooks + MCP server config. Construct keys are managed; your additions are preserved. Gitignored. | Carefully |
+| `.cx/` | Per-project session state (active work, decisions, this guide). Construct writes here. Gitignored. | Read-mostly |
 | `.beads/` | Issue tracker data. Use `bd <cmd>` to interact. | Via CLI |
-| `AGENTS.md` | Operating rules the agent reads at session start. | Yes: your house rules go here |
+| `AGENTS.md` | Agent guide. Construct owns only its fenced integration block; the rest is yours. | Yes: your house rules go here |
 | `plan.md` | Active work plan. Local-only (gitignored). | Yes: your current focus |
 | `docs/` | Documentation lanes (ADRs, PRDs, memos, …). | Yes: this is your team's docs |
-| `construct_guide.md` | This file. Friendly orientation. | Yes: adapt to your team |
+| `.cx/construct_guide.md` | This file. Friendly orientation. Gitignored. | Yes: adapt to your team |
 
 ## Where to drop information you want Construct to use
 
@@ -67,7 +67,7 @@ The full list of personas lives in `.claude/agents/`. Run `construct list` to se
 
 Two scopes:
 
-**Per-project** (committed, shared with peers): edit `.claude/settings.json`. Construct owns the `hooks` block and a known set of `mcpServers` keys (memory, context7, playwright, github, sequential-thinking, construct-mcp); your additions are preserved on `npm install`. Other top-level keys are yours to control.
+**Per-project** (committed, shared with peers): edit `.claude/settings.json`. Construct owns the `hooks` block and a known set of `mcpServers` keys (memory, context7, github, sequential-thinking, construct-mcp); your additions — including opt-in MCPs like `playwright` (`construct mcp add playwright`) — are preserved on `npm install`. Other top-level keys are yours to control.
 
 **Per-machine** (private to you): edit `~/.construct/config.env`. This is where your API keys, consent flags, and local-service credentials live. Standard `KEY=value` format.
 
@@ -80,16 +80,15 @@ construct doctor             # verify everything's healthy
 
 ## Local services
 
-If you ran `construct init` and have Docker, you have three things running locally on Construct's reserved port block (`54329-54339`, chosen to avoid colliding with Next.js, Postgres, Redis, etc.):
+Once services are set up (`construct install`) and you have Docker, three things run locally. Ports are derived per home directory to avoid collisions, so run `construct status` for the live endpoints rather than assuming fixed numbers.
 
 **Telemetry backend** (LLM observability: see your traces, costs, and quality scores)
 
-- URL: <http://localhost:54330>
+- Dashboard URL: shown by `construct status`
 
 **Postgres + pgvector** (the database that backs hybrid retrieval)
 
-- URL: `postgresql://construct:construct@127.0.0.1:54329/construct`
-- Saved as `DATABASE_URL` in `~/.construct/config.env`
+- Connection string (`DATABASE_URL`): shown by `construct status`, saved in `~/.construct/config.env`
 
 **Vector storage** (semantic search over your project + ingested docs)
 
@@ -105,7 +104,8 @@ All ports bind to `127.0.0.1` only; nothing is reachable from other machines on
 
 | Command | What it does |
 |---|---|
-| `construct init` | One-time per-machine: spins up local services, writes config |
+| `construct install` | Machine setup, once per machine: Docker, local services, `~/.construct` config |
+| `construct init` | Project setup, once per repo: scaffold `.cx/`, AGENTS.md, plan.md, adapters |
 | `construct config [mode <m>]` | Show active deployment mode (solo / team / enterprise) or set a new one |
 | `construct doctor` | Health check across config, services, agents, hooks |
 | `construct sync` | Regenerate platform adapters (Claude Code, OpenCode, Codex, Cursor) |

package/templates/docs/debug-investigation.md

@@ -0,0 +1,53 @@
+# Debug Investigation: {symptom-or-bd-id}
+
+- **Date**: {YYYY-MM-DD}
+- **Debugger**: cx-debugger (or named human)
+- **Severity**: critical / high / medium / low
+- **Status**: in-progress | root-cause-identified | fix-proposed | resolved
+
+<!--
+The real bug is always one layer deeper than where it presents. Every diagnostic claim cites
+a stack trace, log line, test failure, or repro step. If the trace doesn't show the cause,
+the cause is `unknown` — not a guess.
+-->
+
+## Capture
+<!-- The exact error message, stack trace, log output, and repro steps as observed. Verbatim. Do not paraphrase or "clean up" the symptom. Include a path to the run log if one exists. -->
+
+## Reproduce
+<!-- The smallest deterministic recipe that triggers the symptom. Confirm the recipe reproduces on at least two runs. If you can't reproduce, the investigation isn't ready for a fix — say so. -->
+
+```
+{minimal repro: command, input, expected vs. actual output}
+```
+
+## Isolate
+<!-- Reduce the failing case until the smallest change toggles the bug. Cite the bisect range (`git bisect` boundary), the test that exhibits the failure, or the input dimension. -->
+
+## Trace
+<!-- The execution path from trigger to symptom. file:line citations for each hop. A trace without source pointers is a story, not a trace. -->
+
+| Hop | Location | Observation |
+|---|---|---|
+| {1, 2, 3...} | `path/to/file.ext:NNN` | {what the code does here that's relevant} |
+
+## Invariant violated
+<!-- One sentence: the property the system was supposed to uphold, and the specific way this run violated it. The invariant is the contract; the bug is the violation. -->
+
+## Root cause
+<!-- The system / design condition that lets the trigger cause harm. A root cause is a system gap, never a person and never a single line of code unless that line is the design decision. -->
+
+## Proposed fix
+<!-- The smallest safe change that restores the invariant. If the smallest change is large, the root cause is wider than originally thought — restate it. -->
+
+## Verification
+<!-- The specific run, test, or check that proves the fix works. The repro from above must now pass. Cite the test name and the trace id. -->
+
+## Follow-ups
+<!-- Adjacent issues surfaced during the investigation. Each gets a bd id, not a paragraph. -->
+
+## Handoff
+
+- fix to implement → `next:cx-engineer`
+- additional test coverage → `next:cx-qa`
+- design review of the invariant → `next:cx-architect`

package/templates/docs/qa-report.md

@@ -0,0 +1,48 @@
+# QA Report: {feature-or-bd-id}
+
+- **Date**: {YYYY-MM-DD}
+- **QA**: cx-qa (or named human)
+- **Scope**: {feature / PR / bd-id / acceptance-criteria source}
+- **Verdict**: PASS | FAIL | BLOCKED
+- **Status**: draft | final
+
+<!--
+Coverage is a hypothesis about quality, not proof of it. Every PASS / FAIL verdict cites the
+test name + run log line. Every coverage claim cites the report file. If a report isn't
+available, the verdict is `unknown` — not an estimate.
+-->
+
+## Acceptance criteria
+
+| Criterion | Verdict | Test name | Log line / artifact |
+|---|---|---|---|
+| {restated from the source — PRD, bd issue, design doc} | PASS / FAIL / unknown | `tests/path/to/test.mjs > "name"` | `{path or trace id}` |
+
+## Coverage
+
+| Layer | % | Source |
+|---|---|---|
+| Unit | {NN}% | `{coverage report path}` |
+| Integration | {NN}% | `{report or "not run"}` |
+| E2E | {NN}% | `{report or "not run"}` |
+
+## Test pyramid assessment
+<!-- Target ratio is unit:integration:E2E ≈ 70:20:10. Note the actual mix and the gap. Tests that exist but don't exercise the acceptance criterion are coverage without behavior — name them. -->
+
+## Findings
+
+| Test | Result | Log line / repro | Edge case it exercises |
+|---|---|---|---|
+| `{test name}` | PASS / FAIL / flaky | `{log line or repro steps}` | {what could break in production} |
+
+## Coverage gaps
+<!-- Acceptance criteria that lack a corresponding assertion, or assertions that don't exercise the acceptance criterion. Each gap names the missing test and what it should assert. -->
+
+## Determinism
+<!-- Tests that re-run with different results. Cite the run history (pass rate over N runs). A single failure is not flake; a single pass is not stable. -->
+
+## Handoff
+
+- test failures to fix → `next:cx-engineer`
+- root cause investigation → `next:cx-debugger`
+- flaky tests to stabilize → `next:cx-test-automation`