@geraldmaron/construct 1.0.0 → 1.0.1

package/skills/operating/orchestration-reference.md

@@ -0,0 +1,151 @@
+<!--
+skills/operating/orchestration-reference.md — detailed orchestration reference loaded on demand.
+
+Holds the execution contract, handoff template, intent and work-category
+classification, parallel dispatch, horizontal routing, and efficiency
+discipline. Called via get_skill("operating/orchestration-reference") by
+specialists and personas when they need the full context; short essentials
+stay in sharedGuidance so they load every turn.
+-->
+
+# Orchestration Reference
+
+Loaded on demand via `get_skill("operating/orchestration-reference")`.
+
+This is the detailed reference for Construct's orchestration contract. The short essentials (session resumption, loop guard, terminal states, tool naming, observability) live in the per-agent prompt. Everything below is situational — load it when you hit a case it addresses.
+
+## System model
+
+Construct is the underlying orchestration system for the **current project**. Treat personas as phase owners, specialists as bounded workers, skills as execution playbooks, hooks as enforcement, `.cx/workflow.json` as the durable cross-task workflow ledger, `.cx/task-graphs/<id>.json` as the per-signal execution plans derived from R&D intake triage, and memory / .cx artifacts as persistent project state.
+
+The two task-shaped surfaces are siblings, not duplicates:
+
+- **`.cx/workflow.json`** — single project-wide workflow file. Holds the cross-cutting task ledger and intent / category metadata. Drives `workflow_status` and `project_context` MCP tools.
+- **`.cx/task-graphs/<id>.json`** — per-incoming-signal plan generated by `construct graph from-intake <intake-id>`. One graph per triaged inbox file, one node per persona in the recommendedChain, evidence records gating `done`. See [Concepts → Intake and triage](/concepts/intake-and-triage).
+
+A signal that becomes durable cross-session work crosses over: the graph nodes are executed, the resulting work is tracked in `.cx/workflow.json` and in beads. The intake queue and task graphs are how new signals enter the loop; the workflow ledger and beads are how durable work is carried.
+
+## Perspective architecture
+
+Each specialist carries a distinct cognitive profile shaped by professional prior, characteristic suspicion, and productive tension with adjacent roles. When you dispatch specialists, you are not delegating tasks — you are assembling perspectives. The value is not parallelism; it is forcing the same problem through genuinely different cognitive lenses in sequence. A plan challenged by cx-devil-advocate and reviewed by cx-reviewer is not slower — it is more likely to survive contact with reality.
+
+## Execution contract
+
+For every non-trivial task: classify intent, create or update `.cx/workflow.json`, route to the owning persona or specialist, execute with the relevant skill, dispatch independent work in parallel when supported, persist decisions/handoffs to memory or `.cx`, validate through the validation phase before release.
+
+### Intent classes
+
+- `research` — read-only investigation
+- `implementation` — code changes
+- `investigation` — debugging, tracing
+- `evaluation` — quality gates, review
+- `fix` — bug repair
+
+Tag every workflow task with its intent class. Let intent drive agent selection and depth of work.
+
+### Work categories
+
+- `visual` (UI/CSS/design) → standard tier
+- `deep` (complex reasoning, architecture) → reasoning tier
+- `quick` (single-file, trivial) → fast tier
+- `writing` (docs, prose) → fast tier
+- `analysis` (data, metrics, review) → standard tier
+
+## Workflow state
+
+Task packets include an optional `mcpScope` field: list MCP server names relevant to this task (e.g. `["github", "context7"]`). The mcp-task-scope hook warns when out-of-scope MCPs are called. The mcp-audit hook records all MCP usage per task key to `.cx/mcp-audit.json`.
+
+Every delegated task needs a stable `TASK_KEY`, `phase`, `owner`, `status`, `readFirst`, `doNotChange`, `acceptanceCriteria`, and `verification` evidence before done. Run `construct workflow align` at phase transitions.
+
+## Native surfaces
+
+Use native skills, plugins, slash commands, MCP tools, and project instructions when they exist and match the task. Agents define role, judgment, and handoffs; skills are the execution playbooks.
+
+If a native skill or project instruction conflicts with this registry, obey the higher-priority system, tool, and repository instructions. Surface the conflict, the decision made, and any follow-up needed.
+
+Do not duplicate skill internals inside agent prompts. Reference the relevant skill or workflow, then apply it to the current context.
+
+## Agent-to-agent service contracts
+
+Every producer→consumer pair has an explicit contract in `agents/contracts.json`, loaded via `lib/agent-contracts.mjs`. Specialists call the MCP tool `agent_contract` at the start of a handoff to see:
+
+- `input.mustContain` — fields the packet must carry
+- `input.schema` — JSON schema (when applicable) from `lib/schemas/`
+- `preconditions` — what must be true before work starts
+- `output.schema` / `output.shape` — expected return shape
+- `postconditions` — what must be true before marking DONE
+
+Examples of contracts (full list in `agents/contracts.json`):
+
+- `researcher-to-architect` — research brief with ≥2 primary sources → decision
+- `product-manager-to-architect` — PRD handoff → decision with Rejected alternatives
+- `architect-to-devil-advocate` — framing proposal → challenge report (blocks if framing is weak)
+- `architect-to-engineer` — decision → implementation
+- `engineer-to-reviewer` — implementation → review verdict
+- `engineer-to-qa` — implementation → test report
+- `reviewer-to-security` — review with auth/secrets scope → specialized security review
+- `any-to-docs-keeper` — any DONE mutation that changed core docs → doc sync
+
+`routeRequest` returns a `contractChain` that enumerates which of these fire for a given request. Honor the chain — missing a contract stage is the signal a handoff is incomplete.
+
+## Legacy handoff contract (fallback)
+
+When a contract isn't registered for a specific pair, fall back to this minimum:
+
+- **TASK** (one atomic goal)
+- **EXPECTED OUTCOME** (deliverable + acceptance signal)
+- **REQUIRED TOOLS**
+- **MUST DO** (exhaustive)
+- **MUST NOT DO** (anticipate drift)
+- **CONTEXT** (files, decisions, constraints)
+- **READ FIRST**
+- **DO NOT CHANGE**
+
+Missing required fields mean the handoff is incomplete.
+
+## Primary persona contract
+
+Personas own user interaction. When a worker returns `NEEDS_MAIN_INPUT`, ask the question in the main session, update `.cx/workflow.json` to `blocked_needs_user`, then resume or re-dispatch the worker after the user answers.
+
+## Parallel dispatch
+
+When two or more specialists can work independently, write `[parallel: cx-agent-a, cx-agent-b]` before the handoff list and give each agent a disjoint scope. Do not mark dependent work as parallel.
+
+## Horizontal routing
+
+When your output directly feeds another specialist (e.g. security findings → cx-reviewer, architecture decisions → cx-engineer), write a handoff entity to the memory MCP using `create_entities` with name `handoff:{target-agent}` and `add_observations` with the payload: `{ from, goal, key_findings, files, constraints }`. The target specialist calls `search_nodes 'handoff:{my-agent-name}'` before starting work.
+
+## Context & efficiency (enforced)
+
+These are enforced by hooks, not advisory:
+
+- `context-watch` hook (UserPromptSubmit) injects compaction guidance at ~60% / ~80% of the context window.
+- `repeated-read-guard` hook (PreToolUse on Read) blocks broad re-reads of files already read twice in this session — steers to Grep or offset+limit.
+- `bash-output-logger` hook (PostToolUse on Bash) persists outputs >4KB to `~/.cx/bash-logs/` and tells the model to grep the log rather than re-run.
+
+Advisory companions:
+
+- Use `Grep` and `Glob` to narrow scope before `Read`.
+- Prefer targeted reads under 400 lines.
+- Probe file size before bulk reads: `Glob`, `wc -l`, or a `limit=50` probe.
+- Keep response summaries under 100 words unless the user asks for more detail.
+
+## Deliberation cap
+
+If you reason about the same decision across two consecutive turns without a new file read, tool call, or user answer, stop. Either (a) call a doc/search tool, (b) return a `NEEDS_MAIN_INPUT` packet, or (c) commit to a default and note the assumption. Never a third round of internal debate.
+
+## Speculation rule
+
+When choosing between named options (SDK vs SDK, library vs library, pattern vs pattern), the answer comes from `context7_query-docs`, `WebFetch`, the user, or an explicit default — never from internal reasoning rounds alone.
+
+## Dispatch-first test
+
+If work touches 3+ files across 2+ modules, or introduces a new contract/dependency/SDK, the persona must not produce the implementation plan itself — dispatch cx-architect. In-persona implementation planning for complex work is the primary failure mode this rule exists to prevent.
+
+## Executive communication
+
+Treat the user as the Customer and Executive. Proactive reporting on status, immediate escalation of strategic blockers, seeking input on all user-facing changes (UX/UI). When in doubt, clarify intent rather than assuming a product decision.
+
+## Comment hygiene
+
+Avoid pointless comments. Comment only for intent, invariants, non-obvious constraints, or operationally critical decisions.

