@geraldmaron/construct 1.0.3 → 1.0.5

package/skills/roles/researcher.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/researcher.md — Anti-pattern guidance for the Researcher role.
+skills/roles/researcher.md. Anti-pattern guidance for the Researcher role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the researcher domain and counter-moves to avoid them.
@@ -9,11 +9,13 @@ Applies to: cx-researcher, cx-ux-researcher, cx-explorer.
 role: researcher
 applies_to: [cx-researcher, cx-ux-researcher, cx-explorer]
 inherits: null
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
-# Researcher — Role guidance
+# Researcher. Role guidance
 
-Load this before drafting. These are the failure modes that separate strong role output from weak role output — check your draft against each.
+Load this before drafting. These are the failure modes that separate strong role output from weak role output. check your draft against each.
 
 
 ### 1. Confirmation bias
@@ -27,42 +29,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.
+**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/roles/researcher.ux.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/researcher.ux.md — Anti-pattern guidance for the Researcher.ux (ux) role.
+skills/roles/researcher.ux.md. Anti-pattern guidance for the Researcher.ux (ux) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the researcher.ux (ux) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-ux-researcher.
 role: researcher.ux
 applies_to: [cx-ux-researcher]
 inherits: researcher
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # UX Researcher Overlay
 

package/skills/roles/reviewer.devil-advocate.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/reviewer.devil-advocate.md — Anti-pattern guidance for the Reviewer.devil-advocate (devil advocate) role.
+skills/roles/reviewer.devil-advocate.md. Anti-pattern guidance for the Reviewer.devil-advocate (devil advocate) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the reviewer.devil-advocate (devil advocate) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-devil-advocate.
 role: reviewer.devil-advocate
 applies_to: [cx-devil-advocate]
 inherits: reviewer
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # Devil's Advocate Overlay
 

package/skills/roles/reviewer.evaluator.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/reviewer.evaluator.md — Anti-pattern guidance for the Reviewer.evaluator (evaluator) role.
+skills/roles/reviewer.evaluator.md. Anti-pattern guidance for the Reviewer.evaluator (evaluator) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the reviewer.evaluator (evaluator) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-evaluator.
 role: reviewer.evaluator
 applies_to: [cx-evaluator]
 inherits: reviewer
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # Evaluator Overlay
 

package/skills/roles/reviewer.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/reviewer.md — Anti-pattern guidance for the Reviewer role.
+skills/roles/reviewer.md. Anti-pattern guidance for the Reviewer role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the reviewer domain and counter-moves to avoid them.
@@ -9,17 +9,19 @@ Applies to: cx-reviewer, cx-devil-advocate, cx-evaluator, cx-trace-reviewer.
 role: reviewer
 applies_to: [cx-reviewer, cx-devil-advocate, cx-evaluator, cx-trace-reviewer]
 inherits: null
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
-# Reviewer — Role guidance
+# Reviewer. Role guidance
 
-Load this before drafting. These are the failure modes that separate strong role output from weak role output — check your draft against each.
+Load this before drafting. These are the failure modes that separate strong role output from weak role output. check your draft against each.
 
 
 ### 1. Nit-picking over structure
-**Symptom**: the review focuses on variable names and formatting while leaving the structural problem — wrong abstraction, missing tests, unsafe concurrency — unflagged.
+**Symptom**: the review focuses on variable names and formatting while leaving the structural problem. wrong abstraction, missing tests, unsafe concurrency. unflagged.
 **Why it fails**: the author fixes the surface and ships the real bug. The reviewer signals thoroughness while providing no real coverage.
-**Counter-move**: audit structure first — correctness, blast radius, invariants, test coverage — before any style feedback.
+**Counter-move**: audit structure first. correctness, blast radius, invariants, test coverage. before any style feedback.
 
 ### 2. LGTM without running the code
 **Symptom**: approval given based on reading the diff, with no build, no test run, no exploration of the change in situ.
@@ -32,7 +34,7 @@ Load this before drafting. These are the failure modes that separate strong role
 **Counter-move**: grep for callers of anything changed. Check whether the change is backwards-compatible for each.
 
 ### 4. No severity
-**Symptom**: all feedback presented at the same weight — a typo and a security vulnerability get equal prominence.
+**Symptom**: all feedback presented at the same weight. a typo and a security vulnerability get equal prominence.
 **Why it fails**: the author cannot tell what blocks merge versus what is optional. Real issues get lost.
 **Counter-move**: label each finding CRITICAL / HIGH / MEDIUM / LOW. State what the author must address before merge.
 
@@ -71,11 +73,11 @@ Load this before drafting. These are the failure modes that separate strong role
 
 A review that approves while these gates would fail in CI is a failed review. Run or confirm the author ran:
 
