@geraldmaron/construct 1.3.1 → 1.4.0

package/lib/visual-review.mjs

@@ -0,0 +1,70 @@
+/**
+ * lib/visual-review.mjs — Rubric registry and the visually-reviewed evidence contract.
+ *
+ * A visual review is recordable only from a real captured screenshot, a named rubric, and a
+ * reviewer verdict — never inferred from source text. recordVisualReview throws unless it is handed
+ * screenshot-captured evidence with no degradation, so the visually-reviewed rung cannot be forged
+ * without a rendered image. The verdict rides in the proof and gates the later approved rung; the
+ * review itself (model or human judgment) is supplied by the caller, not fabricated here.
+ */
+import { makeEvidence } from './artifact-completion.mjs';
+
+export const VERDICTS = Object.freeze(['pass', 'needs-changes', 'fail']);
+
+export const RUBRICS = Object.freeze({
+  'document-v1': {
+    id: 'document-v1',
+    applies: ['pdf', 'docx', 'html'],
+    criteria: ['spacing and visual rhythm', 'visual hierarchy and scan-ability', 'reading order sanity'],
+  },
+  'deck-v1': {
+    id: 'deck-v1',
+    applies: ['pptx', 'deck'],
+    criteria: ['slide density', 'font legibility at slide distance', 'no clipped or overflowing content'],
+  },
+  'diagram-v1': {
+    id: 'diagram-v1',
+    applies: ['mermaid', 'd2'],
+    criteria: ['purpose is clear', 'labels are readable', 'density is manageable', 'non-happy path shown where relevant'],
+  },
+});
+
+export function makeVisualReview({ rubricId, image, verdict, reviewer, notes = '' } = {}) {
+  if (!RUBRICS[rubricId]) {
+    throw new Error(`unknown rubric: ${rubricId} (expected one of ${Object.keys(RUBRICS).join(', ')})`);
+  }
+  if (typeof image !== 'string' || image.length === 0) {
+    throw new Error('visual review requires a rendered image path');
+  }
+  if (!VERDICTS.includes(verdict)) {
+    throw new Error(`unknown verdict: ${verdict} (expected one of ${VERDICTS.join(', ')})`);
+  }
+  if (typeof reviewer !== 'string' || reviewer.length === 0) {
+    throw new Error('visual review requires a reviewer');
+  }
+  return Object.freeze({ rubricId, image, verdict, reviewer, notes });
+}
+
+// The review must trace to a real captured screenshot; handing in anything else (a degraded
+// render, or no evidence at all) throws, so visually-reviewed is unreachable from source alone.
+
+export function recordVisualReview({ screenshotEvidence, review, actor = 'construct-review' } = {}) {
+  if (!screenshotEvidence
+    || screenshotEvidence.state !== 'screenshot-captured'
+    || screenshotEvidence.degradation) {
+    throw new Error('visual review requires non-degraded screenshot-captured evidence (no source inference)');
+  }
+  if (!review || !RUBRICS[review.rubricId] || !VERDICTS.includes(review.verdict)) {
+    throw new Error('visual review requires a valid review report');
+  }
+  return makeEvidence('visually-reviewed', {
+    actor,
+    artifact: screenshotEvidence.artifact,
+    proof: {
+      rubricId: review.rubricId,
+      image: review.image,
+      verdict: review.verdict,
+      reviewer: review.reviewer,
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",

package/scripts/sync-specialists.mjs

@@ -1481,7 +1481,7 @@ function syncVSCode(targetDir = null, wants = true) {
       const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
       const transportMismatch = registryWantsCommand && existingIsRemote;
       if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
-      config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
+      config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
     }
     if (!DRY_RUN) {
       mkdirp(path.dirname(mcpPath));
@@ -1505,7 +1505,7 @@ function syncVSCode(targetDir = null, wants = true) {
         const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
         const transportMismatch = registryWantsCommand && existingIsRemote;
         if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
-        config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
+        config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
       }
       if (!DRY_RUN) fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
       synced = true;
@@ -1575,7 +1575,7 @@ function syncCursor(targetDir = null, wants = true) {
     const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
     const transportMismatch = registryWantsCommand && existingIsRemote;
     if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
-    config.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
+    config.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
   }
   if (!DRY_RUN) {
     mkdirp(path.dirname(cursorMcpPath));

package/specialists/artifact-manifest.json

@@ -9,6 +9,10 @@
     "outputs": {
       "formats": ["pdf", "docx", "doc", "deck", "pptx", "html", "rtf", "odt", "epub", "tex", "txt", "md", "mdx"],
       "branding": "construct"
+    },
+    "qualityContract": {
+      "gateLevel": "standard",
+      "requiredStates": ["exported"]
     }
   },
   "artifacts": {
@@ -31,6 +35,13 @@
         "proseMinimum": 3,
         "requiredReviewers": ["cx-devil-advocate"],
         "optionalReviewers": ["cx-ux-researcher"]
+      },
+      "qualityContract": {
+        "gateLevel": "render-smoke",
+        "requiredStates": ["exported", "file-valid", "renderable"],
+        "perFormat": {
+          "pdf": { "requiredStates": ["file-valid", "renderable"], "a11y": "wcag-2.1-aa" }
+        }
       }
     },
     "prd-platform": {
@@ -318,6 +329,13 @@
         "proseMinimum": 2,
         "requiredReviewers": ["cx-devil-advocate"],
         "optionalReviewers": []
+      },
+      "qualityContract": {
+        "gateLevel": "render-smoke",
+        "requiredStates": ["exported", "file-valid", "renderable"],
+        "perFormat": {
+          "pdf": { "requiredStates": ["file-valid", "renderable"] }
+        }
       }
     },
     "customer-profile": {

package/specialists/artifact-manifest.schema.json

@@ -41,7 +41,8 @@
         "authorChain": { "type": "array", "items": { "type": "string" } },
         "reviewerChain": { "type": "array", "items": { "type": "string" } },
         "validation": { "$ref": "#/$defs/validation" },
-        "outputs": { "$ref": "#/$defs/outputs" }
+        "outputs": { "$ref": "#/$defs/outputs" },
+        "qualityContract": { "$ref": "#/$defs/qualityContract" }
       }
     },
     "validation": {
@@ -58,6 +59,48 @@
         "branding": { "type": "string", "enum": ["construct", "plain"] }
       }
     },
+    "gateLevel": {
+      "type": "string",
+      "enum": ["fast", "standard", "render-smoke", "full-certification", "human-reviewed"]
+    },
+    "completionState": {
+      "type": "string",
+      "enum": [
+        "planned",
+        "authored",
+        "structurally-valid",
+        "source-linted",
+        "exported",
+        "file-valid",
+        "renderable",
+        "screenshot-captured",
+        "visually-reviewed",
+        "accessibility-reviewed",
+        "approved",
+        "completed"
+      ]
+    },
+    "qualityContract": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gateLevel": { "$ref": "#/$defs/gateLevel" },
+        "requiredStates": { "type": "array", "items": { "$ref": "#/$defs/completionState" } },
+        "perFormat": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "gateLevel": { "$ref": "#/$defs/gateLevel" },
+              "requiredStates": { "type": "array", "items": { "$ref": "#/$defs/completionState" } },
+              "a11y": { "type": "string" },
+              "fontFloorPt": { "type": "number" }
+            }
+          }
+        }
+      }
+    },
     "artifactEntry": {
       "type": "object",
       "required": ["template", "primaryOwners", "toneDefault", "releaseGate"],
@@ -76,7 +119,8 @@
         "authorChain": { "type": "array", "items": { "type": "string" } },
         "reviewerChain": { "type": "array", "items": { "type": "string" } },
         "validation": { "$ref": "#/$defs/validation" },
-        "outputs": { "$ref": "#/$defs/outputs" }
+        "outputs": { "$ref": "#/$defs/outputs" },
+        "qualityContract": { "$ref": "#/$defs/qualityContract" }
       }
     }
   }