package/skills/roles/architect.md

@@ -1,6 +1,11 @@
 <!--
 skills/roles/architect.md — Anti-pattern guidance for the Architect role.
 
+## Improvement Note (auto-generated 2026-04-29)
+- Improve specificity in technical guidance; provide detailed steps or code snippets rather than vague suggestions.
+- Ensure that responses directly address the user's request; avoid unrelated topics or general advice that doesn't pertain to the task.
+- Incorporate thorough explanations for any proposed solutions or changes to clarify their importance and methodology.
+
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the architect domain and counter-moves to avoid them.
 Applies to: cx-architect, cx-rd-lead.

package/skills/roles/engineer.md

@@ -83,3 +83,35 @@ Load this before drafting. These are the failure modes that separate strong role
 - [ ] Diff is narrow and on-topic
 - [ ] No more than two consecutive thinking turns about the same decision without a tool call or input
 - [ ] Any `Read` over 200 lines was preceded by a size probe
+
+## Hard release gates (blocking, run locally — never push and pray)
+
+Run all four before declaring work done. CI is a backstop, not the primary gate. See `rules/common/release-gates.md`.
+
+- [ ] `npm test` — 0 failed
+- [ ] `node bin/construct lint:comments` — 0 errors AND 0 warnings
+- [ ] `node bin/construct docs:verify` — all checks passed, no warnings
+- [ ] `node bin/construct docs:update --check` — AUTO regions clean
+- [ ] `npm run lint:templates` — commit subjects + PR body match templates
+
+Shortcut: `npm run release:check`.
+
+## Tracker + docs contract
+
+- [ ] Beads issue exists for this change (`bd ready`/`bd show <id>`/`bd update <id> --claim`)
+- [ ] `plan.md` reflects the change (mark done, add new rows, remove stale)
+- [ ] `docs/architecture.md` updated if runtime shape, contracts, or boundaries changed
+- [ ] `docs/README.md` updated if the docs surface or maintenance contract changed
+- [ ] `.cx/context.md` and `.cx/context.json` updated if active work, decisions, or assumptions changed
+- [ ] `CHANGELOG.md` has an entry
+- [ ] `bd close <id>` happens after CI is green, not before
+
+
+## Learned Patterns
+
+### L1. Read file and callers before changing
+**Context**: General
+**Effective Action**: Before modifying a function, read the full file and grep for callers with `grep -r 'functionName' src/`...
+**Evidence**: Score 0.89, used 8 times, 2 projects
+*Last reinforced: 2026-05-04*
+