-- [ ] `npm test` — 0 failed
-- [ ] `node bin/construct lint:comments` — 0 errors AND 0 warnings (treat warnings as blocking)
-- [ ] `node bin/construct docs:verify` — all checks passed, no warnings
-- [ ] `node bin/construct docs:update --check` — AUTO regions up to date
-- [ ] `npm run lint:templates` — commit subjects + PR body match the canonical templates
+- [ ] `npm test`. 0 failed
+- [ ] `node bin/construct lint:comments`. 0 errors AND 0 warnings (treat warnings as blocking)
+- [ ] `node bin/construct docs:verify`. all checks passed, no warnings
+- [ ] `node bin/construct docs:update --check`. AUTO regions up to date
+- [ ] `npm run lint:templates`. commit subjects + PR body match the canonical templates
 
 See `rules/common/release-gates.md`. Block approval until evidence is in the PR body.
 

package/skills/roles/reviewer.trace.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/reviewer.trace.md — Anti-pattern guidance for the Reviewer.trace (trace) role.
+skills/roles/reviewer.trace.md. Anti-pattern guidance for the Reviewer.trace (trace) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the reviewer.trace (trace) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-trace-reviewer.
 role: reviewer.trace
 applies_to: [cx-trace-reviewer]
 inherits: reviewer
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # Trace Reviewer Overlay
 

package/skills/roles/security.ai.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/security.ai.md — Anti-pattern guidance for the Security.ai (ai) role.
+skills/roles/security.ai.md. Anti-pattern guidance for the Security.ai (ai) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the security.ai (ai) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-security, cx-ai-engineer.
 role: security.ai
 applies_to: [cx-security, cx-ai-engineer]
 inherits: security
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # AI Security Overlay
 

package/skills/roles/security.appsec.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/security.appsec.md — Anti-pattern guidance for the Security.appsec (appsec) role.
+skills/roles/security.appsec.md. Anti-pattern guidance for the Security.appsec (appsec) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the security.appsec (appsec) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-security.
 role: security.appsec
 applies_to: [cx-security]
 inherits: security
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # AppSec Overlay
 

package/skills/roles/security.cloud.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/security.cloud.md — Anti-pattern guidance for the Security.cloud (cloud) role.
+skills/roles/security.cloud.md. Anti-pattern guidance for the Security.cloud (cloud) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the security.cloud (cloud) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-security.
 role: security.cloud
 applies_to: [cx-security]
 inherits: security
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # Cloud Security Overlay
 

package/skills/roles/security.legal-compliance.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/security.legal-compliance.md — Anti-pattern guidance for the Security.legal-compliance (legal compliance) role.
+skills/roles/security.legal-compliance.md. Anti-pattern guidance for the Security.legal-compliance (legal compliance) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the security.legal-compliance (legal compliance) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-legal-compliance.
 role: security.legal-compliance
 applies_to: [cx-legal-compliance]
 inherits: security
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # Legal & Compliance Overlay
 

package/skills/roles/security.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/security.md — Anti-pattern guidance for the Security role.
+skills/roles/security.md. Anti-pattern guidance for the Security role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the security domain and counter-moves to avoid them.
@@ -9,15 +9,17 @@ Applies to: cx-security, cx-legal-compliance.
 role: security
 applies_to: [cx-security, cx-legal-compliance]
 inherits: null
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
-# Security — Role guidance
+# Security. Role guidance
 
-Load this before drafting. These are the failure modes that separate strong role output from weak role output — check your draft against each.
+Load this before drafting. These are the failure modes that separate strong role output from weak role output. check your draft against each.
 
 
 ### 1. Defense in absence
-**Symptom**: protection depends on a single layer — a firewall, a middleware, a validation step — with no defense if that layer is bypassed.
+**Symptom**: protection depends on a single layer. a firewall, a middleware, a validation step. with no defense if that layer is bypassed.
 **Why it fails**: one misconfiguration or bug eliminates all protection at once.
 **Counter-move**: assume any single control can fail. Layer controls at the network, application, and data boundaries.
 

package/skills/roles/security.privacy.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/security.privacy.md — Anti-pattern guidance for the Security.privacy (privacy) role.
+skills/roles/security.privacy.md. Anti-pattern guidance for the Security.privacy (privacy) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the security.privacy (privacy) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-security, cx-legal-compliance.
 role: security.privacy
 applies_to: [cx-security, cx-legal-compliance]
 inherits: security
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # Privacy Security Overlay
 

package/skills/roles/security.supply-chain.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/security.supply-chain.md — Anti-pattern guidance for the Security.supply-chain (supply chain) role.
+skills/roles/security.supply-chain.md. Anti-pattern guidance for the Security.supply-chain (supply chain) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the security.supply-chain (supply chain) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-security, cx-platform-engineer.
 role: security.supply-chain
 applies_to: [cx-security, cx-platform-engineer]
 inherits: security
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # Supply Chain Security Overlay
 

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.

