@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/contract-schemas/decision.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Decision",
+  "description": "Output from cx-architect: a documented architectural or design decision",
+  "type": "object",
+  "required": ["type", "goal", "approach", "tasks", "risks", "acceptanceCriteria"],
+  "properties": {
+    "type": { "type": "string", "enum": ["decision"] },
+    "goal": { "type": "string", "description": "Objective restated in one sentence" },
+    "approach": { "type": "string", "description": "Chosen strategy and rationale" },
+    "alternativesConsidered": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["description", "owner", "complexity"],
+        "properties": {
+          "description": { "type": "string" },
+          "owner": { "type": "string" },
+          "complexity": { "type": "string", "enum": ["S", "M", "L"] }
+        }
+      }
+    },
+    "risks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["description", "mitigation"],
+        "properties": {
+          "description": { "type": "string" },
+          "mitigation": { "type": "string" }
+        }
+      }
+    },
+    "acceptanceCriteria": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "doNotTouch": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Files or systems that must stay unchanged"
+    }
+  },
+  "additionalProperties": false
+}

package/lib/contract-schemas/implementation.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Implementation",
+  "description": "Output from cx-engineer: summary of changes made",
+  "type": "object",
+  "required": ["type", "status", "filesChanged", "verificationChecklist"],
+  "properties": {
+    "type": { "type": "string", "enum": ["implementation"] },
+    "status": {
+      "type": "string",
+      "enum": ["DONE", "BLOCKED", "NEEDS_MAIN_INPUT"]
+    },
+    "filesChanged": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "action"],
+        "properties": {
+          "path": { "type": "string" },
+          "action": { "type": "string", "enum": ["created", "modified", "deleted"] },
+          "summary": { "type": "string" }
+        }
+      }
+    },
+    "verificationChecklist": {
+      "type": "object",
+      "properties": {
+        "compilesWithoutErrors": { "type": "boolean" },
+        "existingTestsPass": { "type": "boolean" },
+        "newBehaviorHasCoverage": { "type": "boolean" },
+        "noHardcodedSecrets": { "type": "boolean" },
+        "noFileOver800Lines": { "type": "boolean" }
+      },
+      "required": ["compilesWithoutErrors", "existingTestsPass", "newBehaviorHasCoverage", "noHardcodedSecrets", "noFileOver800Lines"]
+    },
+    "blockerDescription": {
+      "type": "string",
+      "description": "Required when status is BLOCKED or NEEDS_MAIN_INPUT"
+    },
+    "needsMainInput": {
+      "type": "object",
+      "description": "Required when status is NEEDS_MAIN_INPUT",
+      "properties": {
+        "taskKey": { "type": "string" },
+        "question": { "type": "string" },
+        "safeDefault": { "type": "string" }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/lib/contract-schemas/review-report.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewReport",
+  "description": "Output from cx-reviewer or cx-security: findings from a code or security review",
+  "type": "object",
+  "required": ["type", "target", "verdict", "findings"],
+  "properties": {
+    "type": { "type": "string", "enum": ["review-report"] },
+    "target": { "type": "string", "description": "Files or scope reviewed" },
+    "verdict": {
+      "type": "string",
+      "enum": ["APPROVED", "APPROVED_WITH_WARNINGS", "BLOCKED"],
+      "description": "APPROVED = no CRITICAL/HIGH. APPROVED_WITH_WARNINGS = only HIGH (merge with caution). BLOCKED = CRITICAL found."
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["severity", "category", "location", "description", "fix"],
+        "properties": {
+          "severity": { "type": "string", "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"] },
+          "category": { "type": "string", "description": "e.g. correctness, security, regression, coverage, maintainability" },
+          "location": { "type": "string", "description": "file:line" },
+          "description": { "type": "string" },
+          "fix": { "type": "string", "description": "Concrete remediation" }
+        }
+      }
+    },
+    "summary": { "type": "string", "description": "One-paragraph summary of overall quality" }
+  },
+  "additionalProperties": false
+}

