@geraldmaron/construct 1.1.0 → 1.2.0

package/examples/distribution/sources/runbook.md

@@ -0,0 +1,103 @@
+---
+description: Distribution example — operational runbook with diagnostic flow and severity table.
+artifactType: runbook
+subtitle: Publish pipeline degraded — Pandoc or figure tooling missing
+version: "1.1"
+doc_id: RUNBOOK-PUBLISH-001
+classification: internal
+status: accepted
+owner: cx-sre
+last_verified_at: 2026-06-22
+---
+
+# Runbook: construct publish / export failures
+
+- **Service**: document-export (`construct publish`, `construct export`)
+- **Owner**: platform on-call
+- **Last tested**: 2026-06-22
+- **Severity**: SEV-2 when exports block release; SEV-3 when examples only
+
+## Alert trigger
+
+`construct publish` exits 2 with `missing: pandoc` or `Figure tooling` in `construct tools detect --figures` output. CI job `release:check` fails on export certification scenarios.
+
+## Symptoms
+
+- PDF export fails before Typst invocation
+- `--figures` renders empty diagram placeholders
+- `npm run examples:distribution` reports partial failures in summary
+
+## Impact
+
+| Audience | Impact |
+|---|---|
+| Release managers | Cannot ship branded PRDs/ADRs |
+| Developers | Local previews blocked |
+| Agents | `publish_run` MCP tool returns remediation hints |
+
+## Severity and response
+
+| Severity | Trigger condition | Page within | Comms | Error budget |
+|----------|-------------------|-------------|-------|--------------|
+| SEV-1 | All publish paths down in CI | 5 min | #incident + status | breach → freeze |
+| SEV-2 | PDF down, HTML OK | 15 min | #platform | partial spend |
+| SEV-3 | Examples script only | business hours | team channel | none |
+
+## Diagnostic steps
+
+1. Run `construct tools detect --figures --json` and read `steps.export` + `steps.figures`.
+2. Confirm `pandoc` and `typst` on PATH; confirm `d2` and `mmdc` when `--figures` is set.
+3. Re-run a single fixture: `node bin/construct export examples/distribution/sources/adr.md --to=pdf --figures`.
+
+```mermaid
+flowchart TD
+  A[Alert fires] --> B{export.present?}
+  B -->|No| C[Install pandoc + typst]
+  B -->|Yes| D{figures.present?}
+  D -->|No| E[brew install d2; npm i -g @mermaid-js/mermaid-cli]
+  D -->|Yes| F[Re-run examples:distribution]
+  C --> F
+  E --> F
+```
+
+```d2
+direction: down
+
+detect: tools detect
+pandoc: pandoc + typst
+figures: d2 + mmdc
+ok: Green export
+
+detect -> pandoc: if missing
+detect -> figures: if --figures
+pandoc -> ok
+figures -> ok
+```
+
+## Remediation
+
+```bash
+brew install pandoc typst d2 graphviz
+npm install -g @mermaid-js/mermaid-cli
+npm run examples:distribution
+open .tmp/distribution-examples/index.html
+```
+
+Expected: index lists PDF and HTML links for each artifact type; no `FAILED` lines in script output.
+
+## Rollback
+
+Not applicable — this runbook restores tooling, not application state. If a bad template change caused failures, revert the Typst commit and re-run exports.
+
+## Escalation
+
+After 30 minutes without restore: page cx-platform-engineer. After 60 minutes with release blocked: page cx-release-manager.
+
+## Post-incident
+
+Preserve `construct tools detect --json` output and the failing pandoc/typst stderr in the incident ticket.
+
+## References
+
+- `docs/reference/document-io.md`
+- `docs/cookbook/diagram-and-demo.md`

package/examples/distribution/sources/strategy.md