package/templates/distribution/construct-brand.typ

@@ -280,8 +280,7 @@
     #v(0.28em)
     #set text(font: construct-font-sans, size: fs-micro, fill: ink-faint)
     #align(center)[
-      #text(weight: wt-bold, fill: ink, tracking: 0.04em)[Construct]
-      #text[ #sym.dot.c #footer-label]
+      #text(weight: wt-bold, fill: ink, tracking: 0.04em)[#footer-label]
       #if classification != "" [ #sym.dot.c #upper(classification)]
     ]
   ]

package/templates/distribution/construct-deck.html

@@ -1,15 +1,14 @@
 <!--
-  templates/distribution/construct-deck.html — Construct branded 16:9 slide deck
-  HTML for `construct export --to=deck`. Pandoc emits section divs (--section-divs)
-  from markdown slides separated by ---; Space Grotesk via Google Fonts; monochrome ink
-  tokens mirror construct-brand.typ. Metadata variables fill the title slide.
+  Standalone 16:9 slide-deck HTML export template. Pandoc emits section divs
+  (--section-divs) from markdown slides separated by ---; Space Grotesk via Google
+  Fonts; monochrome ink tokens. Metadata variables fill the title slide.
 -->
 <!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>$if(title)$$title$$else$Construct deck$endif$</title>