package/lib/contract-schemas/test-report.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "TestReport",
+  "description": "Output from cx-qa: results of test planning and execution",
+  "type": "object",
+  "required": ["type", "verdict", "passed", "failed", "coverage"],
+  "properties": {
+    "type": { "type": "string", "enum": ["test-report"] },
+    "verdict": {
+      "type": "string",
+      "enum": ["PASS", "FAIL"],
+      "description": "PASS = all tests green and coverage meets threshold. FAIL = failing tests or coverage below threshold."
+    },
+    "passed": { "type": "integer", "minimum": 0 },
+    "failed": { "type": "integer", "minimum": 0 },
+    "skipped": { "type": "integer", "minimum": 0 },
+    "coverage": {
+      "type": "object",
+      "properties": {
+        "overall": { "type": "number", "description": "0.0–100.0 percentage" },
+        "meetsThreshold": { "type": "boolean" },
+        "threshold": { "type": "number" }
+      }
+    },
+    "failingTests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "error"],
+        "properties": {
+          "name": { "type": "string" },
+          "error": { "type": "string" }
+        }
+      }
+    },
+    "gaps": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Untested behaviors that should have tests"
+    }
+  },
+  "additionalProperties": false
+}

package/lib/contracts/construct-handoff.mjs

@@ -0,0 +1,60 @@
+/**
+ * lib/contracts/construct-handoff.mjs — normalize construct→orchestrator handoffs.
+ *
+ * MCP callers often pass only `goal`; enrich from orchestration_policy before
+ * validateHandoff so incomplete packets do not flood contract-violations.jsonl.
+ */
+
+import { buildConstructToOrchestratorPacket, routeRequest } from '../orchestration-policy.mjs';
+
+export const CONSTRUCT_ORCHESTRATOR_REQUIRED = Object.freeze([
+  'goal',
+  'intent',
+  'workCategory',
+  'riskFlags',
+  'acceptanceCriteria',
+]);
+
+export function needsConstructHandoffEnrichment(artifact) {
+  if (!artifact || typeof artifact !== 'object') return false;
+  return CONSTRUCT_ORCHESTRATOR_REQUIRED.some((field) => !Object.prototype.hasOwnProperty.call(artifact, field));
+}
+
+/**
+ * @param {object} artifact — partial or full handoff packet
+ * @param {object} [opts]
+ * @param {string} [opts.request]
+ * @param {number} [opts.fileCount]
+ * @param {number} [opts.moduleCount]
+ * @param {boolean} [opts.introducesContract]
+ */
+export function enrichConstructOrchestratorHandoff(artifact, opts = {}) {
+  if (!needsConstructHandoffEnrichment(artifact)) return artifact;
+  const request = String(opts.request || artifact.goal || artifact.request || '').trim();
+  const routeOpts = {
+    request,
+    fileCount: opts.fileCount ?? artifact.fileCount ?? 0,
+    moduleCount: opts.moduleCount ?? artifact.moduleCount ?? 0,
+    introducesContract: opts.introducesContract ?? artifact.introducesContract ?? false,
+  };
+  const built = buildConstructToOrchestratorPacket({
+    ...routeOpts,
+    goal: artifact.goal,
+    acceptanceCriteria: artifact.acceptanceCriteria,
+  });
+  if (built) return { ...built, ...artifact };
+
+  const route = routeRequest(routeOpts);
+  const goal = String(artifact.goal || request || 'User-requested work').trim();
+  const acceptanceCriteria = Array.isArray(artifact.acceptanceCriteria) && artifact.acceptanceCriteria.length
+    ? artifact.acceptanceCriteria
+    : ['Dispatch plan emitted with specialists in sequence', 'Acceptance criteria verified before close'];
+  return {
+    goal,
+    intent: route.intent,
+    workCategory: route.workCategory,
+    riskFlags: route.riskFlags || {},
+    acceptanceCriteria,
+    ...artifact,
+  };
+}

package/lib/contracts/validate.mjs

@@ -4,7 +4,7 @@
  * Three validation tiers:
  *   1. Schema shape: contracts.json conforms to contracts.schema.json (minimal
  *      validator — top-level required fields, contract entry required fields).
