@geraldmaron/construct 1.1.1 → 1.2.1

package/personas/construct.md

@@ -25,7 +25,7 @@ Use the single-writer rule whenever multiple sessions are active: if two session
 
 ## Classify before acting <!-- cx:prio=1 -->
 
-Before any non-trivial request, CALL the code-backed orchestration policy via the `orchestration_policy` MCP tool with the request text and your `fileCount` / `moduleCount` / `introducesContract` estimate. Do not classify from memory. Honor the returned `track` and `specialists`. When `track` is `orchestrated` you may not author the deliverable yourself: emit the task-packet, dispatch the chain, return in Construct's voice after verdicts. Visual deliverables (wireframes, diagrams, decks) use real visual tools, not bullet prose.
+Before any non-trivial request, CALL the code-backed orchestration policy via the `orchestration_policy` MCP tool with the request text and your `fileCount` / `moduleCount` / `introducesContract` estimate. Do not classify from memory. Honor the returned `track` and `specialists`. When `track` is orchestrated, dispatch the chain — do not author the deliverable yourself.
 
 Tracks: immediate (act directly), focused (one bounded specialist), orchestrated (plan → challenge → build → validate, tracker-backed). cx-devil-advocate is mandatory whenever `riskFlags` include architecture, security, dataIntegrity, or ai.
 
@@ -36,7 +36,7 @@ Orchestrated dispatches emit a task-packet with `goal`, `intent`, `workCategory`
 `orchestration_policy` returns three artifacts; honor all three:
 
 1. **Gates**. `framingChallenge`, `externalResearch`, `docAuthoring`
-2. **Contract chain**. typed handoffs from `specialists/contracts.json`. Call `agent_contract` MCP tool at handoff.
+2. **Contract chain**. typed handoffs from `specialists/contracts.json`. Call `agent_contract` with `handoffPacket` from `orchestration_policy`.
 3. **Specialist sequence**. dispatch plan with ordering/parallel markers.
 
 Before DONE: postconditions met · sources cited · framing logged · ADRs have Rejected alternatives.

package/platforms/claude/settings.template.json

@@ -165,6 +165,30 @@
         "id": "post:edit:comment-lint",
         "description": "Block edits that violate comment policy (banned patterns, missing required header). No bypass — repair the policy if it fires wrong."
       },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/brand-prose-lint.mjs\"",
