@geraldmaron/construct 1.0.14 → 1.0.16

package/platforms/claude/CLAUDE.md

@@ -1,30 +1,58 @@
 # Construct: Claude Code Integration
 
-This project uses Construct. Personas and specialists are defined in `specialists/registry.json` and synced to Claude Code via `construct sync`.
+This file ships as a reference template alongside the Construct npm package. The canonical project-instructions file is `/CLAUDE.md` at your repo root — that's the file Claude Code actually reads at session start. The structure here mirrors that canonical file so users know what shape their own `/CLAUDE.md` should take after `construct init` scaffolds a project.
+
+Personas and specialists are defined in `specialists/registry.json` and rendered into Claude Code agents on every `construct sync`. The single user-facing persona is `construct`; the 28 specialists (cx-engineer, cx-security, cx-devil-advocate, …) are routed internally — you address Construct, Construct dispatches.
+
+## Critical rules (mirror in your project /CLAUDE.md)
+
+- **Never fabricate.** Every load-bearing claim cites a verifiable source. When a fact isn't in the source, write `unknown` or `[unverified]`. See `rules/common/no-fabrication.md`.
+- **Confirm the working branch every session.** Session-start surfaces `## Working branch: <name>` at the top of the injected context.
+- **Never commit, push, or merge without asking first.** State the branch, state the action, wait for explicit yes.
+- **Never edit running hook files** without testing them in isolation. A broken hook blocks all tool use.
+- **Hooks fire unconditionally. No skip env vars on quality gates.** If a check fires wrong, repair the check — do not re-introduce `CONSTRUCT_SKIP_*` / `CONSTRUCT_ALLOW_*`.
+- **Never commit directly to main.** Branch, test, then merge.
+- **Run `construct doctor`** after structural changes.
 
 ## Workflow roles
 
-Construct is the only intended user-facing surface.
+| Role | What it covers |
+|---|---|
+| **Planning** | Requirements, strategy, architecture, framing challenges |
+| **Implementation** | Builds features and fixes bugs |
+| **Validation** | Quality gates, code review, security, accessibility |
+| **Research** | Docs, debugging, codebase exploration, external research |
+| **Operations** | Releases, dev servers, health checks, observability |
+
+Construct routes complex work through the full pipeline (plan → implement → validate → operate). For simple tasks, Construct acts directly without exposing the internal routing.
+
+## Beads issue tracker
+
+This project uses **bd (beads)** for issue tracking. Run `bd prime` for the full workflow context.
 
-- **Planning**: requirements, strategy, architecture
-- **Implementation**: builds features and fixes bugs
-- **Validation**: quality gates, security, accessibility
-- **Research**: docs, debugging, codebase exploration
-- **Operations**: releases, dev servers, health checks
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
 
-## Usage
+Use `bd` for all task tracking. Do NOT use TodoWrite, TaskCreate, or markdown TODO lists.
 
-Talk to Construct normally. It routes complex work through the full pipeline internally:
-plan → implement → validate → operate
+## Session completion
 
-For simple tasks, Construct can act directly without exposing internal routing.
+When ending a work session, **work is not complete until `git push` succeeds.**
 
-All 26 internal specialists (cx-engineer, cx-security, cx-devil-advocate, etc.) are available as subagents.
+```bash
+git pull --rebase
+git push
+git status  # MUST show "up to date with origin"
+```
 
-## Tool Calls
+## Tool calls
 
 When using Bash, always provide both `command` and `description` string fields. Do not emit XML-style fallback tool calls.
 
-## Cross-Tool Memory
+## Cross-tool memory
 
-Construct uses cass-memory for cross-tool memory. Start the local HTTP server with `cm serve`, then use `memory_search` to find prior context.
+Construct uses cass-memory for cross-tool memory. Start the local HTTP server with `cm serve`, then `memory_search` to find prior context. Memory and beads are complementary: memory holds knowledge, beads hold tasks.