@@ -0,0 +1,88 @@
+---
+description: Distribution example — strategy memo with goals, metrics, and landscape diagram.
+artifactType: strategy
+subtitle: Make Construct the default governed layer for agentic IDE workflows
+version: "1.0"
+doc_id: STRATEGY-2026-H1
+classification: internal
+status: draft
+owner: cx-product-manager
+last_verified_at: 2026-06-22
+---
+
+# Strategy: Governed agentic workflows for IDE-native teams
+
+- **Date**: 2026-06-22
+- **Owner**: cx-product-manager
+- **Status**: draft
+- **Horizon**: H1 2026 – H1 2027
+
+> Platform and product teams want specialist routing without losing citation discipline, branded exports, or profile-aware terminology. Construct wins when evaluators can open one gallery of PDFs and see the same ink, typography, and diagram styling across document types.
+
+## Problem
+
+Host-native agents optimize for single-session chat. Enterprise platform teams need durable invoke plans, manifest-enforced artifacts, and distribution that looks intentional — not markdown attachments with host fonts.
+
+## Goals
+
+1. **Prove value in five minutes** — `npm run examples:distribution` produces a browsable gallery with figures.
+2. **One brand contract** — `docs/reference/branding.md` + `03d-brand` audit ratchet.
+3. **Profile-aware language** — intake queue labels follow active profile rebrand in CLI, session prelude, and dashboard API.
+
+## Non-goals
+
+Replacing host LLM execution. Mandating cloud render farms. Re-linting every historical doc for marketing voice.
+
+## Landscape
+
+```mermaid
+flowchart TB
+  subgraph hosts [IDE hosts]
+    CC[Claude Code]
+    OC[OpenCode]
+    CX[Cursor]
+  end
+  subgraph construct [Construct]
+    R[Router]
+    V[Validate]
+    P[Publish]
+  end
+  hosts --> R --> V --> P
+  P --> PDF[Branded PDF]
+  P --> HTML[HTML / deck]
+```
+
+```d2
+direction: down
+
+construct: Construct {
+  style.fill: "#f3f4f6"
+}
+
+hosts: IDE hosts
+validate: Release gate
+export: Branded export
+
+hosts -> construct -> validate -> export
+```
+
+## Success metrics
+
+| Metric | Baseline | Target |
+|---|---|---|
+| Brand audit findings | unknown | 0 in `03d-brand` |
+| Example types with figures | 1 (PRD) | ≥6 layouts |
+| Dashboard rebrand coverage | partial | intake API + pages |
+
+## Risks and mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Toolchain missing on contributor laptops | `construct tools detect --figures` in runbook |
+| Template drift | Functional tests on `construct-brand.typ` + HTML decks |
+| Profile label regressions | `intake-rebrand.functional.test.mjs` |
+
+## References
+
+- `examples/distribution/manifest.json`
+- https://langchain-ai.github.io/langgraph/ (accessed 2026-06-22)

package/lib/adapters-sync.mjs

@@ -0,0 +1,67 @@
+/**
+ * lib/adapters-sync.mjs — project adapter sync for the Construct tool repo and
+ * `npm run adapters`. Detects installed hosts, runs sync-specialists --project,
+ * and is invoked from postinstall when developing inside the package itself.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { detectHostCapabilities } from './host-capabilities.mjs';
+import { isConstructPackageRepo } from './host-disposition.mjs';
+import { stageProjectAdapters } from './install/stage-project.mjs';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(MODULE_DIR, '..');
+
+const HOST_ID_MAP = {
+  'Claude Code': 'claude',
+  OpenCode: 'opencode',
+  Codex: 'codex',
+  'VS Code': 'vscode',
+  Cursor: 'cursor',
+  Copilot: 'copilot',
+};
+
+export function resolveAdapterHosts({ forceAll = false, extra = [] } = {}) {
+  if (forceAll) return ['claude', 'opencode', 'codex', 'vscode', 'cursor'];
+  const hosts = new Set(extra);
+  for (const entry of detectHostCapabilities()) {
+    if (entry.availability !== 'installed') continue;
+    const id = HOST_ID_MAP[entry.host];
+    if (id) hosts.add(id);
+  }
+  if (hosts.size === 0) hosts.add('claude');
+  return [...hosts];
+}
+
+export function syncProjectAdapters({
+  projectRoot = process.cwd(),
+  packageRoot = PKG_ROOT,
+  hosts = null,
+  log = () => {},
+} = {}) {
+  const resolvedHosts = hosts ?? resolveAdapterHosts({ forceAll: isConstructPackageRepo(projectRoot) });
+  return stageProjectAdapters({
+    projectRoot,
+    packageRoot,
+    pkgVersion: null,
+    log,
+    hosts: resolvedHosts,
+  });
+}
+
+export function runAdaptersScript({ cwd = process.cwd(), hosts = null } = {}) {
+  const result = syncProjectAdapters({ projectRoot: cwd, hosts, log: (m) => process.stdout.write(`[adapters] ${m}\n`) });
+  return result.synced ? 0 : 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = new Set(process.argv.slice(2));
+  const forceAll = args.has('--all-hosts');
+  const hosts = forceAll ? resolveAdapterHosts({ forceAll: true }) : null;
+  const code = runAdaptersScript({ cwd: process.cwd(), hosts });
+  process.exit(code);
+}

package/lib/artifact-gate-notice.mjs

@@ -0,0 +1,38 @@
+/**
+ * lib/artifact-gate-notice.mjs — Shared PostToolUse artifact structure/visual check.
+ *
+ * Returns violations for typed docs under docs/** and .cx/research/** without
+ * applying TTY/CI suppression (callers decide whether to emit).
+ */
+
+import path from 'node:path';
+import { inferArtifactTypeFromPath, isArtifactGatePath } from './artifact-type-from-path.mjs';
+import { lintDocStructure, lintDocVisuals } from './templates/visual-requirements.mjs';
+
+export function checkArtifactGateNotice(filePath, { cwd = process.cwd() } = {}) {
+  const rel = filePath.startsWith(cwd)
+    ? filePath.slice(cwd.length).replace(/^\/+/, '')
+    : filePath;
+  if (!isArtifactGatePath(rel)) return null;
+
+  const type = inferArtifactTypeFromPath(filePath, { rootDir: cwd });
+  if (!type) return null;
+
+  const errors = [
+    ...lintDocStructure(filePath, type),
+    ...lintDocVisuals(filePath, type),
+  ];
+  if (errors.length === 0) return null;
+
+  return { type, rel, errors };
+}
+
+export function formatArtifactGateNotice({ type, rel, errors }) {
+  const lines = [
+    `\nartifact-release-gate (${type}): ${errors.length} structure/visual issue(s). `
+    + 'Fix before calling the artifact done; full gate: '
+    + `\`construct artifact validate ${rel} --type=${type}\`\n`,
+  ];
+  for (const e of errors) lines.push(`  - ${e}\n`);
+  return lines.join('');
+}

