@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/writes/sent-log.mjs

@@ -0,0 +1,86 @@
+/**
+ * lib/writes/sent-log.mjs — durable JSONL record of executed external writes.
+ *
+ * WriteSentLog persists idempotency keys and outcomes so a retried or duplicate
+ * write-intent is deduplicated rather than re-executed against the remote system.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export class WriteSentLog {
+  #records = [];
+  #persistPath = null;
+
+  constructor({ persistPath } = {}) {
+    if (persistPath) {
+      this.#persistPath = persistPath;
+      this.#load();
+    }
+  }
+
+  record(entry) {
+    const rec = {
+      idempotencyKey: entry.idempotencyKey,
+      writeType: entry.writeType,
+      provider: entry.provider,
+      sentAt: entry.sentAt || new Date().toISOString(),
+      completedAt: entry.completedAt || null,
+      status: entry.status || 'pending',
+      externalUrl: entry.externalUrl || null,
+      externalId: entry.externalId || null,
+      result: entry.result || null,
+      error: entry.error || null,
+    };
+    this.#records.push(rec);
+    this.#persist();
+    return rec;
+  }
+
+  findByIdempotencyKey(key) {
+    let found = null;
+    for (const r of this.#records) {
+      if (r.idempotencyKey === key) found = r;
+    }
+    return found;
+  }
+
+  list({ provider, status, since } = {}) {
+    let results = [...this.#records];
+    if (provider) results = results.filter(r => r.provider === provider);
+    if (status) results = results.filter(r => r.status === status);
+    if (since) results = results.filter(r => new Date(r.sentAt) >= new Date(since));
+    return results;
+  }
+
+  pruneOlderThan(ms) {
+    const cutoff = Date.now() - ms;
+    const before = this.#records.length;
+    this.#records = this.#records.filter(r => new Date(r.sentAt).getTime() > cutoff);
+    this.#persist();
+    return before - this.#records.length;
+  }
+
+  #persist() {
+    if (!this.#persistPath) return;
+    try {
+      fs.mkdirSync(path.dirname(this.#persistPath), { recursive: true });
+      const lines = this.#records.map(r => JSON.stringify(r)).join('\n');
+      fs.writeFileSync(this.#persistPath, lines + '\n', 'utf8');
+    } catch {}
+  }
+
+  #load() {
+    try {
+      if (!fs.existsSync(this.#persistPath)) return;
+      const lines = fs.readFileSync(this.#persistPath, 'utf8').split('\n').filter(Boolean);
+      for (const line of lines) {
+        try { this.#records.push(JSON.parse(line)); } catch {}
+      }
+    } catch {}
+  }
+
+  static resolvePersistPath(rootDir) {
+    return path.join(rootDir, '.cx', 'writes', 'sent-log.jsonl');
+  }
+}

package/lib/writes/write-intent.mjs

@@ -0,0 +1,109 @@
+/**
+ * lib/writes/write-intent.mjs — the writeIntent record: the only artifact
+ * shape a specialist, embed capability, or MCP caller may produce when it
+ * wants an external write to happen.
+ *
+ * A writeIntent never executes anything by itself. `buildWriteIntent`
+ * validates and normalizes the record; `lib/writes/control-plane.mjs` is the
+ * only module that turns an *approved* writeIntent into a call through
+ * lib/writes/envelope.mjs. Nothing in this file resolves a provider adapter
+ * or performs I/O — it is schema and validation only, so it stays importable
+ * from any orchestration or embed path without smuggling in write access.
+ */
+
+/** Providers with a governed-write adapter under lib/providers/contract/adapters/*. */
+export const KNOWN_PROVIDERS = Object.freeze(['jira', 'github', 'confluence']);
+
+/**
+ * Validate a writeIntent's required shape. Returns `{ ok: true }` or
+ * `{ ok: false, errors: string[] }` — never throws, so a malformed proposal
+ * from a specialist degrades to a rejected intent rather than crashing the
+ * caller.
+ *
+ * @param {object} intent
+ * @param {string} intent.providerId - one of KNOWN_PROVIDERS
+ * @param {string} intent.writeKind - adapter-specific write type (e.g. 'issue', 'comment')
+ * @param {object} intent.payload - write payload passed to the adapter
+ * @param {object} [intent.requestedBy] - actor identity of the recommending specialist
+ * @returns {{ ok: boolean, errors?: string[] }}
+ */
+export function validateWriteIntent(intent) {
+  const errors = [];
+  if (!intent || typeof intent !== 'object') {
+    return { ok: false, errors: ['writeIntent must be an object'] };
+  }
+  if (!intent.providerId || typeof intent.providerId !== 'string') {
+    errors.push('writeIntent.providerId is required');
+  } else if (!KNOWN_PROVIDERS.includes(intent.providerId)) {
+    errors.push(`writeIntent.providerId "${intent.providerId}" is not a known governed provider (${KNOWN_PROVIDERS.join(', ')})`);
+  }
+  if (!intent.writeKind || typeof intent.writeKind !== 'string') {
+    errors.push('writeIntent.writeKind is required');
+  }
+  if (!intent.payload || typeof intent.payload !== 'object') {
+    errors.push('writeIntent.payload is required and must be an object');
+  }
+  return errors.length ? { ok: false, errors } : { ok: true };
+}
+
+/**
+ * Build a normalized writeIntent record from a specialist's recommendation.
+ * Throws on an invalid intent so a caller cannot silently enqueue a
+ * malformed record — the run should see the failure at recommend time, not
+ * discover it later when the control plane tries to execute it.
+ *
+ * @param {object} spec
+ * @param {string} spec.providerId
+ * @param {string} spec.writeKind
+ * @param {object} spec.payload
+ * @param {object} [spec.requestedBy] - { specialistId, role, serviceId, sessionId }
+ * @param {string} [spec.surface] - origin surface, e.g. 'embed-capability' | 'mcp' | 'cli'
+ * @returns {{ providerId: string, writeKind: string, payload: object, requestedBy: object, surface: string, tool: string }}
+ */
+export function buildWriteIntent(spec) {
+  const intent = {
+    providerId: spec?.providerId,
+    writeKind: spec?.writeKind,
+    payload: spec?.payload,
+  };
+  const result = validateWriteIntent(intent);
+  if (!result.ok) {
+    throw new Error(`buildWriteIntent: invalid writeIntent — ${result.errors.join('; ')}`);
+  }
+  return {
+    providerId: intent.providerId,
+    writeKind: intent.writeKind,
+    payload: intent.payload,
+    requestedBy: spec?.requestedBy ?? {},
+    surface: spec?.surface ?? 'unknown',
+    tool: writeIntentToolName(intent.providerId, intent.writeKind),
+  };
+}
+
+/**
+ * The tool-name encoding shared with lib/embed/capability-jobs.mjs's
+ * ApprovalQueue.enqueue({ tool }) calls and lib/embed/authority-guard.mjs's
+ * grant keys — "<providerId>.<writeKind>", e.g. "jira.issue". Kept in one
+ * place so the control-plane drain and the enqueue side can never drift.
+ *
+ * @param {string} providerId
+ * @param {string} writeKind
+ * @returns {string}
+ */
+export function writeIntentToolName(providerId, writeKind) {
+  return `${providerId}.${writeKind}`;
+}
+
+/**
+ * Parse a "<providerId>.<writeKind>" tool name back into its parts. Returns
+ * null when the name has no dot, which the caller should treat as
+ * unresolvable rather than guessing.
+ *
+ * @param {string} tool
+ * @returns {{ providerId: string, writeKind: string }|null}
+ */
+export function parseWriteIntentToolName(tool) {
+  const idx = typeof tool === 'string' ? tool.indexOf('.') : -1;
+  if (idx <= 0 || idx === tool.length - 1) return null;
+  return { providerId: tool.slice(0, idx), writeKind: tool.slice(idx + 1) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -26,6 +26,10 @@
     "platforms/**",
     "templates/**",
     "templates/distribution/**",
+    "schemas/**",
+    "registry/**",
+    "config/**",
+    "vendor/**",
     "scripts/sync-specialists.mjs",
     "README.md",
     ".env.example"
@@ -53,9 +57,10 @@
     "mcp": "node lib/mcp/server.mjs",
     "doctor": "node ./bin/construct doctor",
     "test": "node scripts/run-tests.mjs",
-    "test:functional": "XDG_CONFIG_HOME= XDG_STATE_HOME= XDG_CACHE_HOME= node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
-    "test:visual": "node -e \"console.log('visual surface tests removed')\"",
+    "test:functional": "XDG_CONFIG_HOME= XDG_STATE_HOME= XDG_CACHE_HOME= ANTHROPIC_API_KEY= OPENAI_API_KEY= OPENROUTER_API_KEY= CX_MODEL_REASONING= CX_MODEL_STANDARD= CX_MODEL_FAST= CONSTRUCT_MODEL_REASONING= CONSTRUCT_MODEL_STANDARD= CONSTRUCT_MODEL_FAST= CONSTRUCT_PROVIDER_TIMEOUT_MS= WEB_SEARCH_URL= CX_USER_ENV_PATH= CONSTRUCT_TELEMETRY_URL= node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
+    "test:visual": "node --test --test-timeout=120000 tests/visual/*.test.mjs",
     "test:unit": "node scripts/run-tests.mjs --exclude=tests/functional",
+    "ci:local": "bash scripts/ci-repro/run.sh",
     "lint:js": "eslint bin/construct \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"tests/**/*.mjs\"",
     "coverage": "c8 --reporter=text-summary --reporter=lcov --src=lib --src=bin node scripts/run-tests.mjs --exclude=tests/functional",
     "docs:init": "node -e \"console.error('docs:init is deprecated — use: construct init --docs-preset=lean|product|full'); process.exit(1)\"",
@@ -66,33 +71,38 @@
     "docs:build": "node scripts/npm-run.mjs npm --prefix apps/docs run build",
     "lint:comments": "node ./bin/construct lint:comments",
     "lint:contracts": "node ./bin/construct lint:contracts",
+    "graph:gate": "node scripts/run-graph-gate.mjs",
     "lint:agents": "node ./bin/construct lint:agents",
     "gates:audit": "node ./bin/construct gates:audit",
     "evals": "node ./bin/construct evals",
     "certify:demos": "node ./bin/construct certify demos",
     "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)",
+    "build:binary": "node scripts/build-binary.mjs",
+    "build:binary:fallback": "node scripts/build-sea.mjs",
     "examples:deck": "node scripts/generate-deck-examples.mjs",
     "examples:distribution": "node scripts/generate-distribution-examples.mjs",
     "clean:artifacts": "node scripts/clean-artifacts.mjs",
     "lint:scopes": "node scripts/lint-scopes.mjs",
     "catalog:regen": "node scripts/catalog-regen.mjs",
     "catalog:validate": "node scripts/catalog-validate.mjs",
+    "workflow-defs:check": "node scripts/check-workflow-defs-drift.mjs --check",
     "docs:sync": "node scripts/docs-sync.mjs",
     "learning:status": "node scripts/learning-status.mjs",
     "lint:templates": "node scripts/lint-commits-pr.mjs",
     "eval:routing": "node scripts/eval/score-intent-classifier.mjs",
     "adapters": "node lib/adapters-sync.mjs",
-    "release:check": "npm run doctor && node ./bin/construct registry:validate --unified && npm run catalog:validate -- --check && npm test && npm run docs:update -- --check && npm run docs:site -- --check && npm run docs:sync -- --check && node ./bin/construct registry:generate-docs --check && npm run docs:verify -- --strict && node scripts/alignment/census.mjs --ratchet && npm run lint:comments && node ./bin/construct certify gate && npm run lint:templates",
+    "release:check": "npm run doctor && node ./bin/construct registry:validate --unified && npm run catalog:validate -- --check && npm run workflow-defs:check && npm test && node scripts/release-evidence-gate.mjs --skip-tests && npm run docs:update -- --check && npm run docs:site -- --check && npm run docs:sync -- --check && node ./bin/construct registry:generate-docs --check && npm run docs:verify -- --strict && node scripts/alignment/census.mjs --ratchet && npm run lint:comments && node ./bin/construct certify gate && npm run graph:gate && npm run lint:templates",
     "release:gate": "node --test tests/functional/release-gate.functional.test.mjs",
     "audit:published": "node scripts/audit-published-artifact.mjs",
     "version": "node scripts/sync-construct-version.mjs && git add -f .construct/version",
     "release:preflight": "node scripts/pre-release-check.mjs",
     "release:preflight:no-auth": "node scripts/pre-release-check.mjs --skip-auth",
     "npm:publish": "npm run release:check && npm publish --access public",
-    "postinstall": "node ./bin/construct-postinstall.mjs"
+    "postinstall": "node ./bin/construct-postinstall.mjs",
+    "deps:check": "node scripts/validate-dep-intent.mjs"
   },
   "dependencies": {
-    "@lancedb/lancedb": "^0.30.0",
+    "@lancedb/lancedb": "^0.31.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "apache-arrow": "^18.1.0",
     "js-yaml": "^4.2.0"
@@ -106,6 +116,7 @@
     "ai": "^6.0.208",
     "ink": "^7.1.0",
     "mammoth": "^1.12.0",
+    "postgres": "^3.4.9",
     "pptx-embed-fonts": "^0.0.6",
     "pptxgenjs": "^4.0.1",
     "react": "^19.2.7",
@@ -122,6 +133,8 @@
     "esbuild": "^0.28.1",
     "eslint": "^10.4.1",
     "globals": "^17.6.0",
-    "ink-testing-library": "^4.0.0"
+    "ink-testing-library": "^4.0.0",
+    "playwright": "^1.61.1",
+    "postject": "1.0.0-alpha.6"
   }
 }