package/skills/roles/operator.md

@@ -52,10 +52,21 @@ Load this before producing operator output — SRE, ops, release, and durable-kn
 **Counter-move**: every non-trivial release has a changelog entry, a rollback plan, and a comms channel notified.
 
 ### 8. Unbounded retries
+
 **Symptom**: failures retried forever or with naive backoff; retries hide underlying capacity issues.
+
 **Why it fails**: retry storms amplify outages. A transient failure becomes a full incident.
+
 **Counter-move**: bounded retries. Exponential backoff with jitter. Circuit breakers on downstream dependencies.
 
+### 9. Execution gap blindness
+
+**Symptom**: strategy/PRDs/RFCs document what should be built, but Jira tickets don't reflect the full scope. Work drifts without detection.
+
+**Why it fails**: no systematic comparison between planned work (documents) and actual work (tickets). Gaps accumulate silently until delivery dates slip.
+
+**Counter-move**: run periodic gap analysis: query strategy/PRDs/RFCs from knowledge base, compare with Jira tickets via search, identify missing tickets. Create补缺 tickets automatically (or queue for approval). Treat "execution gap" as a first-class risk signal.
+
 ## Self-check before shipping
 
 - [ ] Each runbook step names its purpose and expected output
@@ -66,3 +77,4 @@ Load this before producing operator output — SRE, ops, release, and durable-kn
 - [ ] Operational docs have a last-tested or last-reviewed date
 - [ ] Every release has a changelog, rollback, and comms plan
 - [ ] Retries are bounded; circuit breakers protect dependencies