package/lib/artifact-manifest.mjs

@@ -0,0 +1,112 @@
+/**
+ * lib/artifact-manifest.mjs — Load and resolve the artifact capability manifest.
+ *
+ * specialists/artifact-manifest.json is the single source of truth for document
+ * type metadata: templates, tone, structure, visuals, and release gates.
+ * Consumer projects without a local copy resolve the shipped manifest from the
+ * Construct package root.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const EMPTY_MANIFEST = { version: 1, artifacts: {} };
+
+let cached = null;
+let cachedRoot = null;
+
+function manifestPathForRoot(root) {
+  return path.join(root, 'specialists', 'artifact-manifest.json');
+}
+
+export function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    const manifest = manifestPathForRoot(current);
+    if (fs.existsSync(manifest)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  if (fs.existsSync(manifestPathForRoot(PACKAGE_ROOT))) return PACKAGE_ROOT;
+  return null;
+}
+
+export function loadArtifactManifest({ rootDir, force = false, cwd = process.cwd() } = {}) {
+  const resolvedRoot = rootDir ?? findConstructRoot(cwd) ?? PACKAGE_ROOT;
+  if (cached && !force && cachedRoot === resolvedRoot) return cached;
+
+  const p = manifestPathForRoot(resolvedRoot);
+  if (!fs.existsSync(p)) {
+    cached = EMPTY_MANIFEST;
+    cachedRoot = resolvedRoot;
+    return cached;
+  }
+
+  cached = JSON.parse(fs.readFileSync(p, 'utf8'));
+  cachedRoot = resolvedRoot;
+  return cached;
+}
+
+export function getArtifactEntry(type, opts = {}) {
+  const manifest = loadArtifactManifest(opts);
+  return manifest.artifacts?.[type] ?? null;
+}
+
+export function artifactTypes(opts = {}) {
+  const manifest = loadArtifactManifest(opts);
+  return Object.keys(manifest.artifacts ?? {});
+}
+
+export function structureRequirementsFromManifest(opts = {}) {
+  const manifest = loadArtifactManifest(opts);
+  const out = {};
+  for (const [type, entry] of Object.entries(manifest.artifacts ?? {})) {
+    if (entry.structureRequirements?.length) out[type] = entry.structureRequirements;
+  }
+  return out;
+}
+
+export function visualRequirementsFromManifest(opts = {}) {
+  const manifest = loadArtifactManifest(opts);
+  const out = {};
+  for (const [type, entry] of Object.entries(manifest.artifacts ?? {})) {
+    if (entry.visualRequirements?.length) out[type] = entry.visualRequirements;
+  }
+  return out;
+}
+
+export function loadBrandVoice(cwd = process.cwd()) {
+  const p = path.join(cwd, '.cx', 'brand-voice.json');
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function resolveToneForArtifact(type, { cwd = process.cwd(), rootDir } = {}) {
+  const entry = getArtifactEntry(type, { rootDir, cwd });
+  const brand = loadBrandVoice(cwd);
+  const override = brand?.toneOverride?.[type];
+  if (override) return override;
+  return entry?.toneDefault ?? 'direct';
+}
+
+export function templateMetadata(type, { cwd = process.cwd(), rootDir } = {}) {
+  const entry = getArtifactEntry(type, { rootDir, cwd });
+  if (!entry) return null;
+  return {
+    type,
+    tone: resolveToneForArtifact(type, { cwd, rootDir }),
+    toneAllowed: entry.toneAllowed ?? [],
+    structureRequirements: entry.structureRequirements ?? [],
+    visualRequirements: entry.visualRequirements ?? [],
+    primaryOwners: entry.primaryOwners ?? [],
+    workflowSkill: entry.workflowSkill ?? null,
+    releaseGate: entry.releaseGate ?? null,
+  };
+}

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-')));
+}