package/personas/construct.md

@@ -25,9 +25,9 @@ Use the single-writer rule whenever multiple sessions are active: if two session
 
 ## Classify before acting <!-- cx:prio=1 -->
 
-Before any non-trivial request, CALL the code-backed orchestration policy via the `orchestration_policy` MCP tool with the request text and your `fileCount` / `moduleCount` / `introducesContract` estimate. Do not classify from memory. Honor the returned `track` and `specialists`. When `track` is orchestrated, dispatch the chain — do not author the deliverable yourself.
+Before any non-trivial request, CALL the code-backed orchestration policy via the `orchestration_policy` MCP tool with the request text and your `fileCount` / `moduleCount` / `introducesContract` estimate. Do not classify from memory. Honor the returned `track`. When `track` is not immediate, dispatch through `orchestration_delegation_next` (below) — do not author the deliverable yourself and do not self-sequence off `orchestration_policy`'s specialist list from memory across turns.
 
-Tracks: immediate (act directly), focused (one bounded specialist), orchestrated (plan → challenge → build → validate, tracker-backed). cx-devil-advocate is mandatory whenever `riskFlags` include architecture, security, dataIntegrity, or ai.
+Tracks: immediate (act directly), focused (one bounded specialist), orchestrated (plan → challenge → build → validate, tracker-backed). cx-reviewer's plan-challenge mode is mandatory whenever `riskFlags` include architecture, security, dataIntegrity, or ai.
 
 Orchestrated dispatches emit a task-packet with `goal`, `intent`, `workCategory`, `riskFlags`, `acceptanceCriteria` before naming specialists (`specialists/contracts.json:construct-to-orchestrator`).
 
