@tractiontactics/tt-fidelity 0.2.1 → 0.2.2

package/AGENTS.md

@@ -11,6 +11,9 @@ You are measuring a prototype against a TT WP Theme draft. **You are not the gra
 5. **Never apply a rule site-wide** until `instances_per_page` (in clusters / QUEUE) shows it is a real default. Blanket CSS from a rare seam creates hundreds of false findings.
 6. **Cache:** the tool cache-busts by default. If draft and live disagree, purge host/CDN and re-run — do not “fix” ghosts.
 7. **Escalate** tokens → block Style/Advanced → minimal `PUT /custom-css` → theme change → HTML template. Cite `ttRowId` / `ttBlockIds` when present.
+8. **Default `--scope content`** (page body). Use `--scope chrome` for header/footer. Use `--scope full` only when you intentionally want both (TT draft may then count header/footer rows the prototype does not).
+9. **QUEUE lifetime:** `ttRowId` values persist across *renders* of the same layout JSON, but a **republish / rebuild that regenerates row ids** invalidates the QUEUE. Re-measure after any full layout rewrite.
+10. **`--only-failing`:** optional acceleration only. Do **not** grant exit 0 after an only-failing pass — run a full measure (all sections) first.
 
 ## Loop
 
@@ -21,21 +24,26 @@ npx @tractiontactics/tt-fidelity \
   --viewports 1280,768,390 \
   --out ./fidelity \
   --mode full \
+  --scope content \
   --round N \
   --max-rounds 6
 ```
 
 - Exit **0** → page (or chrome scope) done for this URL pair.
-- Exit **1** → do TASK 1 from the plan; re-measure.
+- Exit **1** → do TASK 1 from the plan; re-measure. Section **count** mismatches and **unpaired** sections also keep exit 1.
 - Exit **2** → fix install / auth / `--roles`; do not guess missing sections.
 - Exit **3** → stop; report residuals; consider history restore.
 
+## Structural noise
+
+If a STRUCTURAL task claims the draft has “extra sections” and those are clearly header/footer chrome, re-run with `--scope content` (default since 0.2.2). Do not `PUT /pages/.../layout` to “add” chrome rows.
+
 ## Large sites
 
-Compare one prototype page to its draft at a time, or pass `--pages`. Use `--scope chrome` then `--scope content`. Prefer `--only-failing` after the first full pass.
+Compare one prototype page to its draft at a time, or pass `--pages`. Use `--scope chrome` then `--scope content`. Prefer `--only-failing` only mid-loop; finish with a full pass.
 
 ## Forbidden
 
 - Certifying “100% parity” without exit 0 from the pixel gate.
 - Substituting fetch-only CSS analysis for the main path.
-- Ignoring section count mismatches (structural first).
+- Ignoring unpaired / section count mismatches (structural first — after confirming scope).

package/README.md

@@ -12,9 +12,12 @@ npx @tractiontactics/tt-fidelity \
   --draft "https://site.example.com/?p=12&preview=true" \
   --viewports 1280,768,390 \
   --out ./fidelity \
-  --mode full
+  --mode full \
+  --scope content
 ```
 