- *   2. Cross-file refs: every output.schema points to a real file in lib/schemas/,
+ *   2. Cross-file refs: every output.schema points to a real file in lib/contract-schemas/,
  *      every producer/consumer name resolves to an agent or persona in
  *      specialists/registry.json, every well-known event/intake string is reachable.
  *   3. Runtime handoff: a single artifact validated against the schema referenced
@@ -19,6 +19,10 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  missingRequiredReviewers,
+} from '../artifact-reviewers.mjs';
+import { inferArtifactTypeFromPath } from '../artifact-type-from-path.mjs';
 import { POSTCONDITIONS, validateBinaryPostconditions } from '../specialists/postconditions.mjs';
 import { logViolation } from './violation-log.mjs';
 
@@ -244,7 +248,12 @@ export function validateHandoff(opts = {}) {
     const absPath = isAbsolutePath(declaredArtifactPath)
       ? declaredArtifactPath
       : join(repoRoot, declaredArtifactPath);
-    const pcErrors = validateArtifactPostconditions({ contract, artifactPath: absPath });
+    const pcErrors = validateArtifactPostconditions({
+      contract,
+      artifactPath: absPath,
+      cwd: repoRoot,
+      rootDir: repoRoot,
+    });
     for (const e of pcErrors) errors.push(e);
   }
 
