@geraldmaron/construct 1.0.0 → 1.0.2

package/templates/docs/onboarding.md

@@ -0,0 +1,57 @@
+# Onboarding: {role or audience}
+
+- **Date**: {YYYY-MM-DD}
+- **Audience**: {engineers | product | ops | all}
+- **Maintained by**: {name or team}
+- **Status**: draft | current | outdated
+
+<!--
+Onboarding docs should be runnable, not just readable. Every step should be
+something a new person can actually execute. Flag commands that require access
+provisioning or credentials so they are not blocked on day one.
+-->
+
+## Prerequisites
+
+<!-- Accounts, access, hardware, or tools that must be in place before starting. -->
+
+## Local setup
+
+<!-- Step-by-step commands to get a working local environment. Use code blocks. -->
+
+```sh
+# Example
+git clone ...
+cd ...
+cp .env.example .env
+npm install
+npm run dev
+```
+
+## Verifying the setup
+
+<!-- How to confirm the setup worked. Include expected output or a smoke-test command. -->
+
+## Key concepts
+
+<!-- The minimum mental model a new person needs to be productive. Link to architecture docs. -->
+
+## Common workflows
+
+<!-- The two or three things this person will do every day. Link to deeper runbooks if needed. -->
+
+## Access provisioning
+
+<!-- What systems need access, who to ask, and typical turnaround time. -->
+
+## Gotchas
+
+<!-- Known sharp edges, non-obvious configuration, common first-day mistakes. -->
+
+## Who to ask
+
+<!-- Owners, on-call rotations, or Slack channels for help. -->
+
+## References
+
+<!-- Architecture overview, runbooks, ADRs, or external docs relevant to this role. -->

package/templates/docs/prd.md

@@ -9,39 +9,183 @@ Use this for a product capability, user workflow, or customer-facing requirement
 Use meta-prd.md instead when defining the requirements for a product system, agent,
 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 —
+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,
 not the whole document. Keep em dashes rare; prefer commas, periods, or parentheses.
 -->
 
+## Summary
+<!--
+One paragraph (3-5 sentences) that a busy reader can use as the whole PRD.
+What the change is, who it's for, why now, and what changes when it ships.
+No solutions in this section that aren't decided. No ticket IDs. No team names.
+-->
+
+## Background
+<!--
+Context the reader needs to evaluate this PRD without asking around.
+Include relevant prior work (linked PRDs, ADRs, RFCs), observed signals, and
+the current state of the user experience or system. State what is already
+true today so the reader can compare against the proposed change.
+
+Cite evidence: support tickets, interviews, telemetry, sales calls, research.
+Avoid roadmap-speak ("this is a Q3 priority"); state what is happening to users.
+-->
+
 ## Problem
-<!-- What is broken, missing, or blocking a user or business outcome? One paragraph. State the pain, not the solution. -->
+<!--
+The specific user or business outcome that is currently blocked. One or two
+paragraphs. State the pain, not the solution.
+
+Must NOT reference:
+- Jira / Linear ticket IDs or "this came from ticket X"
+- Roadmap items, OKR line items, or quarterly goals
+- "The team decided we should build this"
+
+Must reference:
+- Observed user behavior, quantitative signals, or qualitative evidence
+- The specific outcome that is not currently achievable
+- The constraint that makes this non-trivial today
+-->
+
+## Goals
+<!--
+What success looks like, in outcome terms. Three to five goals max. Each
+goal is the *change* you want, not the activity. Order by importance.
+
+Examples:
+- Reduce p95 onboarding time from 12m to under 4m for new accounts.
+- Eliminate the manual reconciliation step our top 20 customers do every Monday.
+- Halve the support volume for "where is my data" questions.
+-->
+
+## 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
+user's perspective when possible. The acceptance criteria below should be the
+falsifiable evidence that this outcome was achieved.
+
+A reader should be able to compare the current state (Background) to this
+section and see the delta in plain language.
+-->
 
-## Users
-<!-- Who experiences the problem? Segments, scale, current workaround. Cite evidence (tickets, interviews, data). -->
+## In scope and out of scope
 
-## Goals and non-goals
-<!-- Goals: what success looks like. Non-goals: explicitly scoped out to keep the work bounded. -->
+| | Description |
+|---|---|
+| **In scope** | <what this PRD covers and commits to ship> |
+| **Out of scope** | <related work explicitly deferred — name the reason> |
+| **Adjacent (deferred)** | <work that's a natural follow-up but not in this PRD> |
 
-## Functional requirements
-<!-- What the system must do. Number them (FR-1, FR-2, …) so they can be referenced in reviews and tests. -->
+<!--
+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.
+-->
 