@@ -45,9 +45,18 @@ General conversation is still valid for scoping, clarification, and lightweight
 
 1. **Gates**. `framingChallenge`, `externalResearch`, `docAuthoring`
 2. **Contract chain**. typed handoffs from `specialists/contracts.json`. Call `agent_contract` with `handoffPacket` from `orchestration_policy`.
-3. **Specialist sequence**. dispatch plan with ordering/parallel markers.
+3. **Specialist sequence**. the engine's job, not yours — see below.
 4. **Team routing**. name `teamRouting.primaryTeam` in the dispatch plan; route through `teamRouting.requiredApprovals` before DONE; if `teamRouting.blockedStatus` is set, stop and escalate along its `escalationPath` rather than proceeding.
 
+## Dispatch one step at a time <!-- cx:prio=1 -->
+
+Sequencing a multi-specialist chain is the flow engine's job (ADR-0067), not something to hold in your own context across turns. Once `orchestration_policy` says the track is not immediate, drive dispatch through `orchestration_delegation_next`, not by reading a full plan and self-sequencing:
+
+- Mint a `run_id` for this dispatch (a session or task id is fine) and call `orchestration_delegation_next` with the same `request`/`fileCount`/`moduleCount` you gave `orchestration_policy`, plus that `run_id`.
+- Act on exactly the returned `currentDelegation` — its `role`, `reason`, and `handoffContract` — and nothing else. Do not pre-plan the rest of the chain from a remembered dispatch plan.
+- Call again with the same `run_id` for the next specialist. Repeat until `done: true`.
+- The chain survives a restart: calling again with the same `run_id` in a later turn or session continues from wherever it left off, never re-running a specialist already dispatched.
+
 Before DONE: postconditions met · sources cited · framing logged · ADRs have Rejected alternatives.
 
 ## Branch + commit approval <!-- cx:prio=1 -->