package/platforms/claude/settings.template.json

@@ -151,7 +151,7 @@
           }
         ],
         "id": "post:edit:comment-lint",
-        "description": "Block edits that violate comment policy (banned patterns, missing required header). Bypass: CONSTRUCT_SKIP_COMMENT_LINT=1"
+        "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",

package/rules/common/beads-hygiene.md

@@ -1,12 +1,6 @@
-<!--
-rules/common/beads-hygiene.md: Beads issue tracker hygiene contract.
-
-Beads is the system of record for durable work in this project. Status drifts
-when issues are not updated alongside the code, so every agent and persona
-operating in Construct treats hygiene as part of the work, not as cleanup.
-Loaded by AGENTS.md, CLAUDE.md, the construct persona, and the engineer /
-operator / planner role overlays.
--->
+---
+description: Beads issue tracker hygiene contract.
+---
 # Beads Hygiene: Project Contract
 
 Beads (`bd`) is the canonical durable tracker for Construct. Beads only earn their keep when their state matches the world. Stale "open" issues pollute `bd ready`, hide real work, and let agents propose work that already shipped. Every agent (human or AI, on any platform) is responsible for keeping the tracker honest.

package/rules/common/code-review.md

@@ -1,9 +1,6 @@
-<!--
-rules/common/code-review.md: when and how to conduct code reviews.
-
-Defines mandatory review triggers, severity levels, approval criteria,
-and references coding-style.md and security.md for checklists.
--->
+---
+description: when and how to conduct code reviews.
+---
 # Code Review Standards
 
 ## When to Review

package/rules/common/coding-style.md

@@ -1,9 +1,6 @@
-<!--
-rules/common/coding-style.md: language-agnostic coding standards.
-
-Covers immutability, core principles (KISS/DRY/YAGNI), file organization,
-error handling, input validation, naming conventions, and quality checklist.
--->
+---
+description: language-agnostic coding standards.
+---
 # Coding Style
 
 ## Immutability (CRITICAL)

package/rules/common/comments.md

@@ -1,10 +1,6 @@
-<!--
-rules/common/comments.md: Construct comment convention for JS/TS/MJS source files.
-
-Defines the two allowed comment forms (file header, section context block) and
-what is never allowed (inline narration, trailing comments, mid-function notes).
-Enforced by lib/hooks/comment-lint.mjs and tests/hooks-budget.test.mjs.
--->
+---
+description: Construct comment convention for JS/TS/MJS source files.
+---
 # Comment Convention
 
 Two forms are allowed. Everything else is deleted.

package/rules/common/commit-approval.md

@@ -1,9 +1,6 @@
-<!--
-rules/common/commit-approval.md: conversational approval rule for mutating git operations.
-
-Behavioral rule, not a hook. The agent asks and waits for a yes; the user
-replies in chat. Infrastructure stays out of the way.
--->
+---
+description: conversational approval rule for mutating git operations.
+---
 # Commit Approval
 
 Construct does not commit, push, or merge without the user explicitly saying yes in the current conversation.

package/rules/common/cx-agent-routing.md

@@ -1,10 +1,6 @@
-<!--
-rules/common/cx-agent-routing.md: auto-trigger routing rules for cx-* specialist agents.
-
-Defines when to route directly to a cx-* specialist vs through Construct orchestration.
-Covers intent-based routing table, complexity gate, and routing rules.
-Loaded by rule-loading systems that look for cx-agent-routing in the rules hierarchy.
--->
+---
+description: auto-trigger routing rules for cx-* specialist agents.
+---
 # cx-* Agent Routing: Auto-trigger Rules
 
 When a request matches the trigger patterns below, automatically route to the corresponding cx-* specialist or persona before responding.

package/rules/common/cx-skill-routing.md

@@ -1,6 +1,6 @@
-<!--
-rules/common/cx-skill-routing.md: Redirect to canonical skill routing table.
--->
+---
+description: Redirect to canonical skill routing table.
+---
 # cx-* Skill Routing
 
 > **Canonical file:** [`skills/routing.md`](../../skills/routing.md)

