@geraldmaron/construct 1.0.3 → 1.0.4

package/lib/worker/trace.mjs

@@ -7,16 +7,11 @@
  *
  *   1. `.cx/traces/<YYYY-MM-DD>.jsonl` — append-only local JSONL. Always on,
  *      no credentials required. Tail live, archive, or replay.
- *   2. Remote telemetry backend — fire-and-forget batched ingest when
- *      CONSTRUCT_TELEMETRY_PUBLIC_KEY + CONSTRUCT_TELEMETRY_SECRET_KEY are
- *      configured and CONSTRUCT_TRACE_BACKEND is `remote` (or unset).
- *      Each unique traceId triggers one trace-create plus an event-create
- *      per emitted event. Failures never throw — observability must not
+ *   2. Optional remote export — selected by CONSTRUCT_TRACE_BACKEND. Each
+ *      unique traceId triggers one trace-create plus an event-create per
+ *      emitted event. Failures never throw because observability must not
  *      break the caller.
  *
- *      Reads CONSTRUCT_TELEMETRY_PUBLIC_KEY / CONSTRUCT_TELEMETRY_SECRET_KEY /
- *      CONSTRUCT_TELEMETRY_URL from env.
- *
  * Event types in current use:
  *   intake.received        — daemon ingested a file
  *   intake.triaged         — classifyRdIntake produced a triage block
@@ -35,7 +30,7 @@ import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 
-import { createIngestClient } from '../telemetry/ingest.mjs';
+import { createTelemetryClient } from '../telemetry/client.mjs';
 
 const TRACE_SUBDIR = '.cx/traces';
 
@@ -73,23 +68,18 @@ export function newSpanId() {
   return `span-${randomBytes(6).toString('hex')}`;
 }
 
-// Reused per-process. The ingest client batches; recreating it would lose
-// the queue. `available` flips false when keys aren't set, which is the
-// graceful no-op path for solo-mode users without no telemetry backend configured.
+// Reused per-process. The adapter batches remote export; recreating it would
+// lose the queue. Local JSONL is already written by emitTraceEvent, so this
+// client disables its own local writer.
 let telemetryClient = null;
 const seenTraces = new Set();
 