package/registry/agent-manifest.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://construct.dev/schemas/agent-manifest.v1.json",
+  "version": 1,
+  "kind": "agent-execution-manifest",
+  "description": "How an agent should reach Construct: MCP-first tool surface, with OpenCode as the primary human conversation surface. Source-of-truth values (core tool set, long-tail dispatcher) are verified against lib/mcp/server.mjs by tests/agent-manifest.test.mjs.",
+  "sources": {
+    "coreTools": "lib/mcp/server.mjs (CORE_TOOL_NAMES)",
+    "longTail": "lib/mcp/server.mjs (CONSTRUCT_CALL_TOOL)",
+    "surfaceTiers": "lib/registry/surface-map.mjs (SURFACE_TIERS, COMMAND_SURFACE)",
+    "capabilities": "registry/capabilities.json",
+    "credentials": "lib/mcp/server.mjs (config.env injection), lib/providers/secret-resolver.mjs"
+  },
+  "toolSurface": {
+    "model": "core-plus-long-tail",
+    "rationale": "ListTools front-loads a small core; everything else is reachable through the `call` gateway or discovered by intent via `find_tool`, so the schema stays small and small models stop hallucinating tool names. The long tail is reachable, just not front-loaded.",
+    "core": [
+      {
+        "name": "orchestration_policy",
+        "use": "Classify intent and get the specialist routing policy for a request."
+      },
+      {
+        "name": "orchestration_run",
+        "use": "Dispatch the routed specialist chain for a request after classifying it."
+      },
+      {
+        "name": "get_skill",
+        "use": "Fetch a role or domain skill playbook by id."
+      },
+      {
+        "name": "get_template",
+        "use": "Read a doc template (prd, adr, runbook, ...) by name before authoring an artifact."
+      },
+      {
+        "name": "search_skills",
+        "use": "Find relevant skills by query."
+      },
+      {
+        "name": "knowledge_search",
+        "use": "Search the project knowledge base."
+      },
+      {
+        "name": "memory_search",
+        "use": "Search durable cross-session memory."
+      },
+      {
+        "name": "project_context",
+        "use": "Read the active project context and working state."
+      },
+      {
+        "name": "summarize_diff",
+        "use": "Summarize a code diff for review or handoff."
+      },
+      {
+        "name": "find_tool",
+        "use": "Find tools by intent when you don't know the exact name; returns ranked tools with schemas."
+      },
+      {
+        "name": "author_artifact",
+        "use": "Materialize a typed artifact you drafted (PRD/ADR/RFC/…) and run the release gate."
+      },
+      {
+        "name": "document_export",
+        "use": "Convert a markdown file to PDF/DOCX/HTML/deck and write it to a path."
+      },
+      {
+        "name": "publish_run",
+        "use": "Run the publish pipeline to export an artifact (figures and demos optional)."
+      },
+      {
+        "name": "artifact_workflow",
+        "use": "Plan a manifest-backed artifact workflow; validate or export locally."
+      },
+      {
+        "name": "workflow_invoke",
+        "use": "Invoke an embedded Construct workflow (prd-draft, architecture-review, …)."
+      },
+      {
+        "name": "triage_recommend",
+        "use": "Recommend intake triage — type, owner, and routing — for a new signal."
+      },
+      {
+        "name": "orchestration_readiness",
+        "use": "Verify that the active MCP session has Construct orchestration tools attached; returns a typed failure reason and next step."
+      }
+    ],
+    "longTail": {
+      "tool": "call",
+      "use": "Invoke any non-core Construct tool by name: put the tool name in `tool` and its arguments in `args`. Call find_tool to discover the right tool by intent; the catalog of valid names is the `tool` enum.",
+      "rationale": "One dispatcher reuses the same handlers, so collapsing the surface costs no capability — every tool stays reachable by name. The manifest deliberately does not enumerate the full tool list; the live catalog is the `call` enum in lib/mcp/server.mjs, and find_tool ranks it by intent. The former gateway name `construct_call` is recovered tolerantly, so a stale name still resolves."
+    }
+  },
+  "humanEntry": {
+    "command": "opencode",
+    "subcommand": null,
+    "use": "A human uses OpenCode as the primary conversation surface after `construct sync` installs the Construct front-door agent, MCP wiring, and runtime plugin. The `construct` CLI remains setup/admin/headless infrastructure.",
+    "rationale": "Construct no longer ships a local conversation UI; OpenCode is primary and other public hosts use generated adapters or MCP.",
+    "surface": "opencode"
+  },
+  "credentials": {
+    "policy": "mcp-mediated",
+    "guidance": "Agents never resolve secrets themselves. The Construct MCP server applies config.env to its process environment at startup, so provider credentials are present for every tool call. The shared secret resolver walks the trusted sources (process env, config.env, ~/.env, project .env, shell rc) and resolves any 1Password reference internally.",
+    "doNot": "Do not instruct or run manual `op read` / `op://` lookups, and do not ask the user to paste keys. MCP tool outputs expose only env-key names and a configured boolean, never credential values.",
+    "source": "lib/mcp/server.mjs config.env injection; lib/providers/secret-resolver.mjs; lib/providers/credential-bootstrap.mjs"
+  },
+  "mcpGaps": {
+    "note": "True gaps only: capabilities that declare MCP unsupported. Flag variants of an MCP-backed capability and retired commands are not gaps.",
+    "gaps": [
+      {
+        "id": "oracle.meta-review",
+        "name": "Oracle Meta-Review",
+        "mcp": "unsupported",
+        "cliFallback": "construct oracle review",
+        "reason": "Declares surfaces.mcp.supported=false in registry/capabilities.json; reach it via the CLI --json twin."
+      }
+    ]
+  }
+}