-## Non-functional requirements
-<!-- Performance, reliability, security, accessibility, compliance. Include numeric targets where possible. -->
+## Phases
+
+<!--
+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" —
+that's a task list, not a phasing.
 
-## Acceptance criteria
-<!-- Observable, falsifiable conditions a reviewer can check without asking the author. -->
+Each phase below holds its own goal, status, functional requirements (FR),
+and non-functional requirements (NFR), with acceptance criteria written
+inline next to each requirement. Use `FR-<phase>.<n>` and `NFR-<phase>.<n>`
+so requirements can be referenced from reviews and tests.
+
+Status values: not started | in progress | shipped | deferred.
+
+NFR categories to consider: performance, reliability, security, privacy,
+accessibility, observability, compliance, cost. Numeric targets where possible.
+-->
+
+### Phase 1 — <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Functional**
+
+- **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** — <...>
+  - *Acceptance*: <...>
+
+**Non-functional**
+
+- **NFR-1.1** — <category>: <target with number>
+  - *Acceptance*: <how this is measured and what counts as pass>
+
+### Phase 2 — <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Functional**
+
+- **FR-2.1** — <...>
+  - *Acceptance*: <...>
+- **FR-2.2** — <...>
+  - *Acceptance*: <...>
+
+**Non-functional**
+
+- **NFR-2.1** — <category>: <target>
+  - *Acceptance*: <...>
+
+### Phase 3 — <name>
+
+- **Goal**: <what this phase delivers>
+- **Status**: not started
+
+**Functional**
+
+- **FR-3.1** — <...>
+  - *Acceptance*: <...>
+
+**Non-functional**
+
+- **NFR-3.1** — <category>: <target>
+  - *Acceptance*: <...>
 
 ## Success metrics
-<!-- How we will know this worked in production. Leading vs. lagging. Avoid vanity metrics. -->
+<!--
+How we will know this worked in production over time, beyond the per-requirement
+acceptance criteria. Leading vs. lagging. Avoid vanity metrics.
+-->
 
 ## Constraints
-<!-- Budget, timeline, platform, team, legal, technical debt that shapes the solution. -->
+<!--
+Budget, timeline, platform, team, legal, technical debt — anything that shapes
+the solution and isn't a requirement.
+-->
 
 ## Dependencies
-<!-- Teams, services, contracts, data sources, vendor timelines. -->
+<!--
+Teams, services, contracts, data sources, vendor timelines. Each dependency
+should name an owner and the date it must be ready by.
+-->
+
+## Risks and mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| <risk> | low / med / high | low / med / high | <how this is reduced or what we accept> |
 
 ## Open questions
-<!-- Genuine unknowns. Each question should name an owner and a decision deadline. -->
+
+| Question | Owner | Decision needed by |
+|---|---|---|
+| <unknown> | <name> | <YYYY-MM-DD> |
 
 ## References
 <!-- Linked research, prior PRDs, ADRs, tickets, designs. -->

package/templates/docs/research-brief.md

@@ -8,13 +8,13 @@
 <!-- The specific, falsifiable question this research is trying to answer. One sentence. -->
 
 ## Method
-<!-- How the question was investigated. Sources consulted, queries run, experiments performed, people interviewed. Enough detail that another person could reproduce it. -->
+<!-- How the question was investigated. Start order, queries run, internal paths checked, experiments performed, and systems consulted. Enough detail that another person could reproduce it. -->
 
 ## Sources
-<!-- Primary sources, with links and access dates. Separate primary from secondary. Note where sources disagree. -->
+<!-- For each source record: title/path, source class (internal/primary/secondary/tertiary), version or revision if relevant, and publication/access date. Separate primary from secondary. Note where sources disagree. -->
 
 ## Findings
-<!-- What the evidence says. Separate observation from inference. Label each finding with its confidence level. -->
+<!-- What the evidence says. Separate observation from inference. Label each finding with its confidence level and cite the supporting source(s). -->
 
 ## Confidence
 <!-- Per finding: high / medium / low, and why. Name the biggest unknowns. -->
@@ -26,4 +26,4 @@
 <!-- What this research did not resolve. What would be needed to answer each. -->
 
 ## References
-<!-- Full citation list. -->
+<!-- Full citation list. Include URLs, document paths, versions, and dates. -->

package/templates/homebrew/construct.rb

