@geraldmaron/construct 1.0.4 → 1.0.6

package/skills/security/pentest.md

@@ -1,5 +1,5 @@
 <!--
-skills/security/pentest.md — Penetration Testing — Use this skill when testing web applications or APIs for security vulnerabilitie
+skills/security/pentest.md (Penetration Testing) Use this skill when testing web applications or APIs for security vulnerabilitie
 
 Use this skill when testing web applications or APIs for security vulnerabilities. ## OWASP Top 10 Checklist
 -->

package/skills/security/red-team.md

@@ -1,5 +1,5 @@
 <!--
-skills/security/red-team.md — Red Team — Use this skill when planning or executing offensive security assessments, advers
+skills/security/red-team.md (Red Team) Use this skill when planning or executing offensive security assessments, advers
 
 Use this skill when planning or executing offensive security assessments, adversary emulation, or attack simulations. ## Reconnaissance
 -->

package/skills/security/threat-intel.md

@@ -1,5 +1,5 @@
 <!--
-skills/security/threat-intel.md — Threat Intelligence — Use this skill when performing OSINT, threat modeling, or building threat intell
+skills/security/threat-intel.md (Threat Intelligence) Use this skill when performing OSINT, threat modeling, or building threat intell
 
 Use this skill when performing OSINT, threat modeling, or building threat intelligence programs. ## OSINT Collection
 -->

package/skills/security/vuln-research.md

@@ -1,5 +1,5 @@
 <!--
-skills/security/vuln-research.md — Vulnerability Research — Use this skill when analyzing binaries, fuzzing software, or developing exploits
+skills/security/vuln-research.md (Vulnerability Research) Use this skill when analyzing binaries, fuzzing software, or developing exploits
 
 Use this skill when analyzing binaries, fuzzing software, or developing exploits for security research. ## Binary Analysis
 -->

package/skills/utility/clean-code.md

@@ -1,5 +1,5 @@
 <!--
-skills/utility/clean-code.md — AI Slop Removal — Patterns and heuristics for identifying and removing AI-generated code smells. U
+skills/utility/clean-code.md (AI Slop Removal) Patterns and heuristics for identifying and removing AI-generated code smells. U
 
 Patterns and heuristics for identifying and removing AI-generated code smells. Use when cleaning up output from AI coding tools. ## Decision Tree
 -->
@@ -160,6 +160,6 @@ async function getUserById(id: string): Promise<User> { ... }
 ## Rules
 
 - Remove smell, nothing else. Do not refactor, reorganize, or add new abstractions.
-- Keep diffs minimal — one smell per change where possible.
+- Keep diffs minimal: one smell per change where possible.
 - Never change behavior. If a removal would change behavior, flag it instead.
 - Show before/after for every change.

package/templates/docs/changelog-entry.md

@@ -1,4 +1,4 @@
-# Changelog: {version} — {YYYY-MM-DD}
+# Changelog: {version}: {YYYY-MM-DD}
 
 - **Version**: {semver or date-based tag}
 - **Type**: major | minor | patch | hotfix

package/templates/docs/construct_guide.md

@@ -1,6 +1,6 @@
 # Welcome to Construct
 