package/rules/common/doc-ownership.md

@@ -1,11 +1,6 @@
-<!--
-rules/common/doc-ownership.md: which specialist owns which document type.
-
-Prevents the orchestrator (or any general persona) from authoring specialist
-documents directly. Routing authorship to the owning role is how research,
-framing, and domain scrutiny actually fire: writing a PRD without the
-product manager bypasses those checks entirely.
--->
+---
+description: which specialist owns which document type.
+---
 # Document Ownership
 
 A document type names a body of work. That body of work has an owner. The orchestrator routes; it does not author.

package/rules/common/efficiency.md

@@ -1,11 +1,6 @@
-<!--
-rules/common/efficiency.md: session context and tool-use efficiency standards.
-
-Applies to all agents operating in a Construct session. Violations compound context
-cost and reduce throughput. These rules are enforced by read-tracker.mjs and surfaced
-in the session-start efficiency digest.
--->
-
+---
+description: session context and tool-use efficiency standards.
+---
 # Session Efficiency
 
 ## Read discipline

package/rules/common/framing.md

@@ -1,11 +1,6 @@
-<!--
-rules/common/framing.md: how to frame a problem before acting on it.
-
-Establishes the hard separation between execution artifacts (tickets, chat
-transcripts, existing docs) and sources of truth (the underlying problem).
-Applies to every specialist working on architecture, documentation, research,
-product, or strategy work. Read before scaffolding anything.
--->
+---
+description: how to frame a problem before acting on it.
+---
 # Framing Policy
 
 Most agent failures on ambiguous work trace to a single mistake: anchoring on the most concrete input available (usually a ticket or a prior doc) and building the output around its structure instead of around the actual problem.

package/rules/common/git-workflow.md

@@ -1,8 +1,6 @@
-<!--
-rules/common/git-workflow.md: commit message format and PR workflow.
-
-Defines conventional commit types and pull request creation steps.
--->
+---
+description: commit message format and PR workflow.
+---
 # Git Workflow
 
 ## Commit Message Format

package/rules/common/no-fabrication.md

@@ -1,14 +1,6 @@
-<!--
-rules/common/no-fabrication.md: canonical anti-fabrication policy for Construct.
-
-Defines the trust contract between operators and the system: outputs stick to
-source, gaps stay visible, and confidence reflects evidence. Applies to every
-specialist, every artifact, and every summary — intake processing, document
-evaluation, knowledge writing, plan drafting, review verdicts, handoffs.
-
-Sibling rules: research.md (evidence hierarchy), framing.md (execution
-artifacts are not sources), comments.md (banned voice patterns).
--->
+---
+description: canonical anti-fabrication policy for Construct.
+---
 # No-Fabrication Policy
 
 Fabrication is the single largest threat to trust in an agent system. A persona that invents a customer quote, sharpens a vague signal into a confident assertion, or papers over a gap with plausible-sounding prose corrupts every artifact downstream. This rule applies to **every output** Construct produces: intake summaries, classification rationales, PRDs, ADRs, RFCs, knowledge notes, handoffs, review verdicts, plan entries, beads issues, MCP tool responses, dashboard text.
@@ -61,7 +53,7 @@ Fabrication is the single largest threat to trust in an agent system. A persona
 ## Enforcement
 
 - `lib/comment-lint.mjs` enforces a subset of these patterns on artifact paths (`docs/prd/**`, `docs/adr/**`, `docs/rfc/**`, `docs/research/**`, `.cx/knowledge/**`, `.cx/handoffs/**`, `.cx/research/**`). PostToolUse warns; `npm run lint:comments`, `construct lint:comments`, and the release gate block.