+- [ ] Execution gaps between strategy/PRDs/RFCs and Jira tickets are detected and closed

package/skills/roles/reviewer.md

@@ -66,3 +66,26 @@ Load this before drafting. These are the failure modes that separate strong role
 - [ ] New behavior has a test that would catch its regression
 - [ ] High-risk domains (auth, payments, data) explicitly scrutinized
 - [ ] Rewrote only when asked; otherwise described the issue
+
+## Hard release gates (block approval if any fail)
+
+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
+
+See `rules/common/release-gates.md`. Block approval until evidence is in the PR body.
+
+## Tracker + docs contract
+
+Reject a change that ships code without the matching documentation update. Specifically check:
+
+- [ ] Beads issue exists and is linked
+- [ ] `plan.md` reflects the change
+- [ ] `docs/architecture.md` updated when runtime shape, contracts, or boundaries changed
+- [ ] `docs/README.md` updated when the docs surface or maintenance contract changed
+- [ ] `.cx/context.md` and `.cx/context.json` updated when active work, decisions, or assumptions changed
+- [ ] `CHANGELOG.md` has an entry that names what changed and why

package/skills/routing.md

@@ -59,7 +59,7 @@ Read the matching skill file before responding when the user's request matches t
 | workflow state, orchestration state, task key, handoff contract, phase gate, project alignment | `skills/ai/orchestration-workflow.md` | Construct-style workflow state and phase alignment |
 | LLM security, prompt injection, jailbreak, guardrail | `skills/ai/llm-security.md` | LLM security and guardrails |
 | prompt engineering, model evaluation, benchmark, fine-tuning | `skills/ai/prompt-and-eval.md` | Prompt engineering and evaluation |
-| prompt optimization, improve prompt, optimize agent, quality score, staging prompt, promotion | `skills/ai/prompt-optimizer.md` | Closed-loop prompt auto-optimization via Langfuse traces |
+| prompt optimization, improve prompt, optimize agent, quality score, staging prompt, promotion | `skills/ai/prompt-optimizer.md` | Closed-loop prompt auto-optimization via telemetry traces |
 | MLOps, ML pipeline, model registry, model deployment, feature store, drift detection, model monitoring, training pipeline | `skills/ai/ml-ops.md` | ML operations and model lifecycle |
 
 ## DevOps Domain

package/templates/devcontainer/Dockerfile.devcontainer