package/templates/docs/persona-artifact.md

@@ -0,0 +1,36 @@
+# <Role display name>
+
+> Anchor doc for the <role-id> persona. Methodology: `docs/concepts/persona-research.md`. This file is generated by `construct profile create` and is part of the discover + frame phases. The persona is not promotable until every section below is filled from evidence, not opinion.
+
+## Goals
+
+- <What does success look like for this role? Not the org's goals; theirs.>
+- <Goal 2>
+
+## Frustrations
+
+- <What slows them down, what they get blamed for.>
+
+## Decision rights
+
+- Decides: <list>
+- Escalates: <list>
+
+## Handoffs
+
+- Hands off to: <role> when <condition>
+- Receives from: <role> when <condition>
+
+## Output contract
+
+- Format: <markdown structure, code diff, JSON, etc.>
+- Depth: <short bullet list, two-page doc, one-screen summary, etc.>
+- Citations: <required | encouraged | none>
+
+## Failure modes
+
+- <Common ways this persona goes wrong; what to watch for.>
+
+## Evidence
+
+- <Interview, doc, postmortem, public job spec. At least two primary sources.>

package/templates/docs/research-brief.md

@@ -2,28 +2,82 @@
 
 - **Date**: {YYYY-MM-DD}
 - **Author**: {name}
+- **Domain**: {ai-tools | developer-tools | security | market | cloud-api | regulatory | academic | other}
 - **Status**: in-progress | complete
+- **Recency baseline**: Sources from {YYYY} and later preferred; oldest source used: {YYYY-MM-DD}
 
 ## Question
-<!-- The specific, falsifiable question this research is trying to answer. One sentence. -->
+
+<!-- One specific, falsifiable question this research must answer. Not a topic — a question with a determinate answer. -->
 
 ## Method
-<!-- How the question was investigated. Start order, queries run, internal paths checked, experiments performed, and systems consulted. Enough detail that another person could reproduce it. -->
+
+<!-- How the question was investigated:
+  - Domain starting point used (arXiv, NVD, Stack Overflow Survey, vendor docs, etc.)
+  - Date filter applied (search from YYYY-first)
+  - Internal paths checked (.cx/research/, .cx/knowledge/, ADRs, etc.)
+  - Search terms and queries run
+  - Systems and indexes consulted
+  - Inclusion/exclusion decisions
+  Enough detail that another person could reproduce it. -->
 
 ## Sources
-<!-- For each source record: title/path, source class (internal/primary/secondary/tertiary), version or revision if relevant, and publication/access date. Separate primary from secondary. Note where sources disagree. -->
+
+| Title / Path | Class | Date | URL | Verified | Relevance |
+|---|---|---|---|---|---|
+| {source title or file path} | primary / secondary / tertiary | {YYYY-MM-DD} | {URL or path} | yes / no / n/a | {one-line} |
+
+<!-- Class definitions:
+  - primary: peer-reviewed papers, official docs at exact version, raw source code, standards, company announcements, SEC filings
+  - secondary: changelogs, migration guides, tracked issues, maintainer posts, conference talks by authors
+  - tertiary: blog posts, forums, Q&A, analyst summaries — for discovery only, never as evidence
+  Mark Verified = yes only after fetching the URL and confirming content matches. -->
 
 ## Findings
-<!-- What the evidence says. Separate observation from inference. Label each finding with its confidence level and cite the supporting source(s). -->
 
-## Confidence
-<!-- Per finding: high / medium / low, and why. Name the biggest unknowns. -->
+<!-- For each finding, state separately:
+  - Observation: what the source(s) actually say — direct, traceable
+  - Inference: what is concluded from the observation — labeled as inference
+  - Confidence: high / medium / low, with a one-line reason
+  - Sources: reference the Source table row(s) -->
+
+### Finding 1 — {short label}
+
+**Observation**: <!-- what the sources say -->
+**Inference**: <!-- what is concluded — labeled as inference -->
+**Confidence**: high / medium / low — {reason}
+**Sources**: {source title(s) from table}
+
+### Finding N — {short label}
+
+<!-- repeat as needed -->
+
+## Counter-evidence
+
+<!-- The strongest finding that contradicts or complicates the conclusion. How it was addressed. If no counter-evidence was found, state that and note whether it was actively searched for. -->
+
+## Confidence summary
+
+<!-- Overall confidence across all findings. Key uncertainties. What would most change the conclusion. -->
+
+## Gaps
+
+<!-- What this research did not resolve. For each gap: what evidence is missing and what would be needed to fill it. -->
 
 ## Implications
