@geraldmaron/construct 1.0.12 → 1.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.12",
+  "version": "1.0.15",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
@@ -27,6 +27,10 @@
   "engines": {
     "node": ">=20"
   },
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
@@ -42,7 +46,7 @@
   "scripts": {
     "mcp": "node lib/mcp/server.mjs",
     "test": "node scripts/run-tests.mjs",
-    "test:functional": "node --test --test-timeout=30000 tests/functional/*.functional.test.mjs",
+    "test:functional": "node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
     "test:unit": "node scripts/run-tests.mjs --exclude=tests/functional",
     "docs:init": "node lib/init-docs.mjs --yes",
     "docs:update": "node ./bin/construct docs:update",
@@ -53,7 +57,6 @@
     "lint:contracts": "node ./bin/construct lint:contracts",
     "lint:agents": "node ./bin/construct lint:agents",
     "build:sea": "esbuild bin/construct --bundle --platform=node --target=node20 --packages=external --outfile=dist/construct-bundle.cjs 2>&1 || (echo 'esbuild not found — install with: npm install -g esbuild' && exit 1)",
-    "lint:prose": "node scripts/lint-prose.mjs",
     "lint:profiles": "node scripts/lint-profiles.mjs",
     "learning:status": "node scripts/learning-status.mjs",
     "lint:templates": "node scripts/lint-commits-pr.mjs",
@@ -69,16 +72,17 @@
     "@huggingface/transformers": "^4.2.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "@xenova/transformers": "^2.0.1",
+    "js-yaml": "^4.2.0",
     "node-webvtt": "^1.9.3",
     "postgres": "^3.4.9"
   },
   "optionalDependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-trace-node": "^1.25.0",
+    "@opentelemetry/core": "^1.25.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",
     "@opentelemetry/resources": "^1.25.0",
-    "@opentelemetry/semantic-conventions": "^1.25.0",
-    "@opentelemetry/core": "^1.25.0"
+    "@opentelemetry/sdk-trace-node": "^1.25.0",
+    "@opentelemetry/semantic-conventions": "^1.25.0"
   },
   "overrides": {
     "express-rate-limit": "8.5.1",

package/personas/construct.md

@@ -1,10 +1,7 @@
-<!--
-personas/construct.md. Construct persona prompt.
-
-Defines the single user-facing AI interface and its session-start behavior,
-routing rules, approval boundaries, and output contract. Loaded by sync-specialists
-and emitted to every supported platform.
--->
+---
+name: construct
+description: Construct persona prompt.
+---
 You are Construct. The user talks only to you; internal routing and specialist dispatch are implementation detail.
 
 **Anti-fabrication contract**: every load-bearing claim cites a verifiable source. Missing source becomes `unknown` or `[unverified]`. Specialists tailor; the persona never weakens. See `rules/common/no-fabrication.md`.

package/platforms/claude/settings.template.json

@@ -14,19 +14,7 @@
           }
         ],
         "id": "session:start",
-        "description": "Load prior project context and git status at session start"
-      },
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/env-check.mjs\"",
-            "timeout": 5
-          }
-        ],
-        "id": "session:env-check",
-        "description": "Warn about missing required env vars at session open"
+        "description": "Load prior project context, git status, and missing-env-var notice at session start"
       }
     ],
     "PreToolUse": [
@@ -163,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",
@@ -215,19 +203,6 @@
         "id": "post:edit:dep-audit",
         "description": "Audit dependencies for vulnerabilities after manifest changes"
       },
-      {
-        "matcher": "Read",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/read-tracker.mjs\"",
-            "timeout": 3,
-            "async": true
-          }
-        ],
-        "id": "post:read-tracker",
-        "description": "Record file content hash after Read for staleness detection in edit-guard"
-      },
       {
         "matcher": "Read",
         "hooks": [
@@ -239,7 +214,7 @@
           }
         ],
         "id": "post:audit-reads",
-        "description": "Tamper-evident chain log of every Read tool call. Off by default — enable with CONSTRUCT_AUDIT_READS=1."
+        "description": "Update file-hashes.json for edit-guard staleness detection on every Read; optionally write a tamper-evident audit chain when CONSTRUCT_AUDIT_READS=1."
       },
       {
         "matcher": "mcp__.*",
@@ -305,6 +280,19 @@
         "id": "post:bash:post-merge-docs-check",
         "description": "Emit doc-drift events when a merge lands without matching docs/CHANGELOG updates"
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/post-merge-tracking.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ],
+        "id": "post:bash:post-merge-tracking",
+        "description": "After `gh pr merge` succeeds, parse the PR body's Refs/Closes/Fixes lines and close every referenced construct-XXX bead so plan.md and .cx/context.md don't drift behind merged work"
+      },
       {
         "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash",
         "hooks": [
@@ -473,6 +461,19 @@
         ],
         "id": "stop:auto-reflect",
         "description": "Deterministic session-end reflect: extracts a transcript summary into .cx/observations (500ms hard budget; CONSTRUCT_REFLECT_AUTO=off to disable)"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/session-tracking-refresh.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ],
+        "id": "stop:tracking-refresh",
+        "description": "Auto-refresh .cx/context.{md,json} from recent observations + commits + closed beads; sync plan.md bead-status table; archive plan.md to .cx/handoffs/ when all referenced beads are closed"
       }
     ],
     "UserPromptSubmit": [

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"