qfai 1.7.13 → 1.7.15

package/assets/scripts/capture-screenshots.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * capture-screenshots.js — Headless screenshot capture utility for qfai-prototyping.
+ *
+ * Usage:
+ *   node capture-screenshots.js --url <url> --out <dir> [--width <px>] [--height <px>]
+ *
+ * Outputs:
+ *   <dir>/screenshot-<ISOtimestamp>.png  — full-page screenshot
+ *   <dir>/manifest.json                  — { url, capturedAt, files: [{path, timestamp}] }
+ *
+ * Exit codes:
+ *   0 — success (at least one screenshot captured)
+ *   1 — argument error (missing --url or --out)
+ *   2 — capture error (unreachable URL or write failure)
+ *
+ * Input/output contract:
+ *   Input : --url  (string, required) — the page URL to capture
+ *           --out  (string, required) — directory to write screenshots; created if absent
+ *           --width  (number, default 1280) — viewport width in px
+ *           --height (number, default 800)  — viewport height in px
+ *
+ *   Output: each screenshot filename includes an ISO-8601-like timestamp suffix
+ *           (e.g. screenshot-2026-04-18T130000123Z.png) so filenames are
+ *           sortable and unique per run.
+ *
+ * spec-0012 TC-0012-0291 / AC-0012-0176
+ */
+
+"use strict";
+
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--url" && argv[i + 1]) {
+      args.url = argv[++i];
+    } else if (argv[i] === "--out" && argv[i + 1]) {
+      args.out = argv[++i];
+    } else if (argv[i] === "--width" && argv[i + 1]) {
+      args.width = parseInt(argv[++i], 10);
+    } else if (argv[i] === "--height" && argv[i + 1]) {
+      args.height = parseInt(argv[++i], 10);
+    }
+  }
+  return args;
+}
+
+function isoTimestamp() {
+  return new Date().toISOString().replace(/[:.]/g, "").replace("T", "T").slice(0, -1) + "Z";
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.url) {
+    console.error("Error: --url is required");
+    process.exit(1);
+  }
+  if (!args.out) {
+    console.error("Error: --out is required");
+    process.exit(1);
+  }
+
+  const outDir = path.resolve(args.out);
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const timestamp = isoTimestamp();
+  const filename = `screenshot-${timestamp}.png`;
+  const screenshotPath = path.join(outDir, filename);
+
+  let captured = false;
+  let captureError = null;
+  try {
+    // Try puppeteer-based capture (available when installed). Any failure
+    // must surface as a capture error; writing fake PNG bytes would corrupt
+    // the evidence chain by making downstream steps think capture succeeded.
+    const puppeteerScript = `
+const puppeteer = require('puppeteer');
+(async () => {
+  const browser = await puppeteer.launch({ args: ['--no-sandbox'] });
+  const page = await browser.newPage();
+  await page.setViewport({ width: ${args.width || 1280}, height: ${args.height || 800} });
+  await page.goto(${JSON.stringify(args.url)}, { waitUntil: 'networkidle0', timeout: 30000 });
+  await page.screenshot({ path: ${JSON.stringify(screenshotPath)}, fullPage: true });
+  await browser.close();
+})();
+`;
+    const tmpScript = path.join(outDir, `_tmp_capture_${timestamp}.js`);
+    fs.writeFileSync(tmpScript, puppeteerScript, "utf-8");
+    try {
+      execSync(`node "${tmpScript}"`, { timeout: 60000, stdio: "pipe" });
+      captured = true;
+    } finally {
+      try {
+        fs.unlinkSync(tmpScript);
+      } catch {
+        /* ignore */
+      }
+    }
+  } catch (error) {
+    captureError = error;
+  }
+
+  if (!captured) {
+    const detail =
+      captureError && typeof captureError.message === "string"
+        ? captureError.message
+        : String(captureError || "unknown error");
+    console.error(`Error: capture failed (${detail})`);
+    process.exit(2);
+  }
+
+  const manifest = {
+    url: args.url,
+    capturedAt: new Date().toISOString(),
+    files: [{ path: screenshotPath, timestamp }],
+  };
+  fs.writeFileSync(path.join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf-8");
+
+  console.log(screenshotPath);
+  process.exit(0);
+}
+
+main();

package/assets/uix-rev/comparison-review.md

@@ -1,6 +1,6 @@
 # UIX-REV: Comparison Review
 
-Review option comparison and selected anchor screen as independent artifacts.
+Review only `30_option_comparison.md` as the option comparison artifact.
 
 ## Comparison Quality (30_option_comparison.md)
 
@@ -9,22 +9,10 @@ Review option comparison and selected anchor screen as independent artifacts.
 - Evaluation criteria must reference the 3-layer evaluation family
 - Rejected/deferred options must have explicit rationale
 - Reconsideration conditions must be documented for deferred options