@@ -0,0 +1,38 @@
+# Dockerfile.devcontainer — development container for Construct projects.
+#
+# This is NOT the production image (see Dockerfile in the project root).
+# It bundles a full Node.js dev environment + Construct pre-installed so
+# any team member can open the project in VS Code / Codespaces and have
+# a working Construct environment without any host-side setup.
+#
+# Usage via construct init --devcontainer:
+#   - Copies this file + devcontainer.json into .devcontainer/
+#   - Commits both files; teammates open the project and VS Code prompts to
+#     "Reopen in Container"
+
+ARG NODE_VERSION=22
+ARG CONSTRUCT_VERSION=latest
+
+FROM node:${NODE_VERSION}-bookworm-slim
+
+# Install system deps for development (git, curl, docker CLI for resource spinup)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      git curl ca-certificates gnupg \
+    && curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /usr/share/keyrings/docker.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker.gpg] \
+        https://download.docker.com/linux/debian bookworm stable" \
+        > /etc/apt/sources.list.d/docker.list \
+    && apt-get update && apt-get install -y --no-install-recommends docker-ce-cli \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Install Construct globally so `construct` command is available everywhere.
+# The version is pinned by the ARG so the container is reproducible.
+RUN npm install -g @geraldmaron/construct@${CONSTRUCT_VERSION}
+
+# Pre-warm npx cache so the first `npx construct` is instant.
+RUN npx --yes @geraldmaron/construct@${CONSTRUCT_VERSION} --version 2>/dev/null || true
+
+WORKDIR /workspace
+
+# Project files are bind-mounted at runtime; this just ensures the dir exists.
+CMD ["bash"]

package/templates/devcontainer/devcontainer.json

@@ -0,0 +1,31 @@
+{
+  "name": "Construct Dev",
+  "build": {
+    "dockerfile": "Dockerfile.devcontainer",
+    "context": ".."
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/git:1": {},
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+  },
+  "forwardPorts": [4242],
+  "portsAttributes": {
+    "4242": {
+      "label": "Construct Dashboard",
+      "onAutoForward": "notify"
+    }
+  },
+  "postCreateCommand": "node .construct/run.mjs setup --auto",
+  "remoteEnv": {
+    "CONSTRUCT_VERSION": "${localEnv:CONSTRUCT_VERSION}",
+    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": ["anthropic.claude-code"],
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "bash"
+      }
+    }
+  }
+}

package/templates/distribution/bootstrap.ps1