+Default `--scope` is **`content`** (page body; excludes TT header/footer rows). Use `--scope chrome` for header/footer, `--scope full` only when you need both.
+
 Monorepo:
 
 ```bash
@@ -97,10 +100,10 @@ Override fail cut with `--threshold` (default `0.10`).
 | `--out <dir>` | `fidelity.json`, `QUEUE.md`, `shots/sections/…` |
 | `--mode full\|pixel\|styles` | See above |
 | `--viewports` | Default `1280,768,390` |
-| `--scope full\|chrome\|content` | Section / landmark scope |
+| `--scope` | Default **`content`**. `chrome` = header/footer. `full` = both (may skew TT section counts). |
 | `--cache-bust` / `--no-cache-bust` | Default **on** (`tt_nocache=`); logs cache headers |
 | `--concurrency <n>` | Parallel pages |
-| `--only-failing` | Skip sections clean in prior `fidelity.json` |
+| `--only-failing` | Skip sections clean in prior `fidelity.json` — finish with a full pass before exit 0 |
 | `--roles` | Landmark map when defaults miss |
 | `--round` / `--max-rounds` | Agent loop |
 | `--json` | Extra copy of the document |

package/fidelity.schema.json

@@ -66,7 +66,14 @@
 									}
 								},
 								"cacheHeaders": { "type": "object" },
-								"coverage": { "type": "object" }
+								"coverage": { "type": "object" },
+								"unpaired": {
+									"type": "object",
+									"properties": {
+										"prototype": { "type": "array" },
+										"draft": { "type": "array" }
+									}
+								}
 							}
 						}
 					}

package/fixtures/self-test.mjs

@@ -8,6 +8,8 @@ import { fileURLToPath } from 'node:url';
 import { writeFileSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { runFidelity } from '../src/index.mjs';
+import { alignSections } from '../src/sections.mjs';
+import { PACKAGE_VERSION } from '../src/constants.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const FIX = __dirname;
@@ -24,6 +26,26 @@ function assert(cond, msg) {
 }
 
 async function main() {
+	assert(PACKAGE_VERSION === '0.2.2', 'package version constant is 0.2.2');
+
+	// Align: unpaired + structural when counts differ
+	{
+		const proto = [
+			{ index: 0, label: 'A', selector: '#a', ttRowId: null },
+			{ index: 1, label: 'B', selector: '#b', ttRowId: null },
+			{ index: 2, label: 'C-unpaired', selector: '#c', ttRowId: null }
+		];
+		const draft = [
+			{ index: 0, label: 'A', selector: '#a', ttRowId: 'row_a' },
+			{ index: 1, label: 'B', selector: '#b', ttRowId: 'row_b' }
+		];
+		const { pairs, structural, unpaired } = alignSections(proto, draft);
+		assert(pairs.length === 2, 'align: pairs = min length');
+		assert(unpaired.prototype.length === 1 && unpaired.prototype[0].label === 'C-unpaired', 'align: unpaired proto listed');
+		assert(unpaired.draft.length === 0, 'align: no unpaired draft');
+		assert(structural.some((s) => s.kind === 'count'), 'align: count structural finding');
+	}
+
 	// 1. Known style drift — exit 1 in styles mode
 	{
 		const r = await runFidelity({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tractiontactics/tt-fidelity",
-	"version": "0.2.1",
+	"version": "0.2.2",
 	"description": "Section-first visual fidelity: hybrid SSIM+pixel gate + computed-style explainer for TT Platform prototype→site builds.",
 	"type": "module",
 	"bin": {
@@ -51,5 +51,8 @@
 	"dependencies": {
 		"pixelmatch": "^7.2.0",
 		"pngjs": "^7.0.0"
+	},
+	"devDependencies": {
+		"playwright": "^1.63.0"
 	}
 }

package/src/cli.mjs

@@ -13,7 +13,7 @@ function parseArgs(argv) {
 		only: null,
 		menus: false,
 		quiet: false,
-		scope: 'full',
+		scope: 'content',
 		round: 1,
 		maxRounds: 6,
 		mode: 'full',
@@ -77,11 +77,12 @@ function usage() {
   --auth u:p / --draft-auth  basic auth
   --cookie "n=v"             draft cookies
   --roles roles.json         project role map
-  --scope full|chrome|content
+  --scope content|chrome|full  default content (page body; excludes TT header/footer rows)
+                               use chrome for header/footer; full only when you need both
   --round / --max-rounds     fidelity loop (exit 3 at max with diffs)
   --cache-bust / --no-cache-bust  default ON (tt_nocache=)
   --concurrency <n>          parallel pages (default 1)
-  --only-failing             skip sections clean in prior fidelity.json
+  --only-failing             skip sections clean in prior fidelity.json (do not use until a final full pass)
   --prior <path>             prior fidelity.json for --only-failing
   --json out.json            also write document
   --plan-only                suppress raw evidence tables

package/src/constants.mjs

@@ -70,4 +70,4 @@ export const BANDS = {
 };
 
 export const SCHEMA_VERSION = 2;
-export const PACKAGE_VERSION = '0.2.1';
+export const PACKAGE_VERSION = '0.2.2';

package/src/plan.mjs

@@ -121,6 +121,7 @@ export function buildPlan(d, { pixelSections = [] } = {}) {
 	}
 	for (const [role, items] of structuralByRole) {
 		const unmatched = items.some((i) => i.kind === 'unmatched' || i.kind === 'extra');
+		const hints = items.map((i) => i.hint).filter(Boolean);
 		tasks.push({
 			kind: 'structural',
 			title: unmatched
@@ -129,13 +130,34 @@ export function buildPlan(d, { pixelSections = [] } = {}) {
 			why: items.map((i) => i.text),
 			fixAt: unmatched
 				? `FIRST verify it is really absent (inspect the page). If it exists under different markup, add its selector via --roles and re-run — do not "fix" it. If genuinely absent: ${fixHintFor(null, role, 'structural')}`
-				: fixHintFor(null, role, 'structural'),
+				: (hints[0] || fixHintFor(null, role, 'structural')),
 			rows: [],
 			affects: items.length,
 			mayResolve: 0
 		});
 	}
 
+	const unpaired = d.unpaired;
+	if (unpaired && ((unpaired.prototype && unpaired.prototype.length) || (unpaired.draft && unpaired.draft.length))) {
+		const why = [];
+		for (const u of unpaired.prototype || []) {
+			why.push(`unpaired prototype [${u.index}]: "${u.label || u.selector}"${u.ttRowId ? ` (${u.ttRowId})` : ''}`);
+		}
+		for (const u of unpaired.draft || []) {
+			why.push(`unpaired draft [${u.index}]: "${u.label || u.selector}"${u.ttRowId ? ` (${u.ttRowId})` : ''}`);
+		}
+		tasks.push({
+			kind: 'structural',
+			title: 'Unpaired sections — not pixel-compared (positional truncate)',
+			why,
+			fixAt:
+				'These sections were dropped from the pixel gate because counts differ. Prefer --scope content for page body (default since 0.2.2). Fix real missing/extra content, then re-measure so every section is paired.',
+			rows: [],
+			affects: why.length,
+			mayResolve: 0
+		});
+	}
+
 	// Pixel sections — severity-ranked, before global style (rebuild first).
 	const failing = (pixelSections || [])
 		.filter((s) => s.band && s.band !== 'clean')
@@ -381,6 +403,10 @@ export function renderQueueMd(clusters, pages) {
 	lines.push('');
 	lines.push('Ranked by leverage. Do one task, re-measure, continue.');
 	lines.push('');
+	lines.push('> Default scope is **content** (page body). Use `--scope chrome` for header/footer.');
+	lines.push('> This QUEUE is valid only until the draft page layout is rewritten (row ids may change).');
+	lines.push('> Do not use `--only-failing` until a final full pass before claiming exit 0.');
+	lines.push('');
 	if (clusters?.length) {
 		lines.push('## Cross-page clusters (fix these first)');
 		lines.push('');
@@ -397,13 +423,23 @@ export function renderQueueMd(clusters, pages) {
 	for (const page of pages) {
 		let fail = 0;
 		let total = 0;
+		const unpairedNotes = [];
 		for (const vp of page.viewports) {
 			for (const s of vp.sections || []) {
 				total += 1;
 				if (s.band !== 'clean') fail += 1;
 			}
+			const u = vp.unpaired || vp.styleDiff?.unpaired;
+			if (u && (u.prototype?.length || u.draft?.length)) {
+				unpairedNotes.push(
+					`${vp.width}px: ${u.prototype?.length || 0} proto / ${u.draft?.length || 0} draft unpaired`
+				);
+			}
+		}
+		lines.push(`- \`${page.id}\`: ${fail}/${total} sections failing (compared)`);
+		for (const note of unpairedNotes) {
+			lines.push(`  - unpaired (not pixel-compared): ${note}`);
 		}