@@ -0,0 +1,67 @@
+# Construct — Homebrew formula template.
+#
+# Authoritative copy lives in the construct repo at templates/homebrew/
+# construct.rb. The tap repo (geraldmaron/homebrew-construct) carries the
+# active formula at Formula/construct.rb and is updated by the release
+# workflow's Homebrew bump step on every tag push.
+#
+# When the release pipeline fires for `vX.Y.Z`, dawidd6/action-homebrew-bump-
+# formula rewrites the url + sha256 fields for each platform from the
+# matching GitHub Release asset. The placeholder SHAs below are only used
+# when seeding the tap by hand the first time.
+class Construct < Formula
+  desc "Deployable AI R&D operating system for coding agents — runs locally or for teams"
+  homepage "https://github.com/geraldmaron/construct"
+  version "0.1.0"
+  license "Elastic-2.0"
+
+  livecheck do
+    url :stable
+    strategy :github_latest
+  end
+
+  on_macos do
+    on_arm do
+      url "https://github.com/geraldmaron/construct/releases/download/v0.1.0/construct-darwin-arm64"
+      sha256 "REPLACE_ON_FIRST_RELEASE_DARWIN_ARM64"
+    end
+    on_intel do
+      url "https://github.com/geraldmaron/construct/releases/download/v0.1.0/construct-darwin-x64"
+      sha256 "REPLACE_ON_FIRST_RELEASE_DARWIN_X64"
+    end
+  end
+
+  on_linux do
+    on_arm do
+      url "https://github.com/geraldmaron/construct/releases/download/v0.1.0/construct-linux-arm64"
+      sha256 "REPLACE_ON_FIRST_RELEASE_LINUX_ARM64"
+    end
+    on_intel do
+      url "https://github.com/geraldmaron/construct/releases/download/v0.1.0/construct-linux-x64"
+      sha256 "REPLACE_ON_FIRST_RELEASE_LINUX_X64"
+    end
+  end
+
+  def install
+    bin.install Dir["construct-*"].first => "construct"
+  end
+
+  def caveats
+    <<~EOS
+      To finish setup on this machine, run:
+        construct setup
+
+      Construct uses a local Postgres container (via Docker) for hybrid
+      retrieval. If Docker is not installed, Construct falls back to a JSON
+      vector index — no hard requirement.
+
+      To wire up hooks and agents per project, add Construct as a dev
+      dependency in that project:
+        npm install -D @geraldmaron/construct
+    EOS
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/construct version")
+  end
+end

package/langfuse/docker-compose.yml

@@ -1,82 +0,0 @@
-# Construct — Langfuse Self-Hosted
-# Auto-provisioned: keys are seeded at container startup via LANGFUSE_INIT_* vars.
-# No browser setup required. 'construct setup' writes keys to .env automatically.
-#
-# Manual usage:
-#   docker-compose -f langfuse/docker-compose.yml -p construct-langfuse up -d
-#   # Keys are ready immediately — see LANGFUSE_INIT_PROJECT_* below
-
-name: construct-langfuse
-
-services:
-  langfuse-server:
-    image: langfuse/langfuse:2
-    container_name: construct-langfuse
-    restart: unless-stopped
-    depends_on:
-      langfuse-db:
-        condition: service_healthy
-    ports:
-      - "3000:3000"
-    environment:
-      DATABASE_URL: postgresql://langfuse:langfuse@langfuse-db:5432/langfuse
-      NEXTAUTH_SECRET: ${LANGFUSE_NEXTAUTH_SECRET:-construct-nextauth-secret}
-      SALT: ${LANGFUSE_SALT:-construct-salt-value}
-      NEXTAUTH_URL: http://localhost:3000
-      TELEMETRY_ENABLED: "false"
-      LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: "true"
-      AUTH_DISABLE_SIGNUP: "false"
-      # ── Auto-provisioning (no browser setup needed) ──────────────────
-      LANGFUSE_INIT_ORG_ID: "construct-org"
-      LANGFUSE_INIT_ORG_NAME: "Construct"
-      LANGFUSE_INIT_PROJECT_ID: "construct-project"
-      LANGFUSE_INIT_PROJECT_NAME: "Construct"
-      LANGFUSE_INIT_PROJECT_PUBLIC_KEY: "pk-lf-construct-local"
-      LANGFUSE_INIT_PROJECT_SECRET_KEY: "sk-lf-construct-local"
-      LANGFUSE_INIT_USER_EMAIL: "admin@construct.local"
-      LANGFUSE_INIT_USER_NAME: "Admin"
-      LANGFUSE_INIT_USER_PASSWORD: "construct-admin"
-    healthcheck:
-      test: ["CMD-SHELL", "curl -sf http://localhost:3000/api/public/health || exit 1"]
-      interval: 10s
-      timeout: 5s
-      retries: 10
-      start_period: 30s
-
-  langfuse-db:
-    image: postgres:15-alpine
-    container_name: construct-langfuse-db
-    restart: unless-stopped
-    environment:
-      POSTGRES_USER: langfuse
-      POSTGRES_PASSWORD: langfuse
-      POSTGRES_DB: langfuse
-    volumes:
-      - langfuse_db_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U langfuse -d langfuse"]
-      interval: 3s
-      timeout: 3s
-      retries: 10
-
-  dspy-optimizer:
-    build:
-      context: ./dspy-optimizer
-      dockerfile: Dockerfile
-    container_name: construct-dspy-optimizer
-    restart: "no"
-    profiles:
-      - optimize
-    env_file:
-      - ../.env
-    environment:
-      LANGFUSE_BASEURL: http://langfuse-server:3000
-    depends_on:
-      langfuse-server:
-        condition: service_healthy
-    volumes:
-      - ../.cx:/app/.cx
-
-volumes:
-  langfuse_db_data:
-    driver: local