@@ -0,0 +1,142 @@
+# .construct/bootstrap.ps1 — Windows PowerShell bootstrap shim.
+#
+# Usage:
+#   powershell -ExecutionPolicy Bypass -File .construct\bootstrap.ps1                   # probe + plan
+#   powershell -ExecutionPolicy Bypass -File .construct\bootstrap.ps1 -Install          # ensure runtime
+#   powershell -ExecutionPolicy Bypass -File .construct\bootstrap.ps1 -- <args…>        # invoke with args
+#
+# Mirrors bootstrap.sh: same resolution order (node_modules → npx → global →
+# cached binary → docker → fail). Forwards every argument and stream.
+
+[CmdletBinding()]
+param(
+  [switch]$Install,
+  [Parameter(ValueFromRemainingArguments=$true)]
+  [string[]]$ConstructArgs
+)
+
+$ErrorActionPreference = 'Stop'
+
+$ScriptDir   = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectRoot = Resolve-Path (Join-Path $ScriptDir '..')
+$VersionFile = Join-Path $ScriptDir 'version'
+$CacheBinDir = Join-Path $ScriptDir 'cache\bin'
+
+$Version = ''
+if (Test-Path $VersionFile) {
+  $Version = (Get-Content $VersionFile -Raw).Trim()
+}
+
+function Test-NodeMin18 {
+  if (-not (Get-Command node -ErrorAction SilentlyContinue)) { return $false }
+  $v = (node --version) -replace '^v',''
+  $major = [int]($v.Split('.')[0])
+  return ($major -ge 18)
+}
+
+function Resolve-Arch {
+  switch ($env:PROCESSOR_ARCHITECTURE) {
+    'AMD64' { return 'x64' }
+    'ARM64' { return 'arm64' }
+    default { return '' }
+  }
+}
+
+function Invoke-NodeModules {
+  param([string[]]$Args)
+  $bin = Join-Path $ProjectRoot 'node_modules\@geraldmaron\construct\bin\construct'
+  if (-not (Test-Path $bin)) { return $false }
+  & node $bin @Args
+  exit $LASTEXITCODE
+}
+
+function Invoke-Npx {
+  param([string[]]$Args)
+  if (-not (Test-NodeMin18)) { return $false }
+  if (-not (Get-Command npx -ErrorAction SilentlyContinue)) { return $false }
+  $spec = if ($Version) { "@geraldmaron/construct@$Version" } else { '@geraldmaron/construct' }
+  & npx -p $spec -- construct @Args
+  exit $LASTEXITCODE
+}
+
+function Invoke-Global {
+  param([string[]]$Args)
+  if (-not (Get-Command construct -ErrorAction SilentlyContinue)) { return $false }
+  & construct @Args
+  exit $LASTEXITCODE
+}
+
+function Invoke-CachedBinary {
+  param([string[]]$Args)
+  $arch = Resolve-Arch
+  if (-not $arch) { return $false }
+  $bin = Join-Path $CacheBinDir "construct-windows-$arch.exe"
+  if (-not (Test-Path $bin)) { return $false }
+  & $bin @Args
+  exit $LASTEXITCODE
+}
+
+function Invoke-Docker {
+  param([string[]]$Args)
+  if (-not (Get-Command docker -ErrorAction SilentlyContinue)) { return $false }
+  $image = 'ghcr.io/geraldmaron/construct'
+  if ($Version) { $image = "${image}:$Version" } else { $image = "${image}:latest" }
+  & docker run --rm `
+    -v "${ProjectRoot}:/work" -w /work `
+    -v "$env:USERPROFILE\.construct:/data/.construct" `
+    -e CONSTRUCT_PROJECT_ROOT=/work `
+    $image @Args
+  exit $LASTEXITCODE
+}
+
+if ($Install) {
+  $bin = Join-Path $ProjectRoot 'node_modules\@geraldmaron\construct\bin\construct'
+  if (Test-Path $bin) {
+    Write-Host "[construct] node_modules install ready: $bin"
+    exit 0
+  }
+  if ((Test-NodeMin18) -and (Get-Command npx -ErrorAction SilentlyContinue)) {
+    Write-Host '[construct] npx will resolve construct on first invocation.'
+    exit 0
+  }
+  if (Get-Command docker -ErrorAction SilentlyContinue) {
+    Write-Host '[construct] docker available — bootstrap will use the container image on next run.'
+    exit 0
+  }
+  $arch = Resolve-Arch
+  if ($arch -and $Version -and (Get-Command curl -ErrorAction SilentlyContinue)) {
+    $url = "https://github.com/geraldmaron/construct/releases/download/v$Version/construct-windows-$arch.exe"
+    New-Item -ItemType Directory -Force -Path $CacheBinDir | Out-Null
+    $target = Join-Path $CacheBinDir "construct-windows-$arch.exe"
+    Write-Host "[construct] downloading binary to $target…"
+    try {
+      Invoke-WebRequest -Uri $url -OutFile $target -UseBasicParsing
+      Write-Host '[construct] binary cached. Subsequent invocations use it.'
+      exit 0
+    } catch {
+      Write-Host "[construct] binary download failed; falling through."
+    }
+  }
+  Write-Error '[construct] No installable runtime detected. Install Node.js 18+, Docker, or curl + a release binary.'
+  exit 127
+}
+
+# Default — resolve and invoke.
+try { Invoke-NodeModules    $ConstructArgs } catch {}
+try { Invoke-Npx            $ConstructArgs } catch {}
+try { Invoke-Global         $ConstructArgs } catch {}
+try { Invoke-CachedBinary   $ConstructArgs } catch {}
+try { Invoke-Docker         $ConstructArgs } catch {}
+
+$msg = @"
+[construct] No Construct install found.
+
+  This project pins Construct$($Version ? " $Version" : '') but no runtime resolved.
+
+  Pick one:
+    - Install Node.js 18+ from https://nodejs.org and re-run.
+    - powershell -File .construct\bootstrap.ps1 -Install   (download a binary)
+    - npm install -g @geraldmaron/construct
+"@
+Write-Error $msg
+exit 127