-- `specialists/contracts.json` postconditions check structural requirements (mandatory sections, intake traceability, citation density). `lib/contracts/validate.mjs#validateHandoff` blocks handoffs that fail validation when `CONSTRUCT_CONTRACT_ENFORCEMENT=block`.
+- `specialists/contracts.json` postconditions check structural requirements (mandatory sections, intake traceability, citation density). `lib/contracts/validate.mjs#validateHandoff` blocks handoffs that fail validation; binary postconditions in `lib/specialists/postconditions.mjs` block rubber-stamp reviews, post-hoc threat models, symptom-only fixes, stale-doc PRs, and post-hoc accessibility. Enforcement is hard-default `block`.
 - `construct intake done <id> --output=<path>` stamps `intake_id`, `intake_confidence`, and `intake_rationale` into the artifact's frontmatter so every intake-derived artifact carries verifiable provenance.
 
 ## Bypass

package/rules/common/patterns.md

@@ -1,8 +1,6 @@
-<!--
-rules/common/patterns.md: reusable design patterns and skeleton project strategy.
-
-Covers skeleton project evaluation, repository pattern, and API response format.
--->
+---
+description: reusable design patterns and skeleton project strategy.
+---
 # Common Patterns
 
 ## Skeleton Projects

package/rules/common/release-gates.md

@@ -1,11 +1,6 @@
-<!--
-rules/common/release-gates.md: Hard release gates for Construct work.
-
-Defines the blocking contracts every agent and persona must satisfy locally
-before any commit, push, or "done" claim. Loaded by the construct persona,
-AGENTS.md, and the engineer/reviewer/operator role overlays. Enforcement is at
-the prompt level: CI is a backstop, not the primary gate.
--->
+---
+description: Hard release gates for Construct work.
+---
 # Release Gates: Hard Contracts
 
 These are blocking gates. Every agent, persona, and harness session working in or shipping Construct must satisfy them locally **before** any commit, push, or "done" claim. CI is a backstop, not the primary check.

package/rules/common/research.md

@@ -1,11 +1,6 @@
-<!--
-rules/common/research.md: canonical research and evidence policy for Construct.
-
-Defines how research starts, which sources to prefer, how claims are verified,
-and what must be recorded so findings are reproducible. Applies to research,
-product evidence synthesis, document ingest follow-up, and any recommendation
-that depends on external facts or evolving internal evidence.
--->
+---
+description: canonical research and evidence policy for Construct.
+---
 # Research Policy
 
 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.

package/rules/common/review-before-change.md

@@ -1,11 +1,6 @@
-<!--
-rules/common/review-before-change.md: audit the current state before authoring anything new.
-
-Applies to every specialist on every platform. Pairs with framing.md (frame the
-problem) and development-workflow.md step 0 (research and reuse before code).
-This rule extends the same discipline to artifacts: docs, strategy, PRDs, ADRs,
-RFCs, rules, templates, and any other durable file. Read before scaffolding.
--->
+---
+description: audit the current state before authoring anything new.
+---
 # Review Before Change
 
 Before creating or rewriting a durable artifact, check what already exists.
@@ -54,5 +49,4 @@ For artifacts that go through a review cycle (strategy, PRD, ADR, RFC), the fram
 ## Related
 
 - `rules/common/framing.md`: frame the underlying problem before reaching for inputs.
-- `rules/common/development-workflow.md`: step 0 covers the same discipline for code.
 - `rules/common/doc-ownership.md`: which specialist owns which artifact type.

package/rules/common/security.md

@@ -1,9 +1,6 @@
-<!--
-rules/common/security.md: mandatory security checks and secret management.
-
-Defines pre-commit security checklist, secret management rules,
-and response protocol for discovered vulnerabilities.
--->
+---
+description: mandatory security checks and secret management.
+---
 # Security Guidelines
 
 ## Mandatory Security Checks

package/rules/common/skill-composition.md

