@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/artifact-release-gate.mjs

@@ -0,0 +1,171 @@
+/**
+ * lib/artifact-release-gate.mjs — Real-org release validation for typed artifacts.
+ *
+ * Composes structure/visual lint, citation discipline, prose heuristics, and
+ * optional reviewer sign-off from the artifact manifest releaseGate block.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { lintDocStructure, lintDocVisuals } from './templates/visual-requirements.mjs';
+import { getArtifactEntry, resolveToneForArtifact } from './artifact-manifest.mjs';
+import { lintFile } from './comment-lint.mjs';
+import {
+  missingRequiredReviewers,
+  parseReleaseGateFrontmatter,
+} from './artifact-reviewers.mjs';
+import { inferArtifactTypeFromPath } from './artifact-type-from-path.mjs';
+
+function countProseParagraphs(body) {
+  const blocks = body.split(/\n\s*\n/).map((b) => b.trim()).filter(Boolean);
+  let prose = 0;
+  for (const b of blocks) {
+    const first = b.split('\n')[0].trimStart();
+    const isHeading = first.startsWith('#');
+    const isList = /^([-*+]\s|\d+[.)]\s|>\s)/.test(first);
+    const isTable = first.startsWith('|');
+    const isFence = first.startsWith('```');
+    if (isHeading || isList || isTable || isFence) continue;
+    const sentences = (b.match(/[.!?](\s|$)/g) || []).length;
+    if (sentences >= 2 || b.length >= 200) prose++;
+  }
+  return prose;
+}
+
+function countCitations(body) {
+  const patterns = [
+    /\bhttps?:\/\/[^\s)]+/g,
+    /\barxiv:\s*\d{4}\.\d{4,5}/gi,
+    /\[source:[^\]]+\]/gi,
+    /\(accessed\s+\d{4}-\d{2}-\d{2}\)/gi,
+  ];
+  const hits = new Set();
+  for (const re of patterns) for (const m of body.match(re) || []) hits.add(m.trim().toLowerCase());
+  return hits.size;
+}
+
+export function validateArtifactRelease({
+  filePath,
+  type,
+  cwd = process.cwd(),
+  rootDir,
+  reviewersSeen,
+} = {}) {
+  const resolvedType = type || inferArtifactTypeFromPath(filePath, { rootDir: cwd });
+  const entry = getArtifactEntry(resolvedType, { rootDir });
+  if (!entry) {
+    return { ok: false, errors: [`Unknown artifact type: ${resolvedType}`], warnings: [], tone: null };
+  }
+
+  const { bypass, reason } = parseReleaseGateFrontmatter(filePath);
+  if (bypass) {
+    if (!reason) {
+      return {
+        ok: false,
+        errors: ['cx_release_gate: bypass requires cx_release_gate_reason in frontmatter'],
+        warnings: [],
+        tone: resolveToneForArtifact(resolvedType, { cwd, rootDir }),
+        type: resolvedType,
+        filePath,
+        bypassed: true,
+      };
+    }
+    return {
+      ok: true,
+      errors: [],
+      warnings: [`release gate bypassed: ${reason}`],
+      tone: resolveToneForArtifact(resolvedType, { cwd, rootDir }),
+      type: resolvedType,
+      filePath,
+      bypassed: true,
+    };
+  }
+
+  const gate = entry.releaseGate ?? {};
+  const errors = [];
+  const warnings = [];
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const body = raw.replace(/^---\n[\s\S]*?\n---\n/, '');
+
+  if (gate.structuralLint !== false) {
+    errors.push(...lintDocStructure(filePath, resolvedType));
+    errors.push(...lintDocVisuals(filePath, resolvedType));
+  }
+
+  if (gate.citationLint) {
+    const isShippedTemplate = filePath.includes(`${path.sep}templates${path.sep}docs${path.sep}`);
+    if (!isShippedTemplate) {
+      const lint = lintFile(filePath);
+      const artifactIssues = [...(lint.errors ?? []), ...(lint.warnings ?? [])].filter((w) => w.kind === 'artifact');
+      for (const issue of artifactIssues) errors.push(issue.message || String(issue));
+      const citations = countCitations(body);
+      const unverified = /\[unverified\]/i.test(body);
+      if (citations < 1 && !unverified) {
+        errors.push('citationLint: no verifiable sources or [unverified] markers');
+      }
+    }
+  }
+
+  const minProse = gate.proseMinimum ?? 0;
+  if (minProse > 0) {
+    const prose = countProseParagraphs(body);
+    if (prose < minProse) {
+      errors.push(`proseMinimum: ${prose} paragraphs (need ${minProse})`);
+    }
+  }
+
+  const missing = missingRequiredReviewers({
+    docType: resolvedType,
+    filePath,
+    rootDir,
+    cwd,
+    reviewersSeen,
+  });
+  if (missing.length > 0) {
+    warnings.push(`requiredReviewers not seen in agent log: ${missing.join(', ')}`);
+  }
+
+  const tone = resolveToneForArtifact(resolvedType, { cwd, rootDir });
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    tone,
+    type: resolvedType,
+    filePath,
+  };
+}
+
+export async function runArtifactValidateCli(args = []) {
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const filePath = positional[0];
+  const typeArg = args.find((a) => a.startsWith('--type='));
+  const json = args.includes('--json');
+
+  if (!filePath || !typeArg) {
+    process.stderr.write('Usage: construct artifact validate <path> --type=<doc-type> [--json]\n');
+    process.exit(1);
+  }
+
+  const type = typeArg.split('=')[1];
+  const result = validateArtifactRelease({ filePath, type });
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(`Artifact release gate: ${type}\n`);
+    process.stdout.write(`  Tone: ${result.tone}\n`);
+    if (result.errors.length) {
+      process.stdout.write(`  Errors (${result.errors.length}):\n`);
+      for (const e of result.errors) process.stdout.write(`    - ${e}\n`);
+    }
+    if (result.warnings.length) {
+      process.stdout.write(`  Warnings (${result.warnings.length}):\n`);
+      for (const w of result.warnings) process.stdout.write(`    - ${w}\n`);
+    }
+    process.stdout.write(result.ok ? '  Result: PASS\n' : '  Result: FAIL\n');
+  }
+
+  if (!result.ok) process.exit(1);
+}

package/lib/artifact-reviewers.mjs

@@ -0,0 +1,68 @@
+/**
+ * lib/artifact-reviewers.mjs — Required reviewer resolution from manifest + agent log.
+ *
+ * Shared by artifact release gate, contract postconditions, and Oracle read-model.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getArtifactEntry } from './artifact-manifest.mjs';
+import { inferArtifactTypeFromPath } from './artifact-type-from-path.mjs';
+
+const RELEASE_GATE_BYPASS_FIELD = 'cx_release_gate';
+const RELEASE_GATE_REASON_FIELD = 'cx_release_gate_reason';
+
+export function readAgentLogReviewers(projectRoot = process.cwd()) {
+  const logPath = path.join(projectRoot, '.cx', 'agent-log.jsonl');
+  if (!fs.existsSync(logPath)) return new Set();
+  const reviewers = new Set();
+  for (const line of fs.readFileSync(logPath, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line);
+      const id = row.agent || row.specialist;
+      if (id) reviewers.add(String(id));
+    } catch { /* skip */ }
+  }
+  return reviewers;
+}
+
+export function parseReleaseGateFrontmatter(filePath) {
+  try {
+    const head = fs.readFileSync(filePath, 'utf8').slice(0, 4096);
+    const match = head.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return { bypass: false, reason: null };
+    const fm = {};
+    for (const line of match[1].split('\n')) {
+      const m = line.match(/^([\w-]+)\s*:\s*(.+)$/);
+      if (m) fm[m[1]] = m[2].trim().replace(/^['"]|['"]$/g, '');
+    }
+    const bypass = fm[RELEASE_GATE_BYPASS_FIELD] === 'bypass';
+    return { bypass, reason: fm[RELEASE_GATE_REASON_FIELD] ?? null };
+  } catch {
+    return { bypass: false, reason: null };
+  }
+}
+
+export function resolveRequiredReviewers({ docType, filePath, rootDir, cwd = process.cwd() }) {
+  let type = docType;
+  if (!type && filePath) {
+    type = inferArtifactTypeFromPath(filePath, { rootDir: cwd });
+  }
+  if (!type) return [];
+  const entry = getArtifactEntry(type, { rootDir });
+  return entry?.releaseGate?.requiredReviewers ?? [];
+}
+
+export function missingRequiredReviewers({
+  docType,
+  filePath,
+  rootDir,
+  cwd = process.cwd(),
+  reviewersSeen,
+} = {}) {
+  const required = resolveRequiredReviewers({ docType, filePath, rootDir, cwd });
+  if (required.length === 0) return [];
+  const seen = reviewersSeen ?? readAgentLogReviewers(cwd);
+  return required.filter((r) => !seen.has(r) && !seen.has(r.replace(/^cx-/, 'cx-')));
+}

package/lib/artifact-type-from-path.mjs

@@ -0,0 +1,79 @@
+/**
+ * lib/artifact-type-from-path.mjs — Infer manifest doc type from artifact file paths.
+ *
+ * Resolves a manifest doc type when --type is omitted.
+ * Resolution order: YAML frontmatter cx_doc_type → directory heuristics → filename hints.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { artifactTypes } from './artifact-manifest.mjs';
+
+const KNOWN = new Set(artifactTypes());
+
+function readFrontmatterType(filePath) {
+  try {
+    const head = fs.readFileSync(filePath, 'utf8').slice(0, 4096);
+    const match = head.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return null;
+    for (const line of match[1].split('\n')) {
+      const m = line.match(/^(?:cx_doc_type|artifactType|doc_type)\s*:\s*(.+)$/);
+      if (m) {
+        const value = m[1].trim().replace(/^['"]|['"]$/g, '');
+        return KNOWN.has(value) ? value : null;
+      }
+    }
+  } catch { /* unreadable */ }
+  return null;
+}
+
+function inferPrdSubtype(rel, base) {
+  const blob = `${rel} ${base}`.toLowerCase();
+  if (/meta[\s-]?prd/.test(blob)) return 'meta-prd';
+  if (/platform/.test(blob)) return 'prd-platform';
+  if (/business/.test(blob)) return 'prd-business';
+  return 'prd';
+}
+
+function inferRfcSubtype(rel, base) {
+  const blob = `${rel} ${base}`.toLowerCase();
+  if (/platform/.test(blob)) return 'rfc-platform';
+  return 'rfc';
+}
+
+const PREFIX_RULES = [
+  [/^docs\/prd\//, inferPrdSubtype],
+  [/^docs\/adr\//, () => 'adr'],
+  [/^docs\/rfc\//, inferRfcSubtype],
+  [/^docs\/research\//, () => 'research-brief'],
+  [/^docs\/runbooks?\//, () => 'runbook'],
+  [/^\.cx\/research\//, () => 'research-brief'],
+];
+
+export function isArtifactGatePath(relPath) {
+  const rel = relPath.replace(/\\/g, '/');
+  if (!rel.endsWith('.md')) return false;
+  if (rel.startsWith('templates/docs/')) return false;
+  if (/^docs\//.test(rel) || /^\.cx\/research\//.test(rel)) return true;
+  return false;
+}
+
+export function inferArtifactTypeFromPath(filePath, { rootDir = process.cwd() } = {}) {
+  const rel = path.relative(rootDir, filePath).replace(/\\/g, '/');
+  if (!rel.endsWith('.md')) return null;
+
+  const fromFm = readFrontmatterType(filePath);
+  if (fromFm) return fromFm;
+
+  if (!isArtifactGatePath(rel)) return null;
+
+  const base = path.basename(filePath, path.extname(filePath));
+  for (const [re, resolver] of PREFIX_RULES) {
+    if (re.test(rel)) {
+      const type = typeof resolver === 'function' ? resolver(rel, base) : resolver;
+      return KNOWN.has(type) ? type : null;
+    }
+  }
+
+  return null;
+}

package/lib/artifact-workflow.mjs

@@ -0,0 +1,252 @@
+/**
+ * lib/artifact-workflow.mjs — intent-to-artifact workflow planning.
+ *
+ * Planning describes specialist work and manifest ordering without reporting a
+ * planned role as executed.
+ */
+
+import { existsSync } from 'node:fs';
+import { loadProjectConfig } from './config/project-config.mjs';
+import {
+  BRAND_CAPABLE_FORMATS,
+  artifactTypes,
+  resolveArtifactType,
+  resolveArtifactWorkflowContract,
+} from './artifact-manifest.mjs';
+import { inferArtifactTypeFromPath } from './artifact-type-from-path.mjs';
+import { validateArtifactRelease } from './artifact-release-gate.mjs';
+import { exportMarkdown } from './document-export.mjs';
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function findRequestedTypes(input, { rootDir, cwd }) {
+  const text = String(input ?? '').toLowerCase();
+  const matches = [];
+  for (const type of artifactTypes({ rootDir, cwd }).sort((a, b) => b.length - a.length)) {
+    const entry = resolveArtifactType(type, { rootDir, cwd }).entry;
+    for (const candidate of [type, ...(entry?.aliases ?? [])]) {
+      if (new RegExp(`(?:^|[^a-z0-9])${escapeRegex(candidate.toLowerCase())}(?:$|[^a-z0-9])`, 'i').test(text)) {
+        matches.push(type);
+        break;
+      }
+    }
+  }
+  return [...new Set(matches)];
+}
+
+function inferFormat(input, requestedFormat) {
+  if (requestedFormat) return String(requestedFormat).toLowerCase();
+  const text = String(input ?? '').toLowerCase();
+  for (const format of ['pptx', 'docx', 'pdf', 'deck', 'html', 'doc', 'rtf', 'odt', 'epub', 'tex', 'txt', 'mdx', 'md']) {
+    if (new RegExp(`\\b${format}\\b`, 'i').test(text)) return format;
+  }
+  return null;
+}
+
+function inferBranding(input, requestedBranding) {
+  if (requestedBranding) return requestedBranding;
+  return /\b(?:unbranded|plain|without (?:the )?construct brand)\b/i.test(String(input ?? '')) ? 'plain' : 'construct';
+}
+
+function buildSteps({ contract, input, targetFormat, branding }) {
+  const text = String(input ?? '').toLowerCase();
+  const needsResearch = Boolean(contract.researchProfile) && /\b(?:research|source|evidence|validate claims)\b/.test(text);
+  const needsReview = /\b(?:review|critique|audit|feedback)\b/.test(text) || contract.requiredReviewers.length > 0;
+  const rewrite = /\b(?:rewrite|revise|edit|polish|improve)\b/.test(text);
+  const steps = [];
+  if (needsResearch) steps.push({ id: 'research', action: 'research', roles: [], required: false, reason: `research profile: ${contract.researchProfile}` });
+  if (needsReview) steps.push({ id: 'review', action: 'review', roles: contract.reviewerChain, required: contract.requiredReviewers.length > 0, reason: 'review occurs before any rewrite' });
+  steps.push({
+    id: rewrite ? 'rewrite' : 'author',
+    action: rewrite ? 'rewrite' : 'author',
+    roles: contract.authorChain,
+    required: true,
+    reason: rewrite ? 'requested revision after review' : 'manifest author chain',
+  });
+  if (contract.validation.releaseGate !== false) {
+    steps.push({ id: 'validate', action: 'validate', roles: [], required: true, reason: 'manifest validation policy' });
+  }
+  if (targetFormat && BRAND_CAPABLE_FORMATS.includes(targetFormat) && branding === 'construct') {
+    steps.push({ id: 'brand', action: 'brand', roles: [], required: true, reason: 'default Construct branding for brand-capable format' });
+  }
+  if (targetFormat) steps.push({ id: 'export', action: 'export', roles: [], required: true, format: targetFormat, reason: 'requested distribution format' });
+  return steps;
+}
+
+/**
+ * Build an artifact plan from an ordinary request. A missing or ambiguous
+ * class is a clarification result, never an implicit PRD route.
+ */
+export function planArtifactWorkflow(request = {}, { cwd = process.cwd(), rootDir } = {}) {
+  const input = request.input ?? request.request ?? '';
+  const sourcePath = request.sourcePath ?? request.filePath ?? '';
+  const project = request.projectConfig ?? loadProjectConfig(cwd).config;
+  const requested = request.artifactType ?? request.documentClass ?? null;
+  const pathType = sourcePath && existsSync(sourcePath) ? inferArtifactTypeFromPath(sourcePath, { rootDir: cwd }) : null;
+  const inferredTypes = requested ? [] : findRequestedTypes(input, { rootDir, cwd });
+  const candidates = requested ? [requested] : [...new Set([pathType, ...inferredTypes].filter(Boolean))];
+
+  if (candidates.length !== 1) {
+    return {
+      kind: 'artifact-workflow',
+      status: 'needs-classification',
+      plannedSteps: [],
+      executedSteps: [],
+      skippedSteps: [],
+      producedFiles: [],
+      validation: null,
+      appliedOverrides: [],
+      clarification: candidates.length > 1
+        ? `Request names multiple document classes (${candidates.join(', ')}). Specify one registered class.`
+        : 'Specify a registered document class, use a typed source path, or register the requested class in specialists/artifact-manifest.json.',
+    };
+  }
+
+  const resolution = resolveArtifactType(candidates[0], { rootDir, cwd });
+  if (resolution.status !== 'registered') {
+    return {
+      kind: 'artifact-workflow',
+      status: 'needs-classification',
+      plannedSteps: [],
+      executedSteps: [],
+      skippedSteps: [],
+      producedFiles: [],
+      validation: null,
+      appliedOverrides: [],
+      clarification: resolution.guidance,
+    };
+  }
+
+  const targetFormat = inferFormat(input, request.format ?? request.targetFormat);
+  const requestedBranding = inferBranding(input, request.branding);
+  const contract = resolveArtifactWorkflowContract(resolution.type, {
+    rootDir,
+    cwd,
+    projectConfig: project,
+    overrides: request.overrides,
+  });
+  const branding = request.branding ?? (requestedBranding === 'plain' ? 'plain' : (contract.outputs.branding ?? 'construct'));
+  const steps = buildSteps({ contract, input, targetFormat, branding });
+  const unavailableFormat = targetFormat && !contract.outputs.formats.includes(targetFormat);
+
+  return {
+    kind: 'artifact-workflow',
+    status: unavailableFormat ? 'needs-classification' : 'planned',
+    documentClass: contract.documentClass,
+    artifactType: contract.type,
+    sourcePath: sourcePath || null,
+    target: {
+      format: targetFormat,
+      audience: /\bcustomer(?:-facing)?\b/i.test(input) ? 'customer' : 'internal',
+      branding,
+      brandCapable: Boolean(targetFormat && BRAND_CAPABLE_FORMATS.includes(targetFormat)),
+    },
+    contract,
+    plannedSteps: steps,
+    executedSteps: [],
+    skippedSteps: [],
+    producedFiles: [],
+    validation: null,
+    appliedOverrides: contract.appliedOverrides,
+    clarification: unavailableFormat ? `${targetFormat} is not an output capability for ${contract.type}.` : null,
+  };
+}
+
+/**
+ * Produce a provenance-preserving workflow run report. Specialist authoring
+ * and review are never fabricated: Construct can plan them, but only reports
+ * them as executed when a host returns execution evidence (not available in
+ * the deterministic entry point). Validation/export are local operations and
+ * run only with the explicit durable-write approval mode.
+ */
+export function runArtifactWorkflow(request = {}, { cwd = process.cwd(), rootDir } = {}) {
+  const plan = planArtifactWorkflow(request, { cwd, rootDir });
+  const approvalMode = request.approvalMode ?? 'proposal-only';
+  const report = {
+    reportVersion: 1,
+    kind: 'artifact-workflow-run',
+    status: plan.status === 'planned' ? 'planned' : plan.status,
+    approval: {
+      mode: approvalMode,
+      durableWriteAllowed: approvalMode === 'allow-durable-write',
+    },
+    plan,
+    plannedSteps: plan.plannedSteps,
+    executedSteps: [],
+    skippedSteps: [],
+    producedFiles: [],
+    validation: null,
+    appliedOverrides: plan.appliedOverrides,
+  };
+  if (plan.status !== 'planned') return report;
+
+  const pendingReason = approvalMode === 'allow-durable-write'
+    ? 'specialist execution is host-owned; this local command has no specialist execution evidence'
+    : `approval mode '${approvalMode}' permits planning only`;
+  for (const step of plan.plannedSteps) {
+    if (['review', 'rewrite', 'author', 'research'].includes(step.action)) {
+      report.skippedSteps.push({ id: step.id, reason: pendingReason });
+    }
+  }
+  if (approvalMode !== 'allow-durable-write') {
+    for (const step of plan.plannedSteps) {
+      if (!['review', 'rewrite', 'author', 'research'].includes(step.action)) {
+        report.skippedSteps.push({ id: step.id, reason: pendingReason });
+      }
+    }
+    return report;
+  }
+
+  const sourcePath = plan.sourcePath;
+  for (const step of plan.plannedSteps) {
+    if (step.action === 'validate') {
+      if (!sourcePath) {
+        report.skippedSteps.push({ id: step.id, reason: 'validation needs sourcePath or filePath' });
+      } else {
+        const result = validateArtifactRelease({ filePath: sourcePath, type: plan.artifactType, cwd, rootDir });
+        report.validation = result;
+        report.executedSteps.push({ id: step.id, result: result.ok ? 'passed' : 'failed' });
+        if (!result.ok) {
+          report.status = 'validation-failed';
+          return report;
+        }
+      }
+    }
+    if (step.action === 'brand') {
+      // Branding is applied by the export operation. Keeping this pending until
+      // output exists avoids claiming a template was applied when no export ran.
+      report.skippedSteps.push({ id: step.id, reason: 'branding is evidenced by the export result' });
+    }
+    if (step.action === 'export') {
+      if (!sourcePath) {
+        report.skippedSteps.push({ id: step.id, reason: 'export needs sourcePath or filePath' });
+      } else {
+        const result = exportMarkdown({
+          inputPath: sourcePath,
+          outputPath: request.outputPath,
+          format: step.format,
+          artifactType: plan.artifactType,
+          branding: plan.target.branding,
+          cwd,
+          rootDir,
+        });
+        if (!result.ok) {
+          report.status = 'export-failed';
+          report.skippedSteps.push({ id: step.id, reason: result.message });
+          return report;
+        }
+        report.executedSteps.push({ id: step.id, result: 'produced', format: step.format });
+        report.producedFiles.push({ path: result.outputPath, format: step.format, branding: result.branding });
+        const brandStep = report.skippedSteps.findIndex((entry) => entry.id === 'brand');
+        if (brandStep >= 0 && result.branding?.applied === 'construct') {
+          report.skippedSteps.splice(brandStep, 1);
+          report.executedSteps.push({ id: 'brand', result: 'applied', mechanism: result.branding.mechanism });
+        }
+      }
+    }
+  }
+  report.status = report.executedSteps.length ? 'completed-local-steps' : 'planned';
+  return report;
+}

package/lib/audit-skills.mjs

@@ -155,6 +155,10 @@ export function auditSkills({ rootDir, silent = false } = {}) {
 
 export async function runAuditSkillsCli(args = []) {
   const rootDir = args.find((a) => a.startsWith('--root='))?.split('=')[1] ?? undefined;
+  if (args.includes('--inventory')) {
+    const { runSkillInventoryAuditCli } = await import('./certification/skill-inventory.mjs');
+    return runSkillInventoryAuditCli(args.filter((a) => a !== '--inventory'), { rootDir });
+  }
   const result = auditSkills({ rootDir });
   if (!result.pass) process.exit(1);
 }