+- Do not move selected anchor ownership back into `30_option_comparison.md`
 
 ### Trend-derived conversion check
 
 - Trend scan results are converted to comparison axes
 - Stale / overused AI slop avoidance is reflected in comparison criteria
-
-## Selected Direction Quality (31_selected_anchor_screen.md)
-
-- `selected_option` must reference one of the compared options in `30_option_comparison.md`
-- `why_selected` must provide rationale aligned with 3-layer evaluation family
-- Anchor screen must represent the canonical visual direction
-- Downstream strategy (`10_implementation_strategy.md`) must align with selected direction
-- Downstream contracts (`40_screen_contracts.md`) must be consistent with selected direction
-- Deferred options must document reconsideration conditions
-
-### Trend-derived conversion check
-
-- Trend scan results are reflected in selected direction rationale
-- Stale / overused AI slop avoidance is reflected in selection
+- Keep selected-anchor ownership in `31_selected_anchor_screen.md` and scoring-ready field ownership in `50_review_input_bundle.md`

package/assets/uix-rev/contracts-review.md

@@ -1,4 +1,4 @@
-# UIX-REV: Screen Contracts Review (40_screen_contracts.md)
+# UIX-REV: Screen Contracts Review (`40_screen_contracts.md`)
 
 Review screen contracts for canonical 11-field schema completeness.
 
@@ -22,4 +22,7 @@ Review screen contracts for canonical 11-field schema completeness.
 - Routes must be unique across all contracts
 - Required states must include `default`, `loading`, `empty`, and `error`
 - All 11 fields must be present and non-empty for each screen
-- Screen contracts must be consistent with 50_review_input_bundle.md
+- Screen contracts must stay consistent with `31_selected_anchor_screen.md`
+- Screen contracts must stay consistent with Browser QA findings and screen-linked evidence
+- Do not reference legacy filenames such as `40_contracts.md`
+- Keep wording aligned with scoring-ready canonical fields and avoid stale migration vocabulary

package/assets/uix-rev/scoring-review.md

@@ -25,9 +25,11 @@ Each evaluation axis must include:
 
 ## Evaluation Axes Quality
 
-- Each trend-derived row must include source_translation
 - Axes must be measurable and verifiable
 - No generic/boilerplate axes without taste/trend derivation
+- Each axis must define `origin`, `intent`, `why_it_matters`, `score_scale`, `score_anchors.low/mid/high`
+- Each axis must define `positive_signals`, `negative_signals`, `anti_patterns`, `evidence_required`, `minimum_floor`
+- Each axis must define `source_refs`, `goal_refs`, and `review_questions`
 
 ## Aggregate Scoring Rules
 
@@ -46,5 +48,11 @@ Canonical field names (must match `23_design_eval_aggregate.md`):
 ### Trend-derived conversion check
 
 - Trend scan results are converted to scoring axes
-- Trend scan results are reflected in selected direction
+- Trend scan results are reflected in selected anchor
 - Stale / overused AI slop avoidance is reflected in comparison and selection
+
+## Aggregate Review Focus
+
+- Review axis quality, overlap, and minimum floors as a single aggregate system
+- Review `source_refs` and `goal_refs` linkage for every scored axis
+- Remove old aggregate vocabulary and keep wording aligned with `23_design_eval_aggregate.md`

package/assets/uix-rev/strategy-review.md

@@ -2,22 +2,26 @@
 
 Review the UI/UX strategy document (`10_implementation_strategy.md`) for completeness and quality.
 
-This review is scoped to strategy completeness only. Selected direction evaluation belongs to `comparison-review.md`.
+This review is scoped to strategy completeness only. Selected anchor evaluation belongs to `comparison-review.md`.
 
 ## Required Fields
 
 - `surface`
+- `selection_required`
 - `decision`
-- `why_this_strategy`
-- `expected_strengths`
-- `known_risks`
-- `fit_for_this_product`
-- enum validity for `surface` and `decision`
+- `candidate_options`
+- `chosen_option`
+- `rationale`
+- `verification_expectations`
+- `notes_for_reviewer`
 
 ## Alignment Check
 
-- Strategy `decision` must be consistent with the selected direction in `31_selected_anchor_screen.md` (cross-reference only; SSOT judgment is in comparison-review)
+- `chosen_option` must exist in `candidate_options`
+- `decision` and `chosen_option` should use coherent vocabulary
+- Strategy `decision` must be consistent with the selected anchor in `31_selected_anchor_screen.md` (cross-reference only; SSOT judgment is in comparison-review)
 - Strategy must not contradict screen contracts in `40_screen_contracts.md`
+- `selection_required=false` with multiple `candidate_options` should be treated as a warning
 
 ## Verdict