+<title>$if(title)$$title$$else$Slides$endif$</title>
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">
@@ -24,57 +23,58 @@
   }
   * { box-sizing:border-box; }
   html { scroll-behavior:smooth; -webkit-text-size-adjust:100%; }
-  body { margin:0; background:#e8e9ec; color:var(--ink-body); font-family:var(--sans); font-size:22px; line-height:1.45; -webkit-font-smoothing:antialiased; }
+  body { margin:0; background:#e8e9ec; color:var(--ink-body); font-family:var(--sans); font-size:17px; line-height:1.5; -webkit-font-smoothing:antialiased; }
   .deck { display:flex; flex-direction:column; align-items:center; gap:32px; padding:40px 24px 80px; }
-  section.slide {
+  .deck > section {
     width:min(100%, var(--slide-w));
     aspect-ratio:16/9;
     background:var(--paper);
     border:1px solid var(--hairline);
     border-radius:8px;
     box-shadow:0 18px 48px rgba(10,12,16,.08);
-    padding:56px 64px 48px;
+    padding:48px 56px 40px;
     overflow:hidden;
     display:flex;
     flex-direction:column;
     position:relative;
   }
-  section.slide::after {
+  .deck > section::after {
     content:"";
     position:absolute;
     left:0; right:0; bottom:0;
     height:4px;
     background:linear-gradient(90deg, var(--ink) 46px, var(--hairline) 46px);
   }
-  section.slide.title-slide { justify-content:center; }
-  section.slide.title-slide h1 { font-size:52px; line-height:1.06; letter-spacing:-.024em; margin:0 0 16px; color:var(--ink); font-weight:600; }
-  section.slide.title-slide .subtitle { font-size:26px; color:var(--muted); margin:0 0 28px; letter-spacing:-.005em; }
-  section.slide.title-slide .meta { font-size:15px; color:var(--muted); letter-spacing:.04em; text-transform:uppercase; font-weight:600; }
-  section.slide.title-slide .meta .sep { color:var(--faint); font-weight:400; }
-  section.slide h1 { font-size:40px; line-height:1.08; letter-spacing:-.02em; margin:0 0 20px; color:var(--ink); font-weight:600; }
-  section.slide h1::after { content:""; display:block; width:36px; height:3px; background:var(--ink); margin-top:14px; }
-  section.slide h2 { font-size:28px; font-weight:600; color:var(--ink-strong); margin:28px 0 12px; letter-spacing:-.01em; }
-  section.slide h3 { font-size:22px; font-weight:600; color:var(--ink-strong); margin:20px 0 8px; }
-  section.slide p { margin:0 0 14px; max-width:52em; }
-  section.slide ul, section.slide ol { margin:0 0 16px; padding-left:1.2em; }
-  section.slide li { margin:0 0 10px; }
-  section.slide li::marker { color:var(--ink); }
-  section.slide strong { color:var(--ink); font-weight:600; }
-  section.slide code { font-family:var(--mono); font-size:.84em; background:var(--surface-alt); padding:1px 6px; border-radius:4px; }
-  section.slide pre { background:var(--surface); border:1px solid var(--hairline); border-radius:8px; padding:16px 18px; overflow:auto; font-size:17px; }
-  section.slide pre code { background:none; padding:0; }
-  section.slide blockquote { margin:16px 0; padding:14px 18px; background:var(--surface-alt); border-left:3px solid var(--ink); border-radius:0 4px 4px 0; }
-  section.slide table { width:100%; border-collapse:collapse; font-size:18px; margin:12px 0; }
-  section.slide th, section.slide td { text-align:left; padding:8px 12px; border-bottom:1px solid var(--hairline); }
-  section.slide thead th { font-weight:700; color:var(--ink); border-bottom:2px solid var(--ink); }
-  section.slide figure { margin:16px 0; text-align:center; }
-  section.slide figure img { max-width:58%; max-height:42vh; width:auto; height:auto; object-fit:contain; border:1px solid var(--hairline); border-radius:6px; padding:8px; }
+  .deck > section.title-slide { justify-content:center; }
+  .deck > section.title-slide h1 { font-size:38px; line-height:1.1; letter-spacing:-.022em; margin:0 0 14px; color:var(--ink); font-weight:600; }
+  .deck > section.title-slide .subtitle { font-size:19px; color:var(--muted); margin:0 0 24px; letter-spacing:-.005em; }
+  .deck > section.title-slide .meta { font-size:13px; color:var(--muted); letter-spacing:.04em; text-transform:uppercase; font-weight:600; }
+  .deck > section.title-slide .meta .sep { color:var(--faint); font-weight:400; }
+  .deck > section h1 { font-size:28px; line-height:1.12; letter-spacing:-.018em; margin:0 0 16px; color:var(--ink); font-weight:600; }
+  .deck > section h1::after { content:""; display:block; width:30px; height:2px; background:var(--ink); margin-top:12px; }
+  .deck > section h2 { font-size:20px; font-weight:600; color:var(--ink-strong); margin:22px 0 10px; letter-spacing:-.01em; }
+  .deck > section h3 { font-size:16px; font-weight:600; color:var(--ink-strong); margin:16px 0 6px; }
+  .deck > section p { margin:0 0 12px; max-width:54em; }
+  .deck > section ul, .deck > section ol { margin:0 0 12px; padding-left:1.2em; }
+  .deck > section li { margin:0 0 7px; }
+  .deck > section li::marker { color:var(--ink); }
+  .deck > section strong { color:var(--ink); font-weight:600; }
+  .deck > section code { font-family:var(--mono); font-size:.84em; background:var(--surface-alt); padding:1px 6px; border-radius:4px; }
+  .deck > section pre { background:var(--surface); border:1px solid var(--hairline); border-radius:8px; padding:14px 16px; overflow:auto; font-size:13.5px; }
+  .deck > section pre code { background:none; padding:0; }
+  .deck > section blockquote { margin:16px 0; padding:14px 18px; background:var(--surface-alt); border-left:3px solid var(--ink); border-radius:0 4px 4px 0; }
+  .deck > section table { width:100%; border-collapse:collapse; font-size:15px; margin:10px 0; }
+  .deck > section th, .deck > section td { text-align:left; padding:8px 12px; border-bottom:1px solid var(--hairline); }
+  .deck > section thead th { font-weight:700; color:var(--ink); border-bottom:2px solid var(--ink); }
+  .deck > section figure { margin:12px 0; text-align:center; flex:1 1 auto; min-height:0; display:flex; flex-direction:column; align-items:center; justify-content:center; }
+  .deck > section figure img { max-width:80%; max-height:100%; width:auto; height:auto; object-fit:contain; border:1px solid var(--hairline); border-radius:6px; padding:8px; }
+  .deck > section > img { display:block; margin:12px auto; flex:1 1 auto; min-height:0; max-width:84%; max-height:100%; width:auto; height:auto; object-fit:contain; border:1px solid var(--hairline); border-radius:6px; padding:8px; }
   .slide-foot { margin-top:auto; padding-top:16px; font-size:13px; color:var(--faint); display:flex; justify-content:space-between; align-items:center; }
   .slide-foot b { color:var(--ink); font-weight:600; }
   @media print {
     body { background:var(--paper); }
     .deck { gap:0; padding:0; }
-    section.slide { box-shadow:none; border:none; border-radius:0; page-break-after:always; width:100%; height:100vh; }
+    .deck > section { box-shadow:none; border:none; border-radius:0; page-break-after:always; width:100%; height:100vh; }
   }
 </style>
 </head>
@@ -86,7 +86,7 @@ $if(artifactType)$<div class="meta">$artifactType$$if(docId)$ <span class="sep">
 <h1>$title$</h1>
 $if(subtitle)$<p class="subtitle">$subtitle$</p>$endif$
 $if(owner)$<p class="meta">$owner$$if(date)$ <span class="sep">&middot;</span> $date$$endif$$if(status)$ <span class="sep">&middot;</span> $status$$endif$</p>$endif$
-<div class="slide-foot"><span><b>Construct</b>$if(classification)$ &middot; $classification$$endif$</span></div>
+<div class="slide-foot"><span>$if(classification)$<b>$classification$</b>$endif$$if(date)$$if(classification)$ &middot; $endif$$date$$endif$</span></div>
 </section>
 $endif$
 $body$

package/templates/distribution/construct-pdf.typ

@@ -16,7 +16,7 @@
     version: "$if(version)$$version$$endif$",
   ),
   footer: construct-running-footer(
-    "Construct brief",
+    "Brief",
     classification: "$if(classification)$$classification$$endif$",
   ),
 )

package/templates/distribution/construct-web.html

@@ -1,18 +1,16 @@
 <!--
-  templates/distribution/construct-web.html — Construct branded standalone HTML
-  template for `construct export --to=html`. Monochrome design mirroring the PDF
-  brand (construct-brand.typ): Space Grotesk webfont, masthead from frontmatter metadata,
-  bold-header hairline tables, callout blockquotes, framed figures. Pandoc fills
-  $title$/$subtitle$/$status$/$owner$/$date$/$artifactType$/$version$/$docId$/
-  $classification$ and $body$; export runs with --embed-resources so diagrams and
-  fonts inline into a single portable file.
+  Standalone branded HTML export template. Monochrome design: Space Grotesk
+  webfont, masthead from frontmatter metadata, bold-header hairline tables, callout
+  blockquotes, framed figures. Pandoc fills the title, subtitle, status, owner,
+  date, artifactType, version, docId, classification, and document body; export
+  runs with --embed-resources so diagrams and fonts inline into one portable file.
 -->
 <!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>$if(title)$$title$$else$Construct document$endif$</title>
+<title>$if(title)$$title$$else$Document$endif$</title>
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">
@@ -79,14 +77,14 @@
 $if(title)$
 <header class="masthead">
 $if(artifactType)$  <div class="chips">$artifactType$$if(docId)$ <span class="sep">&middot;</span> $docId$$endif$$if(version)$ <span class="sep">&middot;</span> v$version$$endif$$if(classification)$ <span class="sep">&middot;</span> $classification$$endif$</div>
-$endif$  <div class="title">$title$</div>
+$endif$  <h1 class="title">$title$</h1>
 $if(subtitle)$  <p class="subtitle">$subtitle$</p>
 $endif$  <div class="byline">$if(status)$<span class="pill">$status$</span>$endif$$if(owner)$<span>$owner$</span>$endif$$if(date)$<span class="sep">&middot;</span><span>$date$</span>$endif$</div>
 </header>
 <div class="rule"></div>
 $endif$
 $body$
-<div class="doc-foot"><b>Construct</b>$if(classification)$ &middot; $classification$$endif$</div>
+<div class="doc-foot">$if(classification)$<b>$classification$</b>$endif$$if(date)$$if(classification)$ &middot; $endif$$date$$endif$</div>
 </main>
 </body>
 </html>