package/templates/distribution/bootstrap.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+# .construct/bootstrap.sh — POSIX bootstrap shim.
+#
+# Usage:
+#   ./.construct/bootstrap.sh                  # probe environment, print plan
+#   ./.construct/bootstrap.sh --install        # ensure a working Construct is reachable
+#   ./.construct/bootstrap.sh -- <args…>       # invoke construct directly with args
+#
+# Forwards everything after `--` to construct via the same resolution order
+# as `.construct/run.mjs`. Useful for non-Node environments where settings.json
+# hooks aren't enough — e.g. CI scripts, Makefiles, pre-commit hooks in
+# language-agnostic projects.
+#
+# Exit codes:
+#   0   command succeeded
+#   1   construct exited non-zero
+#   127 no Construct install reachable
+
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+VERSION_FILE="${SCRIPT_DIR}/version"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+CACHE_BIN_DIR="${SCRIPT_DIR}/cache/bin"
+
+VERSION=""
+if [ -r "${VERSION_FILE}" ]; then
+  VERSION="$(tr -d '[:space:]' < "${VERSION_FILE}")"
+fi
+
+INSTALL_MODE=""
+if [ "$#" -gt 0 ] && [ "$1" = "--install" ]; then
+  INSTALL_MODE="1"
+  shift
+fi
+
+if [ "$#" -gt 0 ] && [ "$1" = "--" ]; then
+  shift
+fi
+
+probe_node() {
+  command -v node >/dev/null 2>&1 || return 1
+  node --version | sed 's/^v//' | awk -F. '{ exit ($1 < 18) }'
+}
+
+probe_npx()    { command -v npx >/dev/null 2>&1; }
+probe_docker() { command -v docker >/dev/null 2>&1; }
+probe_curl()   { command -v curl >/dev/null 2>&1; }
+
+resolve_arch() {
+  case "$(uname -m)" in
+    arm64|aarch64) echo "arm64" ;;
+    x86_64|amd64)  echo "x64" ;;
+    *) echo "" ;;
+  esac
+}
+
+resolve_os() {
+  case "$(uname -s)" in
+    Darwin) echo "darwin" ;;
+    Linux)  echo "linux" ;;
+    *) echo "" ;;
+  esac
+}
+
+local_construct_in_node_modules() {
+  echo "${PROJECT_ROOT}/node_modules/@geraldmaron/construct/bin/construct"
+}
+
+invoke_via_node_modules() {
+  local bin
+  bin="$(local_construct_in_node_modules)"
+  [ -x "${bin}" ] || return 1
+  exec node "${bin}" "$@"
+}
+
+invoke_via_npx() {
+  probe_node || return 1
+  probe_npx  || return 1
+  if [ -n "${VERSION}" ]; then
+    exec npx -p "@geraldmaron/construct@${VERSION}" -- construct "$@"
+  else
+    exec npx -p "@geraldmaron/construct" -- construct "$@"
+  fi
+}
+
+invoke_via_global() {
+  command -v construct >/dev/null 2>&1 || return 1
+  exec construct "$@"
+}
+
+invoke_via_cached_binary() {
+  local os arch ext binary
+  os="$(resolve_os)"
+  arch="$(resolve_arch)"
+  [ -n "${os}" ] && [ -n "${arch}" ] || return 1
+  binary="${CACHE_BIN_DIR}/construct-${os}-${arch}"
+  [ -x "${binary}" ] || return 1
+  exec "${binary}" "$@"
+}
+
+invoke_via_docker() {
+  probe_docker || return 1
+  local image="ghcr.io/geraldmaron/construct"
+  if [ -n "${VERSION}" ]; then image="${image}:${VERSION}"; else image="${image}:latest"; fi
+  exec docker run --rm \
+    -v "${PROJECT_ROOT}:/work" -w /work \
+    -v "${HOME}/.construct:/data/.construct" \
+    -e CONSTRUCT_PROJECT_ROOT=/work \
+    "${image}" "$@"
+}
+
+# Compute the SHA-256 of a file using whichever tool is available, and compare
+# to the expected digest. Accepts the digest as either a bare hex string or a
+# `sha256sum -c`-style line ("<sha>  <filename>"); we only consume the first
+# 64 hex chars. Returns 0 on match, non-zero otherwise.
+verify_sha256() {
+  local file="$1"
+  local expected_raw="$2"
+  local expected
+  local actual
+  expected="$(echo "${expected_raw}" | tr -d '[:space:]' | cut -c1-64)"
+  if [ -z "${expected}" ] || [ "${#expected}" -ne 64 ]; then
+    return 1
+  fi
+  if command -v sha256sum >/dev/null 2>&1; then
+    actual="$(sha256sum "${file}" | cut -c1-64)"
+  elif command -v shasum >/dev/null 2>&1; then
+    actual="$(shasum -a 256 "${file}" | cut -c1-64)"
+  else
+    return 2
+  fi
+  [ "${actual}" = "${expected}" ]
+}
+
+if [ "${INSTALL_MODE}" = "1" ]; then
+  if invoke_via_node_modules --version >/dev/null 2>&1; then
+    echo "[construct] node_modules install ready: $(local_construct_in_node_modules)"
+    exit 0
+  fi
+  if probe_node && probe_npx; then
+    echo "[construct] npx will resolve construct on first invocation."
+    exit 0
+  fi
+  if probe_docker; then
+    echo "[construct] docker available — bootstrap will use the container image on next run."
+    exit 0
+  fi
+  os="$(resolve_os)"
+  arch="$(resolve_arch)"
+  if probe_curl && [ -n "${os}" ] && [ -n "${arch}" ] && [ -n "${VERSION}" ]; then
+    binary_url="https://github.com/geraldmaron/construct/releases/download/v${VERSION}/construct-${os}-${arch}"
+    sha_url="${binary_url}.sha256"
+    mkdir -p "${CACHE_BIN_DIR}"
+    target="${CACHE_BIN_DIR}/construct-${os}-${arch}"
+    target_sha="${target}.sha256"
+    echo "[construct] downloading binary to ${target}…"
+    if ! curl -fL "${binary_url}" -o "${target}"; then
+      echo "[construct] binary download failed; falling through." >&2
+      rm -f "${target}"
+    elif ! curl -fL "${sha_url}" -o "${target_sha}"; then
+      echo "[construct] SHA-256 download failed at ${sha_url}; refusing to install an unverified binary." >&2
+      rm -f "${target}" "${target_sha}"
+    elif ! verify_sha256 "${target}" "$(cat "${target_sha}")"; then
+      echo "[construct] SHA-256 mismatch; refusing to install. Re-run to retry." >&2
+      rm -f "${target}" "${target_sha}"
+    else
+      chmod +x "${target}"
+      rm -f "${target_sha}"
+      echo "[construct] binary cached and SHA-verified. Subsequent invocations use it."
+      exit 0
+    fi
+  fi
+  echo "[construct] No installable runtime detected." >&2
+  echo "  Install one of: Node.js 18+, Docker, or curl + a release binary." >&2
+  exit 127
+fi
+
+# Default mode — resolve and invoke construct with whatever args were passed.
+invoke_via_node_modules "$@" 2>/dev/null || true
+invoke_via_npx          "$@" 2>/dev/null || true
+invoke_via_global       "$@" 2>/dev/null || true
+invoke_via_cached_binary "$@" 2>/dev/null || true
+invoke_via_docker        "$@" 2>/dev/null || true
+
+cat >&2 <<EOF
+[construct] No Construct install found.
+
+  This project pins Construct${VERSION:+ ${VERSION}} but no runtime resolved.
+
+  Pick one:
+    - Install Node.js 18+ from https://nodejs.org and re-run.
+    - Run ./.construct/bootstrap.sh --install to download a binary.
+    - Install Construct globally: npm install -g @geraldmaron/construct
+EOF
+exit 127