package/lib/eval-harness.mjs

@@ -1,59 +0,0 @@
-#!/usr/bin/env node
-/**
- * lib/eval-harness.mjs — <one-line purpose>
- *
- * <2–6 line summary.>
- */
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const root = path.join(__dirname, "..");
-
-/**
- * Basic evaluation harness for Construct agents.
- * This script runs "dry runs" or simulated interactions against agent prompts
- * to verify they would call the right tools or produce the right outcomes.
- */
-
-export async function runEval(agentName, input, expectedPatterns = []) {
-  const registry = JSON.parse(fs.readFileSync(path.join(root, "agents", "registry.json"), "utf8"));
-  const agent = registry.agents.find(a => a.name === agentName) || 
-                registry.personas.find(p => p.name === agentName);
-  
-  if (!agent) throw new Error(`Agent ${agentName} not found in registry`);
-
-  // In a real production setup, this would call the LLM.
-  // For this harness, we are checking the "Static Intent" — 
-  // can the agent logically fulfill the request based on its prompt?
-  
-  const results = {
-    agent: agentName,
-    input,
-    passed: true,
-    findings: []
-  };
-
-  for (const pattern of expectedPatterns) {
-    const regex = new RegExp(pattern, "i");
-    const foundInPrompt = regex.test(agent.prompt || "");
-    const foundInShared = (registry.sharedGuidance || []).some(g => regex.test(g));
-    
-    if (!foundInPrompt && !foundInShared) {
-      results.passed = false;
-      results.findings.push(`MISSING: Pattern "${pattern}" not supported by agent prompt or shared guidance`);
-    } else {
-      results.findings.push(`OK: Pattern "${pattern}" is supported`);
-    }
-  }
-
-  return results;
-}
-
-if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
-  // Simple example run
-  const testAgent = process.argv[2] || "engineer";
-  const result = await runEval(testAgent, "Fix the bug", ["Edit", "Read", "Bash"]);
-  console.log(JSON.stringify(result, null, 2));
-}

package/lib/hooks/bootstrap-guard.mjs