-function getTelemetryClient(env = process.env) {
+function getTelemetryClient(env = process.env, rootDir) {
   if (telemetryClient !== null) return telemetryClient;
-  const backend = (env.CONSTRUCT_TRACE_BACKEND || 'remote').toLowerCase();
-  if (backend === 'none' || backend === 'off' || backend === 'local') {
-    telemetryClient = { available: false, trace: () => {}, event: () => {} };
-    return telemetryClient;
-  }
-  telemetryClient = createIngestClient({
-    baseUrl: (env.CONSTRUCT_TELEMETRY_URL ?? '').replace(/\/$/, ''),
-    publicKey: env.CONSTRUCT_TELEMETRY_PUBLIC_KEY,
-    secretKey: env.CONSTRUCT_TELEMETRY_SECRET_KEY,
+  telemetryClient = createTelemetryClient({
+    env,
+    rootDir,
+    localWrites: false,
   });
   return telemetryClient;
 }
@@ -103,9 +93,9 @@ export function _resetTelemetryClient() {
 }
 
 
-function exportToRemote(event, env) {
-  const client = getTelemetryClient(env);
-  if (!client.available) return;
+function exportToRemote(event, env, rootDir) {
+  const client = getTelemetryClient(env, rootDir);
+  if (!client.remoteAvailable) return;
 
   // First time we see a traceId, register the trace so subsequent events
   // attach to a known parent.
@@ -176,7 +166,7 @@ export function emitTraceEvent({
   };
   appendFileSync(path.join(dir, `${todayShard()}.jsonl`), `${JSON.stringify(event)}\n`, 'utf8');
 
-  // Fire-and-forget export to remote telemetry backend. Silent no-op when not configured.
-  exportToRemote(event, env);
+  // Fire-and-forget export to the configured remote adapter. Silent no-op when not configured.
+  exportToRemote(event, env, rootDir);
   return event;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
@@ -51,6 +51,8 @@
     "lint:templates": "node scripts/lint-commits-pr.mjs",
     "eval:routing": "node scripts/eval/score-intent-classifier.mjs",
     "release:check": "node ./bin/construct doctor && npm test && node ./bin/construct docs:update --check && node ./bin/construct dashboard:sync --check && node ./bin/construct lint:comments && node scripts/lint-commits-pr.mjs",
+    "release:preflight": "node scripts/pre-release-check.mjs",
+    "release:preflight:no-auth": "node scripts/pre-release-check.mjs --skip-auth",
     "npm:publish": "npm run release:check && npm publish --access public",
     "postinstall": "node ./bin/construct-postinstall.mjs"
   },
@@ -61,6 +63,7 @@
     "postgres": "^3.4.9"
   },
   "overrides": {
-    "express-rate-limit": "8.5.1"
+    "express-rate-limit": "8.5.1",
+    "protobufjs": "^8.4.2"
   }
 }

package/rules/common/research.md

@@ -10,7 +10,31 @@ that depends on external facts or evolving internal evidence.
 
 Construct treats research as a reproducible evidence-gathering process, not free-form browsing. If a claim could change decisions, scope, architecture, or roadmap, it must be tied to verifiable evidence.
 
-## 1. Start order
+## 1. Recency discipline
+
+Research always starts from the most recent available evidence.
+
+- Default to sources from the current year before earlier years — always search most-recent-first.
+- For fast-moving topics (AI tools, LLM behavior, cloud APIs, security advisories, market data), treat anything older than 12 months as presumptively stale unless a newer source confirms it is still accurate.
+- When using a search engine or index, always filter or sort by date — do not rely on relevance ranking alone.
+- State the publication or access date for every external source. If a source has no date, treat its confidence as `low` until recency is established another way.
+
+## 2. Domain-specific starting points
+
+Use the narrowest, most authoritative starting point for the research domain:
+
+| Domain | Starting points (most recent first) |
+|---|---|
+| AI tools, LLM behavior, multi-agent | arXiv (cs.AI, cs.SE, cs.CL), ACL Anthology, NeurIPS/ICML/ICLR proceedings, then vendor research blogs |
+| Developer tools, IDE, editor | Stack Overflow Developer Survey (current year), JetBrains Developer Survey, GitHub/Copilot blog, then product changelogs |
+| Security, CVEs, supply chain | NVD, GitHub Security Advisories, OWASP, vendor security blogs (Google Project Zero, Microsoft Security Response), then ProjectDiscovery/Snyk reports |
+| Market data, adoption, ARR | Primary company announcements or SEC filings, then TechCrunch/Bloomberg/WSJ (where citing company sources), then analyst reports |
+| Cloud infra, APIs, SDKs | Official vendor docs for the exact version, changelog, migration guides |
+| Regulatory, compliance, privacy | Primary regulation text, then official guidance from the issuing authority, then law firm analysis |
+
+Tertiary sources (blogs, forums, Q&A, AI-generated summaries) may help locate primaries. They are not sufficient evidence for load-bearing claims.
+
+## 3. Start order
 
 Start with the narrowest authoritative source that can answer the question:
 
@@ -28,9 +52,7 @@ Start with the narrowest authoritative source that can answer the question:
 4. **Tertiary sources last**
    - blogs, forums, Q&A, analyst summaries, AI-generated summaries
 
-Tertiary sources may help discover primary sources. They are not sufficient evidence for load-bearing claims.
-
-## 2. Required metadata for every source
+## 4. Required metadata for every source
 
 Record:
 
@@ -40,9 +62,16 @@ Record:
 - publication date, release date, or access date
 - why this source is relevant
 
-If a source has no date and the topic is time-sensitive, treat confidence as reduced until recency is established another way.
+## 5. URL verification
+
+Every URL cited in a committed document must be verified before the document is published.
+
+- Fetch the URL. Confirm it resolves and the content matches the cited claim.
+- Do not cite aggregate or index pages (e.g., arxiv.org search results, Google Scholar listings) for quantitative claims — cite the specific paper or article URL.
+- If a URL returns a 404, paywall, or redirect loop, find the canonical source or replace the citation.
+- Unverified URLs must be marked `[unverified]` until confirmed.
 
-## 3. Verification rules
+## 6. Verification rules
 
 For each load-bearing claim:
 
@@ -54,7 +83,7 @@ For each load-bearing claim:
 
 Claims about versions, APIs, security, pricing, compatibility, regulations, and timelines must cite the exact version/date basis.
 
-## 4. Reproducibility
+## 7. Reproducibility
 
 Research must be reproducible by another person in the repo.
 
@@ -67,7 +96,7 @@ Record:
 
 If you cannot explain how the answer was obtained, the research is incomplete.
 
-## 5. Evidence thresholds
+## 8. Evidence thresholds
 
 Recommendations must state what evidence threshold was used.
 
@@ -81,27 +110,30 @@ Examples:
 
 If the threshold is not met, the output should recommend more research, a weaker artifact, or a narrower decision.
 
-## 6. Output standard
+## 9. Output standard
 
 Research outputs should include:
 
 - question
 - method
-- sources
+- sources (with dates and classes)
 - findings
 - confidence
 - open questions
 - recommendation or next step
 
-Every substantive finding should point to a source path, URL, or document reference.
+Every substantive finding should point to a verified source path, URL, or document reference.
 
-## 7. Anti-patterns
+## 10. Anti-patterns
 
 Do not:
 
+- start research from older years when more-recent sources are available
 - stop at the first plausible answer
 - cite a blog when the spec or source code is available
+- cite an aggregate or index page when the specific document is available
 - present inference as if the source said it directly
 - ignore conflicting evidence
 - use stale undated material for fast-moving topics without saying so
 - promote weak product evidence into committed requirements
+- include URLs that have not been fetched and confirmed

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

@@ -8,8 +8,8 @@ Use when: product evidence should create or update Jira, Linear, GitHub Issues,
 ## Steps
 
 1. Load source evidence, evidence brief, PRD, or signal brief.
-2. Search existing tracker context if an MCP is configured; otherwise search local docs and product-intel artifacts.
-3. Create `.cx/product-intel/backlog-proposals/{date}-{slug}.md` with `get_template("backlog-proposal")`.
+2. Search existing tracker context if an MCP is configured; otherwise search local docs and knowledge artifacts.
+3. Create `.cx/knowledge/internal/backlog-proposals/{date}-{slug}.md` with `get_template("backlog-proposal")`.
 4. Include duplicate/conflict analysis and exact proposed writes.
 5. Return `NEEDS_MAIN_INPUT` for approval before any external write.
 6. After approval, apply changes and update the proposal's application log.

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

@@ -7,7 +7,7 @@ Use when: customer evidence should update durable product memory.
 
 ## Steps
 
-1. Load the existing customer profile from `.cx/product-intel/customer-profiles/` if present.
+1. Load the existing customer profile from `.cx/knowledge/internal/customer-profiles/` if present.
 2. Read the new source evidence.
 3. Add new facts, asks, pain points, contacts, product areas, and evidence links.
 4. Preserve historical entries. Do not delete or rewrite prior history without explicit approval.

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

@@ -1,5 +1,5 @@
 <!--
-skills/docs/evidence-ingest-workflow.md — Normalize raw product evidence into Construct product-intel artifacts.
+skills/docs/evidence-ingest-workflow.md — Normalize raw product evidence into Construct knowledge artifacts.
 -->
 # Evidence Ingest Workflow
 
@@ -11,9 +11,9 @@ Follow [rules/common/research.md](../../rules/common/research.md) for source met
 
 1. Identify the source type and date.
 2. Extract source metadata: customer, actor, product area, channel, linked issue, and confidence.
-3. Save raw or lightly normalized source material under `.cx/product-intel/sources/`.
-4. If customer-specific, update or create `.cx/product-intel/customer-profiles/{customer}.md` using `get_template("customer-profile")`.
-5. Create `.cx/product-intel/evidence-briefs/{date}-{slug}.md` using `get_template("evidence-brief")` when the evidence supports a product decision.
+3. Save raw or lightly normalized source material under `.cx/knowledge/internal/sources/`.
+4. If customer-specific, update or create `.cx/knowledge/internal/customer-profiles/{customer}.md` using `get_template("customer-profile")`.
+5. Create `.cx/knowledge/internal/evidence-briefs/{date}-{slug}.md` using `get_template("evidence-brief")` when the evidence supports a product decision.
 6. If evidence is weak but worth preserving, create a signal brief with `get_template("signal-brief")`.
 
 ## Rules
@@ -29,4 +29,4 @@ Always preserve:
 
 ## Storage
 
-Files in `.cx/product-intel/` are indexed by Construct's hybrid retrieval path. Postgres stores them as `product-intel` documents during sync, and the vector layer makes them semantically retrievable for future PRDs and Meta PRDs.
+Files in `.cx/knowledge/` are indexed by Construct's hybrid retrieval path. The vector layer makes them semantically retrievable for future PRDs and Meta PRDs.

package/skills/docs/prfaq-workflow.md

@@ -18,7 +18,7 @@ Use when: the user asks for a PRFAQ, working-backwards doc, launch narrative, or
 4. Write the press release in shipped-state language.
 5. Write external FAQ for customers and internal FAQ for engineering, sales, support, security, finance, and leadership.
 6. Include unknowns as `TBD` with what would resolve them.
-7. Save to `.cx/product-intel/prfaqs/` until approved.
+7. Save to `.cx/knowledge/internal/prfaqs/` until approved.
 
 ## Approval
 

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

@@ -14,7 +14,7 @@ Score each dimension as pass, warning, or fail:
 - Acceptance criteria: observable and pass/fail.
 - Scope discipline: goals, non-goals, and tradeoffs are explicit.
 - Approval safety: external writes and approved status are gated.
-- Storage readiness: artifact path is under `.cx/product-intel/`, `docs/prd/`, or `docs/meta-prd/` so hybrid retrieval can index it.
+- Storage readiness: artifact path is under `.cx/knowledge/`, `docs/prd/`, or `docs/meta-prd/` so hybrid retrieval can index it.
 - Readability: balanced paragraphs, tables, and bullets. Few em dashes.
 
 ## Output

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

@@ -14,7 +14,7 @@ Follow [rules/common/research.md](../../rules/common/research.md) for source ord
 
 Product Intelligence is a Construct-native loop:
 
-1. Capture evidence into `.cx/product-intel/sources/` or link existing sources.
+1. Capture evidence into `.cx/knowledge/internal/sources/` or link existing sources.
 2. Normalize evidence into field notes, customer profiles, and evidence briefs.
 3. Synthesize themes, asks, pain points, product areas, and confidence.
 4. Select the PM flavor: product, platform, enterprise, ai-product, or growth.
@@ -53,9 +53,9 @@ Load the core product-manager role guidance and the selected overlay before draf
 
 ## Storage
 
-Write working artifacts under `.cx/product-intel/` unless they are docs of record. Approved PRDs live in `docs/prd/`; approved Meta PRDs live in `docs/meta-prd/`.
+Write working artifacts under `.cx/knowledge/` unless they are docs of record. Approved PRDs live in `docs/prd/`; approved Meta PRDs live in `docs/meta-prd/`.
 
-The hybrid storage layer indexes `.cx/product-intel/`, `docs/prd/`, and `docs/meta-prd/`. When Postgres is configured, `construct storage sync` can persist these artifacts into shared SQL rows. The vector layer scores the same documents for local, remote, or file-backed semantic retrieval.
+The hybrid storage layer indexes `.cx/knowledge/`, `docs/prd/`, and `docs/meta-prd/`. When Postgres is configured, `construct storage sync` can persist these artifacts into shared SQL rows. The vector layer scores the same documents for local, remote, or file-backed semantic retrieval.
 
 ## Approval boundaries
 

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

@@ -1,31 +1,61 @@
 <!--
-skills/docs/product-signal-workflow.md — Synthesize product signals from evidence.
+skills/docs/product-signal-workflow.md — Synthesize product signals from evidence into the right artifact.
+Confidence rubric, contradiction resolution, artifact decision tree, and storage are all defined here.
+Follow rules/common/research.md for source-handling policy.
 -->
 # Product Signal Workflow
 
 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.
 
-Follow [rules/common/research.md](../../rules/common/research.md) for confidence, contradictions, and source handling.
+## Confidence Rubric
 
-## Steps
+| Level | Criteria |
+|---|---|
+| **high** | ≥ 3 independent customers mention the same problem verbatim, OR 1 enterprise blocker with revenue at risk named |
+| **medium** | 2 independent customers, OR 1 customer with high frequency (≥ 3 mentions), OR corroborated by a competitor signal |
+| **low** | 1 customer mention, OR internal opinion without user observation, OR inferred from adjacent evidence |
+
+## Contradiction Resolution
 
-1. Gather relevant evidence briefs, customer profiles, notes, tickets, research, and product docs.
-2. Group evidence into themes, asks, pain points, affected personas, product areas, and counter-signals.
-3. Assign confidence: high, medium, or low.
-4. Choose the next artifact:
-   - signal brief for weak or early evidence
-   - evidence brief for decision-ready synthesis
-   - PRD or PRFAQ for strong customer-facing product demand
-   - Meta PRD for operating-system or process changes
-   - backlog proposal for tracker changes after approval
-5. Store synthesis in `.cx/product-intel/signals/` or `.cx/product-intel/evidence-briefs/`.
+When two signals conflict:
+1. Name both signals explicitly — do not average them away.
+2. Weight by customer tier (enterprise > growth > SMB) and recency (weight decays after 90 days).
+3. Record the contradiction in the signal brief as an open question.
+4. Never let a minority signal disappear — it may be the leading indicator.
 
-## Evidence threshold
+## Artifact Decision Tree
 
-Default threshold for PRD-ready evidence: at least two independent customers, three independent mentions, one severe enterprise blocker, or a clear strategic mandate with named risk. If the threshold is not met, write a signal brief instead of inventing requirements.
+| Condition | Artifact |
+|---|---|
+| < 2 independent sources OR < medium confidence | signal brief |
+| ≥ 2 independent sources AND ≥ medium confidence AND no strategic mandate yet | evidence brief |
+| ≥ 3 sources OR 1 enterprise blocker OR PM has declared this a bet | PRD |
+| PRD is approved AND launch narrative needed | PRFAQ |
+| Subject is an internal process, agent workflow, or governance mechanism | Meta PRD |
+| Artifact is approved AND needs a tracker item | backlog proposal (requires approval gate) |
 
-## Quality bar
+## Strategy Check
 
-Separate asks from requirements. Separate observation from inference. Name what evidence would change the recommendation.
+After grouping evidence, check `.cx/knowledge/decisions/strategy/` for any declared strategy documents:
+- Signal aligns with a declared Bet → raise priority, note alignment explicitly.
+- Signal conflicts with a declared Non-bet → flag the conflict; the user must make an explicit override decision before proceeding.
+- No strategy documents exist → continue without blocking; note that strategy grounding is not available.
+
+## Steps
 
-When a claim depends on time-sensitive or external information, include the date or version basis. If evidence conflicts, state the counter-signal explicitly instead of averaging it away.
+1. **Gather** — collect evidence briefs, customer profiles, field notes, tickets, and research from `.cx/knowledge/` and linked sources.
+2. **Group** — cluster by theme, ask, pain point, affected persona, product area, and counter-signal.
+3. **Assign confidence** — apply the rubric above; separate observation from inference.
+4. **Check strategy** — check `.cx/knowledge/decisions/strategy/`; flag alignment or conflict with Bets and Non-bets if documents exist.
+5. **Select artifact** — apply the decision tree; write the artifact; store to the path below.
+
+## Storage
+
+| Artifact | Path |
+|---|---|
+| Signal brief | `.cx/knowledge/internal/signals/` |
+| Evidence brief | `.cx/knowledge/internal/evidence-briefs/` |
+| PRD | `docs/prd/` |
+| PRFAQ | `docs/prfaq/` |
+| Meta PRD | `docs/meta-prd/` |
+| Backlog proposal | pending approval gate — do not file until explicit user approval |

package/skills/docs/research-workflow.md

@@ -12,25 +12,37 @@ Follow [rules/common/research.md](../../rules/common/research.md) as the default
 ## Steps
 
 1. **Clarify the question** — one specific, falsifiable question the research must answer.
-2. **Check internal evidence first** — search `.cx/research/`, `.cx/product-intel/`, `docs/prd/`, `docs/meta-prd/`, ADRs, runbooks, and ingested artifacts before going external.
-3. **Choose the research path**:
-   - Library/API/framework/version questions → primary vendor docs, source code, changelogs, exact-version references
-   - Market, competitive, policy, or general evidence → cx-researcher using primary sources first
-4. **Use a source hierarchy**:
-   - Primary: official docs, exact-version API references, standards, source code
-   - Secondary: changelogs, migration guides, maintainer issue comments
-   - Tertiary: blogs/forums/Q&A only to locate primaries
-5. **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)
-6. **Write to `.cx/research/{topic-slug}.md`** — cx-docs-keeper owns this
-7. **Reference the research doc** in the requesting agent's output (link by path)
+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:
+
+   | Domain | Authoritative 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)
 
 ## Verification bar
 
-- Every load-bearing claim must cite a source path, URL, or document reference.
-- Record publication date, version, or access date for each source.
-- Separate observation from inference.
+- 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.
 
 ## File naming
 - Topic slug: lowercase, hyphens, no spaces — e.g., `firebase-auth-v9-migration.md`

package/skills/docs/strategy-workflow.md

@@ -0,0 +1,36 @@
+<!--
+skills/docs/strategy-workflow.md — Read, update, and reason about the product strategy.
+Canonical store: ~/.cx/strategy.md (user-global) or .cx/strategy.md (project-local, committed).
+Template: templates/docs/strategy.md.
+-->
+# Strategy Workflow
+
+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.
+
+## Reading Strategy
+
+1. Read `~/.cx/strategy.md` (or project-local `.cx/strategy.md`).
+2. If the file does not exist, inform the user and offer to create it using `templates/docs/strategy.md`.
+3. Parse sections: Vision, Bets, Non-bets, Time Horizon, North Star Metric, Competitive Positioning.
+
+## Checking Signal Alignment
+
+Given a product signal or PRD, check:
+- Does the signal target a declared Bet? → flag as strategically aligned.
+- Does the signal conflict with a Non-bet? → flag the conflict; the user must make an explicit override decision.
+- Does the signal address the Time Horizon goal? → note this in the signal brief.
+
+## Updating Strategy
+
+1. Show the user the current section being updated.
+2. Propose the change with rationale.
+3. Write the updated section and increment the `updated` date.
+4. If a Bet is being added, check for conflicting Non-bets and surface them.
+5. Strategy changes are always approved by the user before writing.
+
+## Storage
+
+| Scope | Path | Committed? |
+|---|---|---|
+| User-global | `~/.cx/strategy.md` | No — local only |
+| Project-local | `.cx/strategy.md` | Yes — source of truth for this repo |

package/skills/roles/data-analyst.product-intelligence.md

@@ -28,7 +28,7 @@ Additional failure modes on top of the data-analyst core.
 ### 3. Evidence store ignored
 **Symptom**: new briefs are written without checking prior Product Intelligence artifacts.
 **Why it fails**: teams rediscover the same signal and lose longitudinal context.
-**Counter-move**: query `.cx/product-intel`, `docs/prd`, and `docs/meta-prd` through hybrid search before drafting.
+**Counter-move**: query `.cx/knowledge`, `docs/prd`, and `docs/meta-prd` through hybrid search before drafting.
 
 ## Self-check before shipping
 - [ ] Evidence count, confidence, and counter-evidence are explicit

package/skills/roles/researcher.md

@@ -27,42 +27,55 @@ Load this before drafting. These are the failure modes that separate strong role
 **Counter-move**: require at least two independent sources for each load-bearing claim. Note when they disagree.
 
 ### 3. Freshness blindness
-**Symptom**: cited source dated 2019 used as current for a fast-moving topic — AI capabilities, framework APIs, security advisories.
+**Symptom**: cited source dated 2019–2024 used as current for a fast-moving topic — AI capabilities, framework APIs, security advisories.
 **Why it fails**: the reader assumes the finding is current; acts on stale information.
-**Counter-move**: check and record the publication date of every source. For fast-moving topics, prefer sources within the last 12 months.
+**Counter-move**: start searches from the most recent year and step backward only if insufficient. Record the publication date of every source. For fast-moving topics (LLM behavior, security advisories, market data), treat anything older than 12 months as presumptively stale unless a newer source confirms it is still accurate.
 
-### 4. Findings without confidence
+### 4. Wrong starting point
+**Symptom**: searching Google or a general index when a domain-specific authoritative source exists — arXiv for AI research, NVD for CVEs, NeurIPS/ICML proceedings for ML, official vendor docs for APIs.
+**Why it fails**: general search returns popularity-ranked results, not authority-ranked ones. The most-cited blog post is not the same as the primary paper.
+**Counter-move**: use the domain's authoritative starting point first (see `rules/common/research.md` §2). Only fall back to general search if the authoritative source is insufficient.
+
+### 5. Unverified URLs
+**Symptom**: URLs included in the brief have not been fetched — the researcher copied them from a search result or from memory.
+**Why it fails**: URLs rot. A confident citation pointing to a 404 or a different page than intended is worse than no citation.
+**Counter-move**: fetch every URL before including it. Confirm the content matches the cited claim. Mark any URL that cannot be fetched `[unverified]` and flag it as a gap.
+
+### 6. Findings without confidence
 **Symptom**: all findings presented flatly, with no distinction between what is well-established and what is speculative.
 **Why it fails**: the reader cannot decide how much weight to place on each claim.
 **Counter-move**: label each finding high / medium / low confidence, with a one-line reason.
 
-### 5. Observation confused with inference
+### 7. Observation confused with inference
 **Symptom**: the doc presents what the author concluded as what the source said.
 **Why it fails**: the conclusion cannot be audited. Reviewers who disagree cannot find the step where the logic turned.
 **Counter-move**: separate "what the source said" from "what I infer from this". Label them.
 
-### 6. Secondary sources passed as primary
+### 8. Secondary sources passed as primary
 **Symptom**: citations point to summaries, listicles, or syntheses instead of the underlying paper, spec, or changelog.
 **Why it fails**: the summary may misrepresent the primary source. The chain of error is invisible.
 **Counter-move**: cite primary sources — the actual paper, spec, commit, or dataset. Use secondary sources only to discover primary ones.
 
-### 7. Scope creep
+### 9. Scope creep
 **Symptom**: the research question was about X but the brief covers X, Y, and Z because they came up.
 **Why it fails**: the original question does not get answered well; reviewers cannot tell which findings are load-bearing.
 **Counter-move**: answer the original question first and completely. Tangential findings go into a separate section or a follow-up.
 
-### 8. Action without evidence threshold
+### 10. Action without evidence threshold
 **Symptom**: the implications section recommends a change without stating what evidence would have led to a different recommendation.
 **Why it fails**: the research is unfalsifiable. Any finding leads to the same recommendation.
 **Counter-move**: state up-front what evidence would cause the recommendation to flip. Verify the actual evidence meets the threshold.
 
 ## Self-check before shipping
 
-- [ ] Strongest counter-finding is named and addressed
-- [ ] Each load-bearing claim has at least two independent sources
-- [ ] Source dates recorded; fast-moving topics use recent sources
-- [ ] Each finding labeled with confidence and reason
-- [ ] Observation separated from inference
-- [ ] Citations point to primary sources
-- [ ] Original question is answered first; tangents are separate
-- [ ] Evidence threshold for the recommendation is stated
+- [ ] Started search from the most recent year and stepped back only when insufficient
+- [ ] Used domain-specific authoritative starting point (see `rules/common/research.md` §2), not general search as default
+- [ ] Every URL fetched and confirmed to match the cited claim
+- [ ] Strongest counter-finding named and addressed
+- [ ] Each load-bearing claim has at least two independent sources (or one authoritative primary)
+- [ ] Source dates recorded; fast-moving topics use sources within last 12 months
+- [ ] Each finding labeled with confidence (high/medium/low) and one-line reason
+- [ ] Observation separated from inference — labeled differently
+- [ ] Citations point to primary sources, not summaries or index pages
+- [ ] Original question answered first; tangents in a separate section
+- [ ] Evidence threshold for the recommendation is stated explicitly

package/skills/routing.md

@@ -122,7 +122,8 @@ Read the matching skill file before responding when the user's request matches t
 | init docs, create docs structure, set up documentation, docs scaffold, documentation init | `skills/docs/init-docs.md` | Initialize required project-state docs and documentation structure |
 | research X, investigate X, find evidence, gather evidence | `skills/docs/research-workflow.md` | Research workflow — question to .cx/research/ file |
 | product intelligence, customer notes, field notes, product signals, customer profile, evidence brief, signal brief, backlog proposal | `skills/docs/product-intelligence-workflow.md` | Product Intelligence workflow — evidence to product artifacts |
-| ingest evidence, ingest customer notes, ingest Slack thread, ingest support ticket, normalize field notes | `skills/docs/evidence-ingest-workflow.md` | Evidence ingest workflow — raw source to .cx/product-intel/ |
+| strategy, product strategy, strategic bet, non-bet, north star, time horizon, competitive positioning | `skills/docs/strategy-workflow.md` | Product strategy — read, update, and reason about the strategy store |
+| ingest evidence, ingest customer notes, ingest Slack thread, ingest support ticket, normalize field notes | `skills/docs/evidence-ingest-workflow.md` | Evidence ingest workflow — raw source to .cx/knowledge/ |
 | write a PRD, create requirements, spec out, requirements document, Meta PRD, platform PRD | `skills/docs/prd-workflow.md` | PRD workflow — requirements to docs/prd/ or docs/meta-prd/ |
 | write a PRFAQ, working backwards doc, press release FAQ | `skills/docs/prfaq-workflow.md` | PRFAQ workflow — launch narrative from PRD or evidence |
 | create Jira proposal, update Linear, backlog proposal, issue proposal | `skills/docs/backlog-proposal-workflow.md` | Backlog proposal workflow — approval-gated issue tracker changes |
@@ -137,3 +138,9 @@ Read the matching skill file before responding when the user's request matches t
 3. Detect programming language from file extensions or context and read the corresponding development skill.
 4. Read each skill file once per conversation.
 5. Skill file content is authoritative over training data when they conflict.
+
+## Agent Roster Disambiguation
+
+**cx-engineer vs cx-platform-engineer:** cx-engineer builds product features for end users. cx-platform-engineer builds the internal platform — CI/CD, deployment tooling, developer environments, internal APIs, and reliability infrastructure. They operate in distinct domains with different quality bars (user-facing UX vs. developer ergonomics and system reliability). Use cx-platform-engineer when the subject is a platform service, internal tool, build pipeline, or infrastructure component that engineers consume, not end users.
+
+**Platform domain overlays** (`roles/product-manager.platform`, `roles/architect.platform`, `roles/engineer.platform`) apply when the PRODUCT being designed or built is a platform — an API, SDK, or developer surface consumed by other developers. These are skill overlays on PM/architect/engineer roles, not routing to cx-platform-engineer. Route to cx-platform-engineer only when the work is infra/ops, not product.