@@ -1,10 +1,6 @@
-<!--
-rules/common/skill-composition.md: how specialist prompts compose with skill files.
-
-Defines the default boundary between what lives in the agent's base prompt and
-what is fetched via `get_skill` at runtime. Aims to keep prompts lean while
-keeping domain knowledge reliably available when needed.
--->
+---
+description: how specialist prompts compose with skill files.
+---
 # Skill Composition Policy
 
 Specialist agent prompts are lean on purpose. Domain depth lives in skill files and is pulled in on demand, not pre-inlined.

package/rules/common/testing.md

@@ -1,9 +1,6 @@
-<!--
-rules/common/testing.md: test coverage requirements and TDD workflow.
-
-Defines minimum 80% coverage, TDD red-green-refactor cycle,
-AAA test structure, and descriptive naming conventions.
--->
+---
+description: test coverage requirements and TDD workflow.
+---
 # Testing Requirements
 
 ## Minimum Test Coverage: 80%

package/rules/golang/coding-style.md

@@ -1,9 +1,5 @@
-<!--
-rules/golang/coding-style.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct golang coding style rule. Applies to files matching **/*.go, **/go.mod, **/go.sum. Use when writing or reviewing golang code that involves coding style.
 paths:
   - "**/*.go"
   - "**/go.mod"

package/rules/golang/hooks.md

@@ -1,9 +1,5 @@
-<!--
-rules/golang/hooks.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct golang hooks rule. Applies to files matching **/*.go, **/go.mod, **/go.sum. Use when writing or reviewing golang code that involves hooks.
 paths:
   - "**/*.go"
   - "**/go.mod"

package/rules/golang/patterns.md

@@ -1,9 +1,5 @@
-<!--
-rules/golang/patterns.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct golang patterns rule. Applies to files matching **/*.go, **/go.mod, **/go.sum. Use when writing or reviewing golang code that involves patterns.
 paths:
   - "**/*.go"
   - "**/go.mod"

package/rules/golang/security.md

@@ -1,9 +1,5 @@
-<!--
-rules/golang/security.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct golang security rule. Applies to files matching **/*.go, **/go.mod, **/go.sum. Use when writing or reviewing golang code that involves security.
 paths:
   - "**/*.go"
   - "**/go.mod"

package/rules/golang/testing.md

@@ -1,9 +1,5 @@
-<!--
-rules/golang/testing.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct golang testing rule. Applies to files matching **/*.go, **/go.mod, **/go.sum. Use when writing or reviewing golang code that involves testing.
 paths:
   - "**/*.go"
   - "**/go.mod"

package/rules/python/coding-style.md

@@ -1,9 +1,5 @@
-<!--
-rules/python/coding-style.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct python coding style rule. Applies to files matching **/*.py, **/*.pyi. Use when writing or reviewing python code that involves coding style.
 paths:
   - "**/*.py"
   - "**/*.pyi"

package/rules/python/hooks.md

@@ -1,9 +1,5 @@
-<!--
-rules/python/hooks.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct python hooks rule. Applies to files matching **/*.py, **/*.pyi. Use when writing or reviewing python code that involves hooks.
 paths:
   - "**/*.py"
   - "**/*.pyi"

package/rules/python/patterns.md

@@ -1,9 +1,5 @@
-<!--
-rules/python/patterns.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct python patterns rule. Applies to files matching **/*.py, **/*.pyi. Use when writing or reviewing python code that involves patterns.
 paths:
   - "**/*.py"
   - "**/*.pyi"

package/rules/python/security.md

@@ -1,9 +1,5 @@
-<!--
-rules/python/security.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct python security rule. Applies to files matching **/*.py, **/*.pyi. Use when writing or reviewing python code that involves security.
 paths:
   - "**/*.py"
   - "**/*.pyi"

package/rules/python/testing.md

@@ -1,9 +1,5 @@
-<!--
-rules/python/testing.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct python testing rule. Applies to files matching **/*.py, **/*.pyi. Use when writing or reviewing python code that involves testing.
 paths:
   - "**/*.py"
   - "**/*.pyi"