@@ -1,90 +0,0 @@
-#!/usr/bin/env node
-/**
- * lib/hooks/bootstrap-guard.mjs — enforce start-of-session bootstrap trio.
- *
- * Blocks Write/Edit/MultiEdit/NotebookEdit/TodoWrite and destructive Bash
- * until the session has invoked workflow_status + project_context + memory_search
- * (or accumulated 3+ read-style tool calls, the equivalent signal that the
- * agent has grounded itself before acting).
- */
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
-
-let payload = {};
-try { payload = JSON.parse(readFileSync(0, 'utf8')) || {}; } catch { process.exit(0); }
-
-const sessionId = payload.session_id || payload.sessionId || 'default';
-const toolName = payload.tool_name || payload.tool || '';
-const toolInput = payload.tool_input || payload.toolInput || {};
-
-const BOOTSTRAP_TOOLS = new Set([
-  'mcp__construct-mcp__workflow_status',
-  'mcp__construct-mcp__project_context',
-  'mcp__construct-mcp__memory_search',
-  'mcp__cass__memory_search',
-  'workflow_status', 'project_context', 'memory_search',
-]);
-const READ_TOOLS = new Set(['Read', 'Grep', 'Glob', 'LS', 'NotebookRead']);
-const BLOCKED_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'TodoWrite']);
-const COMPATIBLE_TOOLS = new Set(['Read', 'Grep', 'Glob', 'LS', 'NotebookRead']);
-
-const BENIGN_BASH = /^(git (status|log|diff|branch|show|rev-parse)|ls|cat|head|tail|pwd|wc|file|echo|which|node --version|npm --version)\b/;
-
-const stateDir = join(homedir(), '.cx');
-const statePath = join(stateDir, 'bootstrap-state.json');
-
-let state = {};
-if (existsSync(statePath)) {
-  try { state = JSON.parse(readFileSync(statePath, 'utf8')) || {}; } catch { state = {}; }
-}
-
-const now = Date.now();
-for (const [k, v] of Object.entries(state)) {
-  if (!v?.ts || now - v.ts > 24 * 60 * 60 * 1000) delete state[k];
-}
-
-const s = state[sessionId] || { ts: now, reads: 0, bootstrap: new Set(), done: false };
-if (Array.isArray(s.bootstrap)) s.bootstrap = new Set(s.bootstrap);
-else if (!(s.bootstrap instanceof Set)) s.bootstrap = new Set();
-s.ts = now;
-
-if (BOOTSTRAP_TOOLS.has(toolName)) s.bootstrap.add(toolName.replace(/^.*__/, ''));
-if (READ_TOOLS.has(toolName)) s.reads = (s.reads || 0) + 1;
-
-if (!s.done) {
-  const hasTrio = s.bootstrap.has('workflow_status') && s.bootstrap.has('project_context') && s.bootstrap.has('memory_search');
-  if (hasTrio || (s.reads || 0) >= 3) s.done = true;
-}
-
-if (!s.done && toolName && COMPATIBLE_TOOLS.has(toolName) && (s.reads || 0) >= 2) {
-  s.done = true;
-}
-
-let block = false;
-let reason = '';
-if (!s.done) {
-  if (BLOCKED_TOOLS.has(toolName)) {
-    block = true;
-    reason = `${toolName} requires session bootstrap.`;
-  } else if (toolName === 'Bash') {
-    const cmd = (toolInput.command || '').trim();
-    if (cmd && !BENIGN_BASH.test(cmd)) { block = true; reason = 'Bash mutations require session bootstrap.'; }
-  }
-}
-
-try {
-  mkdirSync(stateDir, { recursive: true });
-  state[sessionId] = { ...s, bootstrap: Array.from(s.bootstrap) };
-  writeFileSync(statePath, JSON.stringify(state));
-} catch { /* best effort */ }
-
-if (block) {
-  process.stderr.write(
-    `[bootstrap-guard] ${reason}\n` +
-    `Run in parallel first: workflow_status, project_context, memory_search.\n` +
-    `(Or do 3+ exploratory reads — Read/Grep/Glob/LS — if this is a pure exploration task.)\n`
-  );
-  process.exit(2);
-}
-process.exit(0);

package/lib/hooks/console-warn.mjs

@@ -1,43 +0,0 @@
-#!/usr/bin/env node
-/**
- * lib/hooks/console-warn.mjs — Console warn hook — warns when console.log/debug statements are left in code.
- *
- * Runs as PostToolUse after Edit/Write. Detects console.log and console.debug statements in edited files and emits a warning. Does not block — informational only.
- */
-import { readFileSync, appendFileSync, existsSync } from 'fs';
-import { homedir } from 'os';
-import { basename } from 'path';
-
-const CODE_EXTS = new Set(['.js','.mjs','.cjs','.ts','.tsx','.jsx']);
-const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
-
-if (!filePath) process.exit(0);
-
-const ext = '.' + filePath.split('.').pop();
-if (!CODE_EXTS.has(ext)) process.exit(0);
-
-if (!existsSync(filePath)) process.exit(0);
-
-const lines = readFileSync(filePath, 'utf8').split('\n');
-const hits = [];
-
-for (let i = 0; i < lines.length; i++) {
-  const line = lines[i];
-  const stripped = line.replace(/\/\/.*$/, '').replace(/\/\*.*?\*\//g, '');
-  if (/\bconsole\.(log|warn|error|info|debug)\s*\(/.test(stripped) || /\bdebugger\s*;/.test(stripped)) {
-    hits.push(i + 1);
-  }
-}
-
-if (hits.length === 0) process.exit(0);
-
-const file = basename(filePath);
-const lineList = hits.slice(0, 5).join(', ') + (hits.length > 5 ? '…' : '');
-const msg = `Heads up: debug statements left in ${file} — console.log on line${hits.length > 1 ? 's' : ''} ${lineList}. Remove before shipping.`;
-
-process.stderr.write(`[console-warn] ${msg}\n`);
-
-const flagsPath = `${homedir()}/.cx/warn-flags.txt`;
-try { appendFileSync(flagsPath, `console.log in ${file} (lines ${lineList})\n`); } catch { /* best effort */ }
-
-process.exit(0);