-This file was generated by `construct init` to help you get oriented. It's safe to edit — Construct only writes it once, then leaves it alone.
+This file was generated by `construct init` to help you get oriented. It's safe to edit: Construct only writes it once, then leaves it alone.
 
 **Full docs:** [https://geraldmaron.github.io/construct/v2/](https://geraldmaron.github.io/construct/v2/)
 
@@ -12,7 +12,7 @@ You added Construct as a dev dependency. That gave you:
 - **Hard gates.** Every code change runs through commit-time policy: no secrets, tests green, docs current, comments lint-clean. Bypass exists for every gate but leaves an audit trail.
 - **Persistent state.** Your active work, decisions, and history survive across sessions and editor restarts.
 
-You don't need to manage any of that — it all runs locally.
+You don't need to manage any of that: it all runs locally.
 
 ## Files Construct created in your project
 
@@ -26,18 +26,18 @@ You'll see these in `git status`:
 | `.claude/settings.json` | Hooks + MCP server config. Construct keys are managed; your additions are preserved. | Carefully |
 | `.cx/` | Per-project session state (active work, recent decisions). Construct writes here. | Read-mostly |
 | `.beads/` | Issue tracker data. Use `bd <cmd>` to interact. | Via CLI |
-| `AGENTS.md` | Operating rules the agent reads at session start. | Yes — your house rules go here |
-| `plan.md` | Active work plan. Local-only (gitignored). | Yes — your current focus |
-| `docs/` | Documentation lanes (ADRs, PRDs, memos, …). | Yes — this is your team's docs |
-| `construct_guide.md` | This file. Friendly orientation. | Yes — adapt to your team |
+| `AGENTS.md` | Operating rules the agent reads at session start. | Yes: your house rules go here |
+| `plan.md` | Active work plan. Local-only (gitignored). | Yes: your current focus |
+| `docs/` | Documentation lanes (ADRs, PRDs, memos, …). | Yes: this is your team's docs |
+| `construct_guide.md` | This file. Friendly orientation. | Yes: adapt to your team |
 
 ## Where to drop information you want Construct to use
 
 Three intake paths, ordered by formality:
 
-1. **`.cx/inbox/`** — drop a file here (URL, screenshot, paste, anything). The embed daemon watches the directory; when a file lands, it ingests it into the local knowledge base within a second or two and writes a triage packet to `.cx/intake/pending/` describing the new content, its R&D classification (intake type, stage, owner persona, recommended chain), its suggested docs lane, and existing docs that overlap. The agent surfaces pending intake at the next session start and you can ask it to process them — propose updates to existing PRDs/RFCs/ADRs or scaffold new ones — based on the prepared context.
-2. **`docs/intake/`** — for proper intake batches (research notes, evidence from a meeting, raw source material). Has a template. Survives in git history.
-3. **`AGENTS.md`** — for rules and conventions you want the agent to follow every time. "We prefer functional components. Don't introduce new dependencies without flagging." Read at session start.
+1. **`.cx/inbox/`** (drop a file here (URL, screenshot, paste, anything). The embed daemon watches the directory; when a file lands, it ingests it into the local knowledge base within a second or two and writes a triage packet to `.cx/intake/pending/` describing the new content, its R&D classification (intake type, stage, owner persona, recommended chain), its suggested docs lane, and existing docs that overlap. The agent surfaces pending intake at the next session start and you can ask it to process them) propose updates to existing PRDs/RFCs/ADRs or scaffold new ones: based on the prepared context.
+2. **`docs/intake/`**: for proper intake batches (research notes, evidence from a meeting, raw source material). Has a template. Survives in git history.
+3. **`AGENTS.md`**: for rules and conventions you want the agent to follow every time. "We prefer functional components. Don't introduce new dependencies without flagging." Read at session start.
 
 For URLs or quick notes, the easiest path is to drop a file into `~/Downloads` and run:
 
@@ -82,7 +82,7 @@ construct doctor             # verify everything's healthy
 
 If you ran `construct init` and have Docker, you have three things running locally on Construct's reserved port block (`54329-54339`, chosen to avoid colliding with Next.js, Postgres, Redis, etc.):
 
-**Telemetry backend** (LLM observability — see your traces, costs, and quality scores)
+**Telemetry backend** (LLM observability: see your traces, costs, and quality scores)
 
 - URL: <http://localhost:54330>
 
@@ -97,7 +97,7 @@ If you ran `construct init` and have Docker, you have three things running local
 - Model auto-downloaded to `~/.construct/cache/embeddings/` on first use (~22 MB, one time)
 - Run `construct search "your query"` to see it work
 
-If you skipped Docker, Construct falls back to a local JSON vector index at `~/.construct/vector/index.json` and stops emitting traces — semantic search still works, just slower at scale, and the telemetry backend isn't available.
+If you skipped Docker, Construct falls back to a local JSON vector index at `~/.construct/vector/index.json` and stops emitting traces: semantic search still works, just slower at scale, and the telemetry backend isn't available.
 
 All ports bind to `127.0.0.1` only; nothing is reachable from other machines on your network.
 
@@ -115,7 +115,7 @@ All ports bind to `127.0.0.1` only; nothing is reachable from other machines on
 | `construct graph from-intake <id>` | Generate a task graph from a triaged intake packet |
 | `construct drop` | Ingest the most recent downloaded file |
 | `construct search "..."` | Hybrid file + SQL + semantic search over project state |
-| `construct uninstall` | Interactive teardown — never touches Docker or your code |
+| `construct uninstall` | Interactive teardown: never touches Docker or your code |
 
 Full reference: <https://geraldmaron.github.io/construct/v2/docs/reference/cli>
 
@@ -140,7 +140,7 @@ Troubleshooting guide: <https://geraldmaron.github.io/construct/v2/docs/operatio
 
 - [Connect your editor](https://geraldmaron.github.io/construct/v2/docs/start/connect-your-editor) if you haven't already.
 - [Run your first task](https://geraldmaron.github.io/construct/v2/docs/start/first-task) to feel the flow.
-- Skim [the architecture](https://geraldmaron.github.io/construct/v2/docs/concepts/architecture) when you have 10 minutes — it'll save you hours later.
+- Skim [the architecture](https://geraldmaron.github.io/construct/v2/docs/concepts/architecture) when you have 10 minutes: it'll save you hours later.
 
 If you'd rather have a teammate walk you through it, the persona itself can:
 

package/templates/docs/meta-prd.md

@@ -27,8 +27,8 @@ the org decides, documents, or evaluates work once this ships.
 <!--
 The current state of the operating system: which workflow, template, eval
 loop, or governance process is in play today, and what's actually happening
-when teams or agents use it. Cite real examples — recent PRDs, prior decisions,
-trace evidence, support tickets — not hypotheticals.
+when teams or agents use it. Cite real examples: recent PRDs, prior decisions,
+trace evidence, support tickets: not hypotheticals.
 -->
 
 ## Problem
@@ -40,7 +40,7 @@ Examples of the right shape:
 - "PRDs ship without rejected alternatives, so reviewers re-litigate decisions
   three weeks in. Happens on ~40% of PRDs in the last quarter."
 - "Postmortems are written by the on-call who shipped the bug, so the action
-  items reflect their proposals — not independent review."
+  items reflect their proposals: not independent review."
 -->
 
 ## Goals
@@ -63,7 +63,7 @@ the doc enters review."
 | | Description |
 |---|---|
 | **In scope** | <which templates, workflows, agents, gates, or evals are touched> |
-| **Out of scope** | <related operating systems explicitly deferred — name the reason> |
+| **Out of scope** | <related operating systems explicitly deferred: name the reason> |
 | **Adjacent (deferred)** | <natural follow-up changes not in this Meta PRD> |
 
 ## Principles
@@ -74,7 +74,7 @@ principle should be testable enough to guide tradeoffs when phases conflict.
 
 ## Inputs and evidence
 <!--
-What evidence the system consumes — customer notes, interviews, traces, Jira
+What evidence the system consumes: customer notes, interviews, traces, Jira
 issues, PRDs, research, analytics, support tickets, prior decisions. State
 minimum evidence thresholds where useful (e.g. "two independent customer
 interviews before a PRD enters review").
@@ -98,53 +98,53 @@ constraints, anti-patterns, rubric dimensions, pass/fail checks.
 Status values: not started | in progress | shipped | deferred.
 -->
 
-### Phase 1 — <name>
+### Phase 1: <name>
 
 - **Goal**: <what this phase delivers>
 - **Status**: not started
 
 **Workflow**
 
-- **MR-1.1** — <imperative statement of how the workflow must behave>
+- **MR-1.1**: <imperative statement of how the workflow must behave>
   - *Acceptance*: <how a reviewer or trace verifies this without asking the author>
-- **MR-1.2** — <...>
+- **MR-1.2**: <...>
   - *Acceptance*: <...>
 
 **Document + evaluation**
 
-- **DR-1.1** — <required section, evidence rule, citation rule, formatting constraint, or anti-pattern>
+- **DR-1.1**: <required section, evidence rule, citation rule, formatting constraint, or anti-pattern>
   - *Acceptance*: <rubric dimension, pass/fail check, or trace signal that proves it>
 
-### Phase 2 — <name>
+### Phase 2: <name>
 
 - **Goal**: <what this phase delivers>
 - **Status**: not started
 
 **Workflow**
 
-- **MR-2.1** — <...>
+- **MR-2.1**: <...>
   - *Acceptance*: <...>
-- **MR-2.2** — <...>
+- **MR-2.2**: <...>
   - *Acceptance*: <...>
 
 **Document + evaluation**
 
-- **DR-2.1** — <...>
+- **DR-2.1**: <...>
   - *Acceptance*: <...>
 
-### Phase 3 — <name>
+### Phase 3: <name>
 
 - **Goal**: <what this phase delivers>
 - **Status**: not started
 
 **Workflow**
 
-- **MR-3.1** — <...>
+- **MR-3.1**: <...>
   - *Acceptance*: <...>
 
 **Document + evaluation**
 
-- **DR-3.1** — <...>
+- **DR-3.1**: <...>
   - *Acceptance*: <...>
 
 ## Human approval gates

package/templates/docs/one-pager.md

@@ -12,7 +12,7 @@
 <!-- One paragraph. What we will do, at a level a non-specialist can understand. -->
 
 ## Why now
-<!-- One paragraph. What makes this the right moment — a trigger, a constraint, a window. -->
+<!-- One paragraph. What makes this the right moment: a trigger, a constraint, a window. -->
 
 ## Success measure
 <!-- The single metric that tells us this worked. Numeric, time-bound. -->

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/prd-business.md

@@ -22,7 +22,7 @@ Use prd-platform.md for internal platform and developer-facing capabilities.
 <!-- The one-paragraph view of market shape, buyer behavior, and where value accrues. Every decision in this document links back here or challenges it. -->
 
 ## Problem and opportunity
-<!-- What is broken in the market or business today? What does the opportunity look like at full scale? State the pain and the size of the prize — with evidence. -->
+<!-- What is broken in the market or business today? What does the opportunity look like at full scale? State the pain and the size of the prize: with evidence. -->
 
 ## Strategic goals
 <!-- What this decision achieves at the business level: position, revenue, defensibility, optionality. Tie to company objectives. -->

package/templates/docs/prd-platform.md

@@ -6,7 +6,7 @@
 
 <!--
 Use this for capabilities consumed by internal systems, developers, operators, or other
-services — not directly by end users. Covers APIs, SDKs, admin surfaces, data contracts,
+services: not directly by end users. Covers APIs, SDKs, admin surfaces, data contracts,
 shared infrastructure, and operational tooling.
 
 Use prd.md instead for customer-facing product capabilities.

package/templates/docs/prd.md

@@ -12,7 +12,7 @@ process, template, evaluation loop, or operating model.
 Before drafting, read rules/common/framing.md.
 
 Owning specialist: cx-product-manager (see rules/common/doc-ownership.md).
-Construct must route PRD authoring to cx-product-manager rather than drafting directly —
+Construct must route PRD authoring to cx-product-manager rather than drafting directly.
 doing so is how requirements traceability, user grounding, and external research fire.
 
 Write with a balance of short paragraphs, tables, and bullets. Bullets are for scans,
@@ -67,7 +67,7 @@ Examples:
 ## Outcome
 <!--
 What is concretely different for users, the business, or the system once this
-ships and is adopted. This is the observable end state — written from the
+ships and is adopted. This is the observable end state: written from the
 user's perspective when possible. The acceptance criteria below should be the
 falsifiable evidence that this outcome was achieved.
 
@@ -80,13 +80,13 @@ section and see the delta in plain language.
 | | Description |
 |---|---|
 | **In scope** | <what this PRD covers and commits to ship> |
-| **Out of scope** | <related work explicitly deferred — name the reason> |
+| **Out of scope** | <related work explicitly deferred: name the reason> |
 | **Adjacent (deferred)** | <work that's a natural follow-up but not in this PRD> |
 
 <!--
 Be specific. "Authentication" is too vague; "OAuth login for the web dashboard,
 not for the CLI" is right. The Out of scope list is a tool for protecting
-schedule and reviewer attention — use it.
+schedule and reviewer attention: use it.
 -->
 
 ## Phases
@@ -94,7 +94,7 @@ schedule and reviewer attention — use it.
 <!--
 Phases are how this work ships, not how it's organized internally. Each phase
 is independently shippable and provides observable user value (or a clearly
-defined platform capability). Avoid "phase 1: backend, phase 2: frontend" —
+defined platform capability). Avoid "phase 1: backend, phase 2: frontend".
 that's a task list, not a phasing.
 
 Each phase below holds its own goal, status, functional requirements (FR),
@@ -108,53 +108,53 @@ NFR categories to consider: performance, reliability, security, privacy,
 accessibility, observability, compliance, cost. Numeric targets where possible.
 -->
 
-### Phase 1 — <name>
+### Phase 1: <name>
 
 - **Goal**: <what this phase delivers>
 - **Status**: not started
 
 **Functional**
 
-- **FR-1.1** — <imperative statement of what the system must do>
+- **FR-1.1**: <imperative statement of what the system must do>
   - *Acceptance*: <observable, falsifiable condition a reviewer can check without asking the author>
-- **FR-1.2** — <...>
+- **FR-1.2**: <...>
   - *Acceptance*: <...>
 
 **Non-functional**
 
-- **NFR-1.1** — <category>: <target with number>
+- **NFR-1.1**: <category>: <target with number>
   - *Acceptance*: <how this is measured and what counts as pass>
 
-### Phase 2 — <name>
+### Phase 2: <name>
 
 - **Goal**: <what this phase delivers>
 - **Status**: not started
 
 **Functional**
 
-- **FR-2.1** — <...>
+- **FR-2.1**: <...>
   - *Acceptance*: <...>
-- **FR-2.2** — <...>
+- **FR-2.2**: <...>
   - *Acceptance*: <...>
 
 **Non-functional**
 
-- **NFR-2.1** — <category>: <target>
+- **NFR-2.1**: <category>: <target>
   - *Acceptance*: <...>
 
-### Phase 3 — <name>
+### Phase 3: <name>
 
 - **Goal**: <what this phase delivers>
 - **Status**: not started
 
 **Functional**
 
-- **FR-3.1** — <...>
+- **FR-3.1**: <...>
   - *Acceptance*: <...>
 
 **Non-functional**
 
-- **NFR-3.1** — <category>: <target>
+- **NFR-3.1**: <category>: <target>
   - *Acceptance*: <...>
 
 ## Success metrics
@@ -165,7 +165,7 @@ acceptance criteria. Leading vs. lagging. Avoid vanity metrics.
 
 ## Constraints
 <!--
-Budget, timeline, platform, team, legal, technical debt — anything that shapes
+Budget, timeline, platform, team, legal, technical debt: anything that shapes
 the solution and isn't a requirement.
 -->
 

package/templates/docs/research-brief.md

@@ -8,7 +8,7 @@
 
 ## Question
 
-<!-- One specific, falsifiable question this research must answer. Not a topic — a question with a determinate answer. -->
+<!-- One specific, falsifiable question this research must answer. Not a topic: a question with a determinate answer. -->
 
 ## Method
 
@@ -30,25 +30,25 @@
 <!-- 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
+  - 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
 
 <!-- For each finding, state separately:
-  - Observation: what the source(s) actually say — direct, traceable
-  - Inference: what is concluded from the observation — labeled as inference
+  - 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}
+### Finding 1: {short label}
 
 **Observation**: <!-- what the sources say -->
-**Inference**: <!-- what is concluded — labeled as inference -->
-**Confidence**: high / medium / low — {reason}
+**Inference**: <!-- what is concluded: labeled as inference -->
+**Confidence**: high / medium / low: {reason}
 **Sources**: {source title(s) from table}
 
-### Finding N — {short label}
+### Finding N: {short label}
 
 <!-- repeat as needed -->
 

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/rfc.md

@@ -9,7 +9,7 @@
 <!--
 Use this for significant technical or architectural proposals that need structured
 review before implementation begins. An RFC is not an ADR (which records a decision
-already made) — it is the proposal that leads to one.
+already made): it is the proposal that leads to one.
 
 Use rfc-platform.md instead when the proposal introduces breaking changes to a
 contract, API, schema, or protocol consumed by other systems.

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

@@ -5,7 +5,7 @@ horizon: "6–12 months"
 ---
 
 <!--
-templates/docs/strategy.md — Template for product strategy documents.
+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.