-		lines.push(`- \`${page.id}\`: ${fail}/${total} sections failing`);
 	}
 	lines.push('');
 	return lines.join('\n');

package/src/run.mjs

@@ -150,9 +150,11 @@ async function measurePagePair(browser, pageSpec, opts, roles) {
 		if (doPixel) {
 			const protoSecs = await protoOpen.page.evaluate(inPageSections, { scope: opts.scope });
 			const draftSecs = await draftOpen.page.evaluate(inPageSections, { scope: opts.scope });
-			const { pairs, structural } = alignSections(protoSecs, draftSecs);
+			const { pairs, structural, unpaired } = alignSections(protoSecs, draftSecs);
 			styleDiff.structural = [...(styleDiff.structural || []), ...structural];
-
+			if (unpaired?.prototype?.length || unpaired?.draft?.length) {
+				styleDiff.unpaired = unpaired;
+			}
 			const shotsDir = opts.outDir
 				? join(opts.outDir, 'shots', 'sections', pageSpec.id, String(width))
 				: null;
@@ -225,6 +227,7 @@ async function measurePagePair(browser, pageSpec, opts, roles) {
 			coverage,
 			styleDiff,
 			sections,
+			unpaired: styleDiff.unpaired || { prototype: [], draft: [] },
 			cacheHeaders: draftOpen.cacheHeaders,
 			plan
 		});
@@ -264,7 +267,7 @@ export async function runFidelity(opts = {}) {
 		viewports: [1280, 768, 390],
 		tolerance: 1,
 		mode: 'full',
-		scope: 'full',
+		scope: 'content',
 		round: 1,
 		maxRounds: 6,
 		cacheBust: true,

package/src/sections.mjs

@@ -95,7 +95,7 @@ export function inPageSections({ scope }) {
 /* eslint-enable no-undef */
 
 /**
- * Align sections by document order. Length mismatch → structural findings.
+ * Align sections by document order. Length mismatch → structural findings + unpaired lists.
  */
 export function alignSections(protoSections, draftSections) {
 	const n = Math.min(protoSections.length, draftSections.length);
@@ -103,17 +103,33 @@ export function alignSections(protoSections, draftSections) {
 	for (let i = 0; i < n; i += 1) {
 		pairs.push({ index: i, proto: protoSections[i], draft: draftSections[i] });
 	}
+	const unpaired = {
+		prototype: protoSections.slice(n).map(summarizeUnpaired),
+		draft: draftSections.slice(n).map(summarizeUnpaired)
+	};
 	const structural = [];
 	if (protoSections.length !== draftSections.length) {
+		const missing = protoSections.length - draftSections.length;
 		structural.push({
 			kind: 'count',
 			role: 'section',
 			text: `section: prototype has ${protoSections.length}, draft has ${draftSections.length}${
-				draftSections.length < protoSections.length
-					? ` (draft is missing ${protoSections.length - draftSections.length})`
-					: ` (draft has ${draftSections.length - protoSections.length} extra)`
-			}`
+				missing > 0
+					? ` (draft is missing ${missing})`
+					: ` (draft has ${-missing} extra)`
+			}`,
+			hint:
+				'If comparing page body only, re-run with --scope content (default since 0.2.2) so TT header/footer rows are not counted as extra sections. Chromeless count gaps may still be real layout issues.'
 		});
 	}
-	return { pairs, structural };
+	return { pairs, structural, unpaired };
+}
+
+function summarizeUnpaired(sec) {
+	return {
+		index: sec.index,
+		label: sec.label || '',
+		selector: sec.selector || '',
+		ttRowId: sec.ttRowId || null
+	};
 }