package/rules/swift/coding-style.md

@@ -1,9 +1,5 @@
-<!--
-rules/swift/coding-style.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct swift coding style rule. Applies to files matching **/*.swift, **/Package.swift. Use when writing or reviewing swift code that involves coding style.
 paths:
   - "**/*.swift"
   - "**/Package.swift"

package/rules/swift/hooks.md

@@ -1,9 +1,5 @@
-<!--
-rules/swift/hooks.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: "Flag `print()` statements: use `os.Logger` or structured logging instead for production code."
 paths:
   - "**/*.swift"
   - "**/Package.swift"

package/rules/swift/patterns.md

@@ -1,9 +1,5 @@
-<!--
-rules/swift/patterns.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct swift patterns rule. Applies to files matching **/*.swift, **/Package.swift. Use when writing or reviewing swift code that involves patterns.
 paths:
   - "**/*.swift"
   - "**/Package.swift"

package/rules/swift/security.md

@@ -1,9 +1,5 @@
-<!--
-rules/swift/security.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct swift security rule. Applies to files matching **/*.swift, **/Package.swift. Use when writing or reviewing swift code that involves security.
 paths:
   - "**/*.swift"
   - "**/Package.swift"

package/rules/swift/testing.md

@@ -1,9 +1,5 @@
-<!--
-rules/swift/testing.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct swift testing rule. Applies to files matching **/*.swift, **/Package.swift. Use when writing or reviewing swift code that involves testing.
 paths:
   - "**/*.swift"
   - "**/Package.swift"

package/rules/typescript/coding-style.md

@@ -1,9 +1,5 @@
-<!--
-rules/typescript/coding-style.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct typescript coding style rule. Applies to files matching **/*.ts, **/*.tsx, **/*.js, **/*.jsx. Use when writing or reviewing typescript code that involves coding style.
 paths:
   - "**/*.ts"
   - "**/*.tsx"

package/rules/typescript/hooks.md

@@ -1,9 +1,5 @@
-<!--
-rules/typescript/hooks.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct typescript hooks rule. Applies to files matching **/*.ts, **/*.tsx, **/*.js, **/*.jsx. Use when writing or reviewing typescript code that involves hooks.
 paths:
   - "**/*.ts"
   - "**/*.tsx"

package/rules/typescript/patterns.md

@@ -1,9 +1,5 @@
-<!--
-rules/typescript/patterns.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct typescript patterns rule. Applies to files matching **/*.ts, **/*.tsx, **/*.js, **/*.jsx. Use when writing or reviewing typescript code that involves patterns.
 paths:
   - "**/*.ts"
   - "**/*.tsx"

package/rules/typescript/security.md

@@ -1,9 +1,5 @@
-<!--
-rules/typescript/security.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct typescript security rule. Applies to files matching **/*.ts, **/*.tsx, **/*.js, **/*.jsx. Use when writing or reviewing typescript code that involves security.
 paths:
   - "**/*.ts"
   - "**/*.tsx"

package/rules/typescript/testing.md

@@ -1,9 +1,5 @@
-<!--
-rules/typescript/testing.md: <one-line purpose>
-
-<2–6 line summary.>
--->
 ---
+description: Construct typescript testing rule. Applies to files matching **/*.ts, **/*.tsx, **/*.js, **/*.jsx. Use when writing or reviewing typescript code that involves testing.
 paths:
   - "**/*.ts"
   - "**/*.tsx"

package/rules/web/coding-style.md

@@ -1,8 +1,6 @@
-<!--
-rules/web/coding-style.md: <one-line purpose>
-
-<2–6 line summary.>
--->
+---
+description: Construct web coding style rule. Use when writing or reviewing web code that involves coding style.
+---
 > This file extends [common/coding-style.md](../common/coding-style.md) with web-specific frontend content.
 
 # Web Coding Style