@@ -397,7 +406,7 @@ function claimsHaveCitations(body) {
  * disk. Postconditions can be strings (descriptive, ignored here) or objects
  * with { id, check, field?, section? }. Returns an array of error strings.
  */
-export function validateArtifactPostconditions({ contract, artifactPath }) {
+export function validateArtifactPostconditions({ contract, artifactPath, cwd = process.cwd(), rootDir } = {}) {
   if (!contract?.postconditions?.length) return [];
   if (!artifactPath || !existsSync(artifactPath)) {
     const structured = contract.postconditions.filter((p) => typeof p === 'object');
@@ -473,6 +482,26 @@ export function validateArtifactPostconditions({ contract, artifactPath }) {
         }
         break;
       }
+      case 'artifact-reviewers-seen': {
+        let missing;
+        if (pc.fromManifest) {
+          missing = missingRequiredReviewers({ filePath: artifactPath, cwd, rootDir });
+        } else {
+          missing = missingRequiredReviewers({
+            docType: pc.docType || inferArtifactTypeFromPath(artifactPath, { rootDir: cwd }),
+            filePath: artifactPath,
+            cwd,
+            rootDir,
+          });
+        }
+        if (Array.isArray(pc.reviewers) && pc.reviewers.length > 0) {
+          missing = missing.filter((r) => pc.reviewers.includes(r));
+        }
+        if (missing.length > 0) {
+          errors.push(`[${tag}] required reviewers not in agent log: ${missing.join(', ')}`);
+        }
+        break;
+      }
       default:
         errors.push(`[${tag}] unknown postcondition check: ${pc.check}`);
     }

package/lib/contracts/violation-log.mjs

@@ -23,7 +23,7 @@
  * verifyChain; all writers go through logViolation.
  */
 
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
@@ -55,6 +55,51 @@ function logFile(repoRoot) {
 // log writes from the developer's project log.
 export function violationLogPath(repoRoot) { return logFile(repoRoot); }
 
+function supersedeMarkerFile(repoRoot) {
+  if (repoRoot) return join(repoRoot, '.cx', 'contract-violations-superseded.json');
+  return resolveProjectScopedPath('contract-violations-superseded.json', { ensureDir: false });
+}
+
+/**
+ * Read ISO timestamp before which violations are ignored for oracle/doctor counts.
+ */
+export function readViolationSupersedeCutoff(repoRoot) {
+  const file = supersedeMarkerFile(repoRoot);
+  if (!existsSync(file)) return null;
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf8'));
+    const ts = data?.supersededBefore;
+    const parsed = Date.parse(String(ts ?? ''));
+    return Number.isFinite(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Mark pre-fix contract violations as superseded for hygiene surfaces.
+ * Forensic log is preserved; oracle read model ignores older entries.
+ */
+export function markContractViolationsSuperseded({ repoRoot, reason = 'superseded by contract hygiene repair' } = {}) {
+  const file = supersedeMarkerFile(repoRoot);
+  mkdirSync(dirname(file), { recursive: true });
+  const payload = {
+    supersededBefore: new Date().toISOString(),
+    reason,
+  };
+  writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`);
+  return payload;
+}
+
+function violationMatchesTail(tail, contractId, direction, missing, packet) {
+  if (!tail) return false;
+  if (tail.contractId !== contractId || tail.direction !== direction) return false;
+  const keys = packet && typeof packet === 'object' ? Object.keys(packet).sort() : null;
+  const tailKeys = Array.isArray(tail.packet_keys) ? [...tail.packet_keys].sort() : null;
+  return JSON.stringify(tail.missing) === JSON.stringify(missing)
+    && JSON.stringify(tailKeys) === JSON.stringify(keys);
+}
+
 function sha256(input) { return createHash('sha256').update(input).digest('hex'); }
 
 function readLastAgent() {
@@ -91,6 +136,8 @@ function nextSequence(repoRoot) {
 export function logViolation(contractId, direction, missing, packet, extra = {}) {
   try {
     const { repoRoot, ...persistedExtra } = extra || {};
+    const tail = readTailRecord(repoRoot);
+    if (violationMatchesTail(tail, contractId, direction, missing, packet)) return;
     const file = logFile(repoRoot);
     mkdirSync(dirname(file), { recursive: true });
     const record = {
@@ -113,17 +160,23 @@ export function logViolation(contractId, direction, missing, packet, extra = {})
  * Rotated segments are intentionally not included — this is the doctor
  * surface, scoped to the active window.
  */
-export function recentViolations({ windowMs = 24 * 60 * 60 * 1000 } = {}) {
-  const file = logFile();
+export function recentViolations({ windowMs = 24 * 60 * 60 * 1000, repoRoot } = {}) {
+  const file = logFile(repoRoot);
   if (!existsSync(file)) return [];
+  const supersedeCutoff = readViolationSupersedeCutoff(repoRoot);
   try {
-    const cutoff = Date.now() - windowMs;
+    const windowCutoff = Date.now() - windowMs;
     return readFileSync(file, 'utf8')
       .trim()
       .split('\n')
       .filter(Boolean)
       .map((line) => { try { return JSON.parse(line); } catch { return null; } })
-      .filter((r) => r && new Date(r.ts).getTime() >= cutoff);
+      .filter((r) => {
+        if (!r) return false;
+        const ts = new Date(r.ts).getTime();
+        if (supersedeCutoff != null && ts <= supersedeCutoff) return false;
+        return ts >= windowCutoff;
+      });
   } catch { return []; }
 }
 

package/lib/dashboard-demo.mjs

@@ -0,0 +1,71 @@
+/**
+ * lib/dashboard-demo.mjs — Construct cockpit Playwright demo adapter.
+ *
+ * Resolves dashboard recording manifests (or legacy script bridge) and delegates
+ * to lib/playwright-demo.mjs with dashboard workspace defaults.
+ */
+
+import path from 'node:path';
+import { loadDemoRecording } from './demo-recording.mjs';
+import {
+  detectPlaywrightDemo,
+  recordPlaywrightDemo,
+  collectVideoFiles,
+  newestVideo,
+  finalizeDemoVideo,
+  locateFfmpeg,
+  transcodeWebmToMp4,
+  resolvePlaywrightPackage,
+} from './playwright-demo.mjs';
+
+export {
+  collectVideoFiles,
+  newestVideo,
+  finalizeDemoVideo,
+  locateFfmpeg,
+  transcodeWebmToMp4,
+  resolvePlaywrightPackage,
+};
+
+export function dashboardWorkspaceRoot(repoRoot) {
+  return path.join(repoRoot, 'apps', 'dashboard');
+}
+
+export function detectDashboardDemo({ cwd = process.cwd(), repoRoot } = {}) {
+  const root = repoRoot || cwd;
+  return detectPlaywrightDemo({ workspace: dashboardWorkspaceRoot(root), repoRoot: root, cwd });
+}
+
+export function recordDashboardDemo(name, {
+  cwd = process.cwd(),
+  repoRoot,
+  outputDir,
+  outputPath = null,
+  format = 'mp4',
+  artifactDir = null,
+  artifactFile = null,
+  env = process.env,
+} = {}) {
+  const root = repoRoot || cwd;
+  const recording = loadDemoRecording(name, { cwd, repoRoot: root });
+
+  if (!recording) {
+    const detection = detectDashboardDemo({ cwd, repoRoot: root });
+    if (!detection.present) {
+      return { ok: false, name, missing: detection.missing, message: detection.message };
+    }
+    return { ok: false, name, message: `No recording manifest or dashboard demo script for ${name}` };
+  }
+
+  const outDir = outputDir || path.join(cwd, '.cx', 'demos', 'dashboard');
+  return recordPlaywrightDemo(recording, {
+    cwd,
+    repoRoot: root,
+    outputDir: outDir,
+    outputPath,
+    format,
+    artifactDir,
+    artifactFile,
+    env,
+  });
+}

package/lib/dashboard-static.mjs

@@ -11,6 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { sanitizeNpmSpawnEnv } from './npm-spawn-env.mjs';
 
 function walkFiles(rootDir, currentDir = rootDir) {
   if (!fs.existsSync(currentDir)) return [];
@@ -125,11 +126,24 @@ export function buildDashboardStatic({
   spawnSyncFn = spawnSync,
 } = {}) {
   const { dashboardDir } = getDashboardPaths({ rootDir });
-  const result = spawnSyncFn('npm', ['run', 'build'], {
-    cwd: dashboardDir,
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
+  const nextCache = path.join(dashboardDir, '.next');
+  fs.rmSync(nextCache, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+
+  const env = sanitizeNpmSpawnEnv(process.env);
+  let result;
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    result = spawnSyncFn('npm', ['--prefix', dashboardDir, 'run', 'build'], {
+      cwd: rootDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env,
+    });
+    if (result.status === 0) break;
+    const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+    const transientRename = /ENOENT.*rename.*\.next\/(export|server\/pages)\/500\.html/.test(output);
+    if (!transientRename) break;
+    fs.rmSync(nextCache, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  }
   if (result.status !== 0) {
     throw new Error((result.stderr || result.stdout || 'dashboard build failed').trim());
   }

package/lib/decisions/registry.mjs

@@ -23,6 +23,8 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, resolve, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { readRuleFile } from '../rules-read.mjs';
+
 export const DECISION_STATUSES = ['proposed', 'accepted', 'superseded', 'deprecated'];
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
@@ -35,7 +37,7 @@ const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const ENFORCES_LINE_RE = /^(?:\/\/|#|\*)?\s*@enforces\s+(\S+)\s*$/;
 
 // The body carries Status and Supersedes as markdown definition lines, not
-// frontmatter (see docs/adr/_template.md); parse them positionally.
+// frontmatter (see docs/adr/templates/_template.md); parse them positionally.
 
 // ADR field styles vary across the lane: inline bold (`- **Status**: x`,
 // `**Status:** X`) and heading-then-value (`## Status` followed by the value on
@@ -184,9 +186,9 @@ function ruleDecisions({ repoRoot, bindings }) {
   const dir = join(repoRoot, 'rules');
   const out = [];
   for (const file of walk(dir, (f) => f.endsWith('.md'))) {
-    const text = readFileSync(file, 'utf8');
-    const fm = parseFrontmatter(text);
     const rel = relative(repoRoot, file);
+    const text = readRuleFile(rel, { rootDir: repoRoot, source: 'validation', callerContext: 'decisions-registry' });
+    const fm = parseFrontmatter(text);
     const id = `rule:${relative(join(repoRoot, 'rules'), file).replace(/\.md$/, '')}`;
     const enforcedBy = fm.enforced_by ? fm.enforced_by.split(',').map((s) => s.trim()).filter(Boolean) : [];
     const enforcingTests = bindings.get(id) || [];