+            "timeout": 15
+          }
+        ],
+        "id": "post:edit:brand-prose-lint",
+        "description": "Block marketing voice, retired fonts, and Construct/cli naming drift in governed docs and templates."
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/artifact-release-gate.mjs\"",
+            "timeout": 15
+          }
+        ],
+        "id": "post:edit:artifact-release-gate",
+        "description": "Advisory: surface manifest structure/visual gaps on typed docs under docs/** and .cx/research/**"
+      },
       {
         "matcher": "Write|Edit|MultiEdit",
         "hooks": [
@@ -177,6 +201,18 @@
         "id": "post:edit:doc-coupling",
         "description": "Advisory: nudge when code edits accumulate without CHANGELOG/docs updates (pre-commit gate will block at commit time)"
       },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/graph-impact-advisory.mjs\"",
+            "timeout": 10
+          }
+        ],
+        "id": "post:edit:graph-impact",
+        "description": "Advisory: surface affected tests from the dependency graph after code edits"
+      },
       {
         "matcher": "Write|Edit|MultiEdit",
         "hooks": [

package/rules/common/patterns.md

@@ -6,7 +6,7 @@ description: reusable design patterns and skeleton project strategy.
 ## Skeleton Projects
 
 When implementing new functionality:
-1. Search for battle-tested skeleton projects
+1. Search for proven skeleton projects
 2. Evaluate options for security, extensibility, and relevance
 3. Clone best match as foundation
 4. Iterate within proven structure

package/rules/common/release-gates.md

@@ -7,7 +7,7 @@ These are blocking gates. Every agent, persona, and harness session working in o
 
 The goal is simple: if a gate would fail in CI, it fails locally first. We never push and pray.
 
-## The five local gates
+## The six local gates
 
 Run these before declaring work done. Pasting the output into the PR body or `bd note` is the standard evidence.
 
@@ -18,8 +18,9 @@ Run these before declaring work done. Pasting the output into the PR body or `bd
 | Doc verification | `node bin/construct docs:verify` | "All documentation checks passed": no warnings either |
 | AUTO doc drift | `node bin/construct docs:update --check` | "Docs are up to date" |
 | Template policy | `npm run lint:templates` | "Template policy: clean." |
+| Certification RC gate | `node bin/construct certify gate` | Release-critical capabilities are not stale; hermetic certification scenarios pass; skipped live runs do not satisfy evidence |
 
-The shortcut for all five (plus dashboard sync) is:
+The shortcut for all six (plus dashboard sync) is:
 
 ```bash
 npm run release:check
@@ -33,7 +34,7 @@ Commit subjects must match `type(scope): subject`: type from {feat, fix, refacto
 
 PR descriptions must keep all six headings (Summary, Beads issue, Doc updates included, Local gates, Test plan, Risks / rollback) with at least one checked box in both the "Doc updates" and "Local gates" sections. Empty templates fail.
 
-Forbidden in commit messages: `Co-Authored-By: Claude*` trailers (unless the user explicitly asks), `--no-verify`, `--no-gpg-sign`. Forbidden in PR bodies: deleting the required headings, leaving every gate box unchecked.
+Forbidden in commit messages: any `Co-Authored-By:` trailer (including Cursor agent attribution) unless the user explicitly asks, `--no-verify`, `--no-gpg-sign`. Forbidden in PR bodies: deleting the required headings, leaving every gate box unchecked.
 
 ## The tracker contract
 

package/scripts/sync-specialists.mjs

@@ -13,8 +13,8 @@
  *       global so hooks fire in every Claude Code session.
  *
  *   Project scope (`<project>/.claude/`, `<project>/.codex/`, `<project>/.github/`, …)
- *     - `construct` + all 28 `cx-*` specialists, slash commands, skills, MCP
- *       wiring. Files version with the repo and travel with teammates via git.
+ *     - `construct` front door only (Single Front Door), slash commands, skills, MCP
+ *       wiring. Specialists dispatch internally via orchestration MCP tools.
  *
  * Flags:
  *   --dry-run             Print a diff of what would change without writing anything.
@@ -56,6 +56,7 @@ import {
 } from "../lib/mcp-platform-config.mjs";
 import { loadConstructEnv } from "../lib/env-config.mjs";
 import { inlineRoleAntiPatterns, PROMPT_WORD_CAP } from "../lib/role-preload.mjs";
+import { inlineValidationContract } from "../lib/prompt-validation-contract.mjs";
 import { loadManifest } from "../lib/roles/manifest.mjs";
 import { resolveActiveProfile } from "../lib/profiles/loader.mjs";
 import { resolveTiersForPrimary, resolveCapabilityTier, selectLocalEditorModel } from "../lib/model-router.mjs";
@@ -154,6 +155,16 @@ if (validationErrors.length > 0) {
   }
 }
 
+{
+  const { validatePromptFiles } = await import("../lib/specialists/prompt-schema.mjs");
+  const promptResult = validatePromptFiles({ rootDir: root, registry });
+  if (promptResult.errors.length > 0) {
+    console.error("Specialist prompt validation failed:");
+    for (const err of promptResult.errors) console.error(`  - ${err}`);
+    process.exit(1);
+  }
+}
+
 // --- Dry-run + lockfile + two-phase write infrastructure ---
 
 const DRY_RUN = process.argv.includes("--dry-run");
@@ -518,10 +529,6 @@ function loadPersonaPrompt(persona) {
   return prompt;
 }
 
-export function buildAgentRoster(allEntries) {
-  return allEntries.map((e) => `- ${adapterName(e)}: ${e.when_to_use || e.description}`).join("\n");
-}
-
 function buildModelGuidanceBlock(entry) {
   const merged = { ...globalModelGuidance, ...(entry.modelGuidance ?? {}) };
   const families = Object.keys(merged);
@@ -675,7 +682,7 @@ function buildPrompt(entry, allEntries, platform, { capabilityTier = 'full' } =
 
   if (capabilityTier && capabilityTier !== 'full' && entry.promptFile) {
     let slim = renderPersonaForTier(readPromptBody(entry.promptFile, root), capabilityTier);
-    if (entry.injectAgentRoster && capabilities.hasNativeSubagents) {
+    if (entry.injectAgentRoster) {
       slim = `${ORCHESTRATION_MICRO_PROMPT}\n\n${slim}`;
     }
     return enforcePromptWordCap(slim, entry);
@@ -688,19 +695,17 @@ function buildPrompt(entry, allEntries, platform, { capabilityTier = 'full' } =
   }).prompt;
 
   prompt = inlineRoleAntiPatterns(prompt, root, entry.name, console.warn, { preload: entry.preloadRoleGuidance === true });
+  prompt = inlineValidationContract(prompt, root, entry.name);
 
-  // Platform-Native Orchestration Alignment (ADR-0002). Hosts with native subagent
-  // routing (OpenCode, VS Code, Cursor) do not get the static specialist roster
-  // injected — on a small-context local model the roster alone is ~3-4k tokens and,
-  // combined with MCP tool schemas, overruns the model's real context window and
-  // collapses output. Those hosts get a tool-bound micro-prompt instead and resolve
-  // the chain at runtime via the orchestration_policy MCP tool. Hosts without native
-  // routing (Claude Code, Codex) still need the roster to simulate handoffs in text.
-
-  if (entry.injectAgentRoster && allEntries && !capabilities.hasNativeSubagents) {
-    const roster = buildAgentRoster(allEntries);
-    prompt = `Available specialist agents:\n${roster}\n\n${prompt}`;
-  } else if (entry.injectAgentRoster && capabilities.hasNativeSubagents) {
+  // Platform-Native Orchestration Alignment (ADR-0002). All hosts receive the
+  // tool-bound micro-prompt when injectAgentRoster is set; the static 29-line
+  // roster was removed (construct-ymp5). Specialists resolve at runtime via
+  // orchestration_policy, which returns a lazy specialistCatalog.
+
+  // Single Front Door: all hosts resolve specialists at runtime via
+  // orchestration_policy / orchestration_run — never inject the static roster.
+
+  if (entry.injectAgentRoster) {
     prompt = `${ORCHESTRATION_MICRO_PROMPT}\n\n${prompt}`;
   }
 
@@ -1432,12 +1437,10 @@ function syncCursor(targetDir = null, wants = true) {
 
   if (targetDir) {
     const rulesPath = path.join(targetDir, ".cursor", "rules", "construct.mdc");
-    if (!fs.existsSync(rulesPath)) {
-      const body = `---\ndescription: Construct front-door — invoke \`construct\` for orchestration\nalwaysApply: false\n---\n\nThis project uses Construct (\`@geraldmaron/construct\`) as the single agent\nentry point. Route work through the \`construct\` persona; specialists are\ninternal and dispatched by Construct itself.\n\nSee \`.claude/agents/\` for the registered agents in this project.\n`;
-      if (!DRY_RUN) {
-        mkdirp(path.dirname(rulesPath));
-        fs.writeFileSync(rulesPath, body);
-      }
+    const body = `---\ndescription: Construct front-door — invoke \`construct\` for orchestration\nalwaysApply: false\n---\n\n<!-- Generated by construct sync — do not edit; re-run \`construct sync\` -->\n\nThis project uses Construct (\`@geraldmaron/construct\`) as the single agent\nentry point. Route work through the \`construct\` persona; specialists are\ninternal and dispatched via MCP \`orchestration_run\` (start \`construct dashboard\`).\n\nSkills load via MCP \`get_skill\`; see \`.claude/skills/\` for synced playbooks.\n`;
+    if (!DRY_RUN) {
+      mkdirp(path.dirname(rulesPath));
+      fs.writeFileSync(rulesPath, body);
     }
 
     // Glob-scoped language rules land as managed per-rule .mdc files only when
@@ -1646,7 +1649,8 @@ function syncOpencode(entries, targetDir = null, wants = true) {
       }
     }
 
-    // Heavy external MCP servers serialize ~12k tokens of schema into EVERY
+    // Heavy external MCP servers serialize a measured ~37k tokens of tool schema
+    // into EVERY agent's request — github ~30k alone (fixtures 2026-06-22) —
     // agent's request — including the built-in Build/Plan agents the per-agent
     // permission prune cannot reach. OpenCode 1.15.4 has no per-session tool
     // filter (chat.params carries no tool list), so disabling the whole server in
@@ -1774,13 +1778,22 @@ function syncOpencode(entries, targetDir = null, wants = true) {
   config.construct.models = { ...resolvedModels };
 
   // Seed a cheap auxiliary model for titles and summaries when the user has not
-  // chosen one — a cost lever only. The primary `model` stays the user's choice
-  // and is never written. Global scope only; project configs inherit it.
+  // chosen one — a cost lever only. Global scope only; project configs inherit it.
 
   if (!targetDir && config.small_model === undefined) {
     config.small_model = resolvedModels.fast || "anthropic/claude-haiku-4-5-20251001";
   }
 
+  // Seed a text-capable primary model when the user has not pinned one, so chat
+  // and routing never fall through to a host provider-default that happens to be
+  // an image/non-text model. Seeds only when absent; an explicit user choice is
+  // never overwritten. resolvedModels.standard is family-/registry-aware and
+  // free-biased. Global scope only; project configs inherit it.
+
+  if (!targetDir && (config.model === undefined || config.model === null || config.model === "")) {
+    config.model = resolvedModels.standard || resolvedModels.reasoning || resolvedModels.fast || "openrouter/qwen/qwen3-coder:free";
+  }
+
   writeOpenCodeConfig(config, configPath);
 
   const sourcePluginsDir = path.join(root, "platforms", "opencode", "plugins");

package/skills/devops/data-engineering.md

@@ -17,7 +17,7 @@ artifactType: data-pipeline
 
 ### ELT over ETL
 
-Modern data platforms (BigQuery, Snowflake, Redshift) are powerful enough to transform inside the warehouse. Prefer **ELT** (Extract → Load raw → Transform in warehouse):
+Modern data platforms (BigQuery, Snowflake, Redshift) are capable enough to transform inside the warehouse. Prefer **ELT** (Extract → Load raw → Transform in warehouse):
 
 ```
 Source → Airbyte/Fivetran → Raw tables → dbt models → Mart/API

package/skills/docs/adr-workflow.md

@@ -3,6 +3,7 @@ name: docs-adr-workflow
 description: "Use when: an architectural decision is made that affects the system structure, data model, API contracts, or technology choices."
 inputs: [decision-context]
 artifactType: adr
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # ADR Workflow
 

package/skills/docs/backlog-proposal-workflow.md

@@ -3,6 +3,7 @@ name: docs-backlog-proposal-workflow
 description: "Use when: product evidence should create or update Jira, Linear, GitHub Issues, or another tracker."
 inputs: [evidence-brief, prd, signal]
 artifactType: backlog-proposal
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Backlog Proposal Workflow
 

package/skills/docs/codebase-research-workflow.md

@@ -0,0 +1,40 @@
+---
+name: docs-codebase-research-workflow
+description: "Use when: cx-explorer maps the repo — entry points, dependencies, hot paths, or unfamiliar subsystems."
+inputs: [repository-path]
+artifactType: research-brief
+toneDefault: pedagogical
+toneAllowed: [pedagogical, direct]
+verificationBar: "Every claim cites file:line or command output; no assumed architecture."
+---
+# Codebase Research Workflow
+
+Use when: cx-explorer investigates **this repository** — structure, dependencies, behavior. Not for external vendor research or user interviews.
+
+Call `get_skill("roles/researcher.explorer")` and `get_skill("exploration/repo-map")` before deep dives.
+
+## Steps
+
+1. **Clarify the map question**: what subsystem, entry point, or data flow must be understood?
+2. **Read before concluding**: grep, glob, read implicated files. No claims from memory.
+3. **Produce artifacts**:
+   - `.cx/codebase-map.md` for broad orientation (repo-map skill)
+   - `.cx/research/{slug}.md` for focused investigations using `get_template("research-brief")`
+4. **Source classes** (codebase-primary):
+
+   | Source | Class |
+   |---|---|
+   | Source file at commit | primary |
+   | Test asserting behavior | primary |
+   | Config / schema in repo | primary |
+   | Comment or doc in repo | secondary |
+   | External blog about the repo | tertiary — locate code, do not cite alone |
+
+5. **Cite as** `[source: path#Lnn]` or `[source: commit-sha]`.
+6. **Tone**: default `pedagogical` — teach the next reader the shape of the system.
+
+## Verification bar
+
+- Every architectural claim traceable to file:line.
+- Unknown paths marked `[unverified]` until read.
+- cx-explorer must **not** answer product prioritization or user preference questions.

package/skills/docs/customer-profile-workflow.md

@@ -3,6 +3,7 @@ name: docs-customer-profile-workflow
 description: "Use when: customer evidence should update durable product memory."
 inputs: [signal, customer-profile]
 artifactType: customer-profile
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Customer Profile Workflow
 

package/skills/docs/document-ingest-workflow.md

@@ -3,6 +3,7 @@ name: docs-document-ingest-workflow
 description: "Use when: the user points at a PDF, Word doc, spreadsheet, slide deck, export, or mixed document folder and wants a markdown version that Construct can search efficiently later."
 inputs: [document]
 artifactType: ingested-markdown
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Document Ingest Workflow
 

package/skills/docs/evidence-ingest-workflow.md

@@ -3,6 +3,7 @@ name: docs-evidence-ingest-workflow
 description: "Use when: the user pastes customer notes, Slack threads, support tickets, sales notes, research snippets, RFCs, analytics summaries, or competitor signals."
 inputs: [signal, document]
 artifactType: evidence-brief
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Evidence Ingest Workflow
 

package/skills/docs/init-docs.md

@@ -46,7 +46,7 @@ docs/
 
 ## Interactive UX (TTY)
 
-When run interactively, `construct init-docs` renders a keyboard-driven **full-screen checkbox picker**: all available lanes listed with the default set pre-checked and context-suggested lanes highlighted in the UI. No typing required.
+When run interactively, `construct init --docs-preset=*` renders a keyboard-driven **full-screen checkbox picker**: all available lanes listed with the default set pre-checked and context-suggested lanes highlighted in the UI. No typing required.
 
 - **↑ / ↓**: move cursor (details shown in a dedicated panel)
 - **Space**: toggle lane on/off
@@ -54,7 +54,7 @@ When run interactively, `construct init-docs` renders a keyboard-driven **full-s
 - **Enter**: confirm and scaffold
 - Follow-up choices use the same menu pattern instead of free-text answers
 
-If the user selects the `intake` lane, `construct init-docs` should also create `.cx/inbox/`. Both `.cx/inbox/` and `docs/intake/` act as drop zones for ingestable files, while `docs/intake/` also serves as the durable paper trail lane.
+If the user selects the `intake` lane, `construct init` should also create `.cx/inbox/`. Both `.cx/inbox/` and `docs/intake/` act as drop zones for ingestable files, while `docs/intake/` also serves as the durable paper trail lane.
 
 When run non-interactively (`--yes` or piped stdin), the lean default set is used unless `--docs=` is supplied. `--docs=lean|product|full` or `--docs=adrs,prds,rfcs` both work.
 

package/skills/docs/init-project.md

@@ -10,9 +10,14 @@ Use when: starting work on a new project or joining an existing one without doc
 
 ## Command
 ```bash
-construct init-docs [path]   # defaults to current directory
+construct init --docs-preset=lean [path]   # defaults to current directory; presets: lean | product | full
+# or lane-specific init:
+construct init [path] [--docs-preset=lean|product|full]   # unified bootstrap (preferred)
+construct init --docs-preset=lean [path]                  # docs-only lean preset
 ```
 
+`npm run docs:init` is deprecated — use `construct init --docs-preset=*` instead.
+
 ## What it creates
 ```
 .cx/                    ← agent session memory and decisions
@@ -35,7 +40,7 @@ docs/                   ← human-readable project documentation
 4. Run `construct dashboard` to see the project in the dashboard.
 
 ## For cx-docs-keeper
-At session start, check the core docs set. If missing, suggest running `construct init-docs`.
+At session start, check the core docs set. If missing, suggest running `construct init --docs-preset=lean` (or `construct init --docs-preset=full` for the full lane set).
 At session end, update the affected core docs so the next LLM session inherits current project reality.
 
 ## For all LLMs working in the repo

package/skills/docs/prd-workflow.md

@@ -3,6 +3,7 @@ name: docs-prd-workflow
 description: "Use when: the user asks to create a PRD, platform spec, business case, RFC, or requirements document."
 inputs: [research-question, evidence-brief]
 artifactType: prd
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # PRD Workflow
 
@@ -10,6 +11,8 @@ Use when: the user asks to create a PRD, platform spec, business case, RFC, or r
 
 Choose the document type before drafting:
 
+Resolve tone from `specialists/tone-profiles.json` and optional `.cx/brand-voice.json` override for the selected template.
+
 | Template | Use when |
 |---|---|
 | `prd` | Customer-facing product capabilities, user workflows, end-user requirements |
@@ -36,7 +39,10 @@ Style constraint: do not produce a wall of bullets. Use paragraphs for reasoning
    | `meta-prd` | `docs/meta-prd/{YYYY-MM-DD}-{slug}.md` |
    | `rfc` | `docs/rfc/{YYYY-MM-DD}-{slug}.md` |
    | `rfc-platform` | `docs/rfc/{YYYY-MM-DD}-{slug}.md` |
-5. **cx-docs-keeper** updates `.cx/context.md` with a link to the PRD
+5. **cx-devil-advocate** runs the FMEA challenge pass (`roles/reviewer.devil-advocate`) on the draft; highest-RPN failure modes need a mitigation or explicit accept-with-rationale before ship. Their specialist id must appear in `.cx/agent-log.jsonl` (manifest `releaseGate.requiredReviewers` for PRD-family types).
+6. **cx-docs-keeper** updates `.cx/context.md` with a link to the PRD
+
+Run `construct artifact validate <path> --type=<type>` before marking the artifact approved.
 
 ## File naming
 - `docs/{template-type}/{YYYY-MM-DD}-{slug}.md`
@@ -54,3 +60,20 @@ Style constraint: do not produce a wall of bullets. Use paragraphs for reasoning
 ## After approval → beads
 
 Once the PRD is approved, run `/plan feature {feature-slug}` to produce a structured implementation plan and import it as workflow task packets (beads) into `.cx/workflow.json`. Link the resulting `.cx/plans/` file back in the PRD as the implementation reference.
+
+## Distribution (publish pipeline)
+
+**`construct workflow invoke` returns a plan only** — it does not draft the PRD. Run the listed specialists (cx-product-manager, cx-researcher, cx-ux-researcher as needed) to author the artifact from the template. **Do not hand-write a stub and publish.**
+
+Before distribution:
+
+```bash
+node bin/construct artifact validate docs/prd-platform/<slug>.md --type=prd-platform
+node bin/construct publish docs/prd-platform/<slug>.md --strict --figures
+```
+
+`construct publish` runs the artifact release gate by default. Thin or unscaffolded docs **exit 2** with remediation hints. Do not use `--no-gate` or `--no-strict` in demos or ship paths.
+
+**Presentation is part of done.** Published PDFs use type-specific Typst templates (`construct-prd.typ`, `construct-research.typ`, `construct-decision.typ`) with violet editorial branding and Inter body typography. Lead with an `::: executive-summary` narrative paragraph — not a bullet wall. Diagrams on the publish path use D2 `--sketch` and Mermaid `handDrawn` styling with Construct violet accent.
+
+`--strict` means **toolchain and release gate** both pass. Invoke alone is not "done."

package/skills/docs/prfaq-workflow.md

@@ -3,6 +3,7 @@ name: docs-prfaq-workflow
 description: "Use when: the user asks for a PRFAQ, working-backwards doc, launch narrative, or FAQ grounded in product evidence."
 inputs: [prd, evidence-brief]
 artifactType: prfaq
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # PRFAQ Workflow
 

package/skills/docs/product-intelligence-workflow.md

@@ -3,6 +3,7 @@ name: docs-product-intelligence-workflow
 description: "Use when: the request involves customer evidence, PM synthesis, product requirements, PRDs, PRFAQs, customer profiles, product signals, or backlog proposals."
 inputs: [signal, evidence-brief]
 artifactType: prd
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Product Intelligence Workflow
 

package/skills/docs/product-signal-workflow.md

@@ -3,6 +3,7 @@ name: docs-product-signal-workflow
 description: "Use when: the user asks what customers are asking for, what themes are emerging, whether evidence is strong enough, or what should become a PRD."
 inputs: [signal, evidence-brief]
 artifactType: signal-brief
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Product Signal Workflow
 

package/skills/docs/research-workflow.md

@@ -1,56 +1,73 @@
 ---
 name: docs-research-workflow
-description: "Use when: the user asks to research a topic, investigate a question, or gather evidence for a decision."
+description: "Use when: cx-researcher must investigate external facts — CVEs, APIs, market data, regulations, or vendor behavior."
 inputs: [research-question]
 artifactType: research-brief
+toneDefault: direct
+toneAllowed: [direct]
+verificationBar: "Every load-bearing claim cites a verifiable primary source; label inference confidence; satisfy template structure requirements."
 ---
-# Research Workflow
+# External Research Workflow
 
-Use when: the user asks to research a topic, investigate a question, or gather evidence for a decision.
+Use when: cx-researcher investigates **external** facts — not user interviews or codebase exploration. For user evidence use `docs/user-research-workflow`; for repo exploration use `docs/codebase-research-workflow`.
 
 Follow [rules/common/research.md](../../rules/common/research.md) as the default policy.
 
 ## Steps
 
 1. **Clarify the question**: one specific, falsifiable question the research must answer.
-2. **Apply recency discipline**: always search from the most recent year backward. For fast-moving domains (AI tools, security, market data), treat anything older than 12 months as presumptively stale unless a newer source confirms it is still accurate.
-3. **Check internal evidence first**: search `.cx/research/`, `.cx/knowledge/`, `docs/prd/`, `docs/meta-prd/`, ADRs, runbooks, and ingested artifacts before going external.
-4. **Choose the research path and starting point** by domain:
+2. **Apply recency discipline**: search from the most recent year backward. For fast-moving domains, treat sources older than 12 months as presumptively stale unless confirmed.
+3. **Check internal evidence first**: `.cx/research/`, `.cx/knowledge/`, PRDs, ADRs, runbooks before going external.
+4. **Choose authoritative starting points** (external primary only):
 
-   | Domain | Authoritative starting points |
+   | Domain | Starting points |
    |---|---|
-   | AI tools / LLM behavior / multi-agent | arXiv (cs.AI, cs.SE, cs.CL), ACL Anthology, conference proceedings (NeurIPS, ICML, ICLR, HICSS) |
-   | Developer tools / IDE / adoption | Stack Overflow Developer Survey, JetBrains Developer Ecosystem Report, GitHub blog, editor changelogs |
-   | Security / CVEs / supply chain | NVD, GitHub Security Advisories, OWASP, vendor security blogs (Google Project Zero, Microsoft Security), ProjectDiscovery |
-   | Market data / ARR / adoption | Primary company announcements, SEC filings, then TechCrunch/Bloomberg citing company sources |
-   | Cloud / API / SDK / version | Official vendor docs for exact version, changelog, migration guide |
-   | Regulatory / compliance / privacy | Primary regulation text, then official agency guidance |
-
-5. **Use a source hierarchy**:
-   - Primary: official docs, exact-version API references, standards, source code, peer-reviewed papers
-   - Secondary: changelogs, migration guides, maintainer issue comments, release notes
-   - Tertiary: blogs/forums/Q&A only to locate primaries: never cite tertiary alone for a load-bearing claim
-6. **Verify every URL**: fetch each URL cited and confirm it resolves and matches the cited claim. Mark unconfirmed URLs as `[unverified]`.
-7. **Structure findings** using the template from `get_template("research-brief")`: resolves `.cx/templates/docs/research-brief.md` (override) then `templates/docs/research-brief.md` (shipped)
-8. **Write to `.cx/research/{topic-slug}.md`**: cx-docs-keeper owns this
-9. **Reference the research doc** in the requesting agent's output (link by path)
+   | AI / LLM / multi-agent | arXiv, ACL Anthology, NeurIPS/ICML/ICLR proceedings |
+   | Security / CVEs | NVD, GitHub Security Advisories, OWASP, vendor security blogs |
+   | Market / adoption | SEC filings, company announcements, then analyst reports citing primaries |
+   | Cloud / API / SDK | Official vendor docs for exact version, changelog, migration guide |
+   | Regulatory | Primary regulation text, official agency guidance |
 
-## Verification bar
+5. **Source hierarchy**: primary → secondary → tertiary (tertiary never alone for load-bearing claims).
+6. **Verify every URL** before citing. Mark unconfirmed as `[unverified]`.
+7. **Tone**: resolve from artifact manifest (`direct`). See `specialists/tone-profiles.json`.
+8. **Structure** with `get_template("research-brief")`; write to `.cx/research/{topic-slug}.md`.
+9. **Reference** the research doc in the requesting agent's output.
+
+## Distribution (publish pipeline)
+
+After the brief is written, **validate then publish** — the release gate is enforced by default:
+
+```bash
+node bin/construct artifact validate .cx/research/{topic-slug}.md --type=research-brief
+node bin/construct tools detect --json
+node bin/construct publish .cx/research/{topic-slug}.md --strict \
+  --demo=resource-guard-rails \
+  --dashboard-demo=cockpit-tour
+```
+
+Do **not** publish without a passing validate. Do **not** use `--no-gate` in demos or ship paths.
 
-- Every load-bearing claim must cite a verified source path, URL, or document reference.
-- Record publication date, version, or access date for each source. If no date is available, state `[undated]` and treat confidence as `low`.
-- Fetch and confirm every URL before including it in a committed document.
-- Separate observation from inference: label each finding's confidence as `high`, `medium`, or `low`.
-- Name contradictions and unresolved gaps.
-- Prefer two independent sources per load-bearing claim unless one authoritative primary source is sufficient.
-- State the strongest counter-evidence when one exists.
+Optional frontmatter in the brief:
 
-## File naming
-- Topic slug: lowercase, hyphens, no spaces: e.g., `firebase-auth-v9-migration.md`
-- Date prefix for time-sensitive research: `2026-04-release-comparison.md`
+```yaml
+publish:
+  demo: resource-guard-rails
+  dashboardDemo: cockpit-tour
+```
 
-## When research feeds a decision
-→ Also create `.cx/decisions/ADR-{NNN}-{slug}.md` referencing the research doc
+**Community patterns (do not hand-roll):**
+
+- **Figures in PDF**: fenced ` ```d2` / ` ```mermaid` blocks rendered at export time via vendored [pandoc-ext/diagram](https://github.com/pandoc-ext/diagram) (`construct export --figures` or `construct publish`).
+- **Terminal demos**: shipped `.tape` files under `templates/demos/tapes/`; project overrides in `.cx/demos/tapes/`; regenerate with `construct demo record <name>` or CI `charmbracelet/vhs-action`.
+- **Dashboard demos**: Playwright `e2e/demo/*.spec.ts` with `video: on` in `apps/dashboard`; run via `construct demo dashboard:<name>`.
+
+Install toolchain once: `brew install d2 graphviz pandoc typst vhs` and `npm install -g @mermaid-js/mermaid-cli`. Playwright: `cd apps/dashboard && npm install && npx playwright install chromium`.
+
+Do **not** claim PDF/demo done until `construct tools detect` reports ready or `--strict` publish succeeds.
+
+## Verification bar
 
-## When research feeds a PRD
-→ Reference it in the PRD's References section
+- Two independent sources per load-bearing claim unless one authoritative primary suffices.
+- Admiralty grades on every source. Counter-evidence named when it exists.
+- cx-researcher must **not** answer UX preference questions or infer codebase behavior without reading code.

package/skills/docs/runbook-workflow.md

@@ -3,6 +3,7 @@ name: docs-runbook-workflow
 description: "Use when: creating operational procedures for services, alerts, or recurring operations."
 inputs: [service, incident]
 artifactType: runbook
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Runbook Workflow
 

package/skills/docs/strategy-workflow.md

@@ -3,6 +3,7 @@ name: docs-strategy-workflow
 description: "Use when: the user asks about product direction, strategic bets, what to prioritize, whether a signal aligns with strategy, or wants to update the strategy."
 inputs: [signal, decision-context]
 artifactType: strategy
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Strategy Workflow