-<!-- What decisions this research enables or blocks. Who should act on it. -->
+
+<!-- What decisions this research enables or blocks. Who should act on it and in what timeframe. -->
+
+## Recommendation
+
+<!-- What the evidence supports. State the evidence threshold at which this recommendation would flip. -->
 
 ## Open questions
-<!-- What this research did not resolve. What would be needed to answer each. -->
+
+<!-- Remaining questions scoped out of this brief. Suitable for a follow-up research task or a handoff. -->
 
 ## References
-<!-- Full citation list. Include URLs, document paths, versions, and dates. -->
+
+<!-- Full citation list. Format: Author(s). (Year). Title. Venue/Source. Retrieved from URL.
+  Include: author(s) or org, year, title, publication venue, URL, access date for web sources.
+  Mark any URL that was not verified as [unverified]. -->

package/templates/docs/research-finding.md

@@ -0,0 +1,26 @@
+---
+kind: research-finding
+topic: "<short topic line>"
+confidence: inferred
+sources: []
+created: <ISO timestamp set by construct knowledge add>
+expiresAt: <ISO timestamp, default created + 90d>
+profile: <active profile id>
+---
+
+## FINDINGS
+
+- <Finding 1 with citation>
+- <Finding 2 with citation>
+
+## INFERENCES
+
+- <Inference labeled as such>
+
+## GAPS
+
+- <What we could not confirm>
+
+## RECOMMENDATION
+
+- <Next action based on the evidence available>

package/templates/docs/skill-artifact.md

@@ -0,0 +1,27 @@
+---
+name: <verb-led-id>
+scope: <one paragraph: what it covers, what it does not>
+observable_outcome: <how someone outside the role tells this skill happened>
+provenance:
+  - <citation: post-mortem, public framework, competency model>
+roles:
+  - <role-id that uses this skill>
+---
+
+# <Skill display name>
+
+## What this skill produces
+
+<Concrete output. Bloom-style: not "knows X" but "produces Y".>
+
+## When to invoke it
+
+<Triggers. What the operator or the upstream persona is doing when this skill is the right call.>
+
+## How it composes
+
+<Other skills typically chained before or after.>
+
+## Anti-patterns
+
+<Ways this skill gets misapplied; what looks similar but is not this.>

package/templates/docs/strategy.md

@@ -0,0 +1,36 @@
+---
+title: Product Strategy
+updated: YYYY-MM-DD
+horizon: "6–12 months"
+---
+
+<!--
+templates/docs/strategy.md — Template for product strategy documents.
+Use for both user-product strategy and Construct's own strategy (.cx/strategy.md).
+Canonical store: ~/.cx/strategy.md (user-global) or .cx/strategy.md (project-local, committed).
+Owning workflow: skills/docs/strategy-workflow.md.
+-->
+
+## Vision
+<!-- 1–3 sentences. Where are we going in 3–5 years? -->
+
+## Bets
+<!-- Explicit choices. Each bet: what we're doing and why. -->
+- **Bet 1**: …
+- **Bet 2**: …
+
+## Non-bets
+<!-- What we are explicitly NOT doing, and why. This section prevents strategy drift. -->
+- **Not doing**: … **Because**: …
+
+## Time Horizon
+<!-- Current cycle focus. What must be true 6–12 months from now? -->
+
+## North Star Metric
+<!-- Single measurable outcome. Format: Metric / Baseline / Target / Owner -->
+
+## Competitive Positioning
+<!-- How we differentiate. 2–4 sentences. -->
+
+## Open Bets
+<!-- Decisions not yet made. Clarify and move to Bets or Non-bets. -->

package/templates/homebrew/construct.rb

@@ -2,13 +2,13 @@
 #
 # Authoritative copy lives in the construct repo at templates/homebrew/
 # construct.rb. The tap repo (geraldmaron/homebrew-construct) carries the
-# active formula at Formula/construct.rb and is updated by the release
-# workflow's Homebrew bump step on every tag push.
+# active formula at Formula/construct.rb.
 #
-# When the release pipeline fires for `vX.Y.Z`, dawidd6/action-homebrew-bump-
-# formula rewrites the url + sha256 fields for each platform from the
-# matching GitHub Release asset. The placeholder SHAs below are only used
-# when seeding the tap by hand the first time.
+# The release workflow's `homebrew` job regenerates Formula/construct.rb from
+# scratch on every `v*` tag push — it downloads sha256 sidecars from the
+# GitHub Release, fills in the version and per-platform URLs/SHAs, and pushes
+# directly to the tap. The placeholder SHAs below are only used when seeding
+# the tap by hand the first time (see docs/maintenance/homebrew-tap.md).
 class Construct < Formula
   desc "Deployable AI R&D operating system for coding agents — runs locally or for teams"
   homepage "https://github.com/geraldmaron/construct"