wpt: multi-spec conformance climb to 15,383 passing tests (97.19% normalized)

.agents/skills/champ/SKILL.md

@@ -16,14 +16,16 @@ The subagent persona is a superstar senior SWE. They love concrete specification
 
 ## Subagent Workflow
 1.  **Pick a Task**: Select an uncompleted task from `PLAN.md`. Mark it as in progress `[/]` using the `plan-manager` skill if available.
-2.  **Red Phase**: Write a failing test in the appropriate test file (or create a new one) that demonstrates the missing feature or bug.
-3.  **Green Phase**: Implement the code in `src/` to make the test pass.
-4.  **Verify**: Run the test to ensure it passes.
-5.  **Preflight**: Run `pnpm run preflight` to ensure all tests pass and types are correct.
-6.  **Commit**: Commit the targeted changes with a human-readable, lowercase message describing the action. Do NOT use `git add .` or `git commit -a`.
+2.  **Diagnostic Cluster Triage (for WPT tasks)**: When tackling WPT conformance tasks, run `node scripts/wpt_cluster_failures.ts --spec=<target>` to inspect top failure clusters and prioritize high-frequency patterns.
+3.  **Red Phase**: Write a failing test in the appropriate test file (or create a new one in `tests/`) that demonstrates the missing feature or bug.
+4.  **Green Phase**: Implement the code in `src/` to make the test pass, adding explicit spec anchor citations in comments.
+5.  **Verify**: Run the targeted test to ensure it passes.
+6.  **Preflight**: Run `pnpm run preflight` to ensure all tests pass and types/linters are 100% clean.
+7.  **Commit**: Commit the targeted changes with a human-readable, lowercase message describing the action. Do NOT use `git add .` or `git commit -a`.
 
-## Constraints
-- Follow the "Executable Specification" pattern with spec citations in comments.
+## Constraints & Mandatory Standards
+- **Mandatory Spec Anchor Citations**: You MUST cite the exact Bikeshed specification section and anchor in code comments for every implemented algorithm, branch, or validation rule (e.g. `// cssom-1 § 6.5.3 #insert-a-css-rule` or `// selectors-4 § 4.1 #forgiving-selector`). This maps our implementation directly to the normative standard and allows reviewers to verify correctness.
+- **Consult Normative Specs First**: Actively inspect the normative `.bs` source files in `submodules/csswg-drafts/` and `submodules/css-houdini-drafts/` to understand spec algorithms and edge cases before implementing.
 - **File Editing**: Do NOT use bash redirection or scratch scripts for editing files. Use the specialized tools: `replace_file_content` for single contiguous edits, `multi_replace_file_content` for multiple non-contiguous edits, or `write_to_file` for new files.
 - **Subagent Reuse**: If a subagent with the appropriate role and context already exists from a previous task, prefer reusing it via `send_message` instead of invoking a new one.
 

.agents/skills/coherence-auditor/SKILL.md

@@ -25,15 +25,17 @@ Use this skill when you need to audit the consistency, link integrity, codebase
        - `README.md`
        - `PLAN.md`
        - `AGENTS.md`
-       - `API_BOUNDARIES.md`
        - `LOOP.md`
        - `MAINTENANCE.md`
-       - `contributing.md`
+       - `CONTRIBUTING.md`
      - Verify taxonomy, workflow, and abbreviation consistency across docs:
        - **Subagent Personas & Quality Loop**: Ensure references to `champ` (Developer), `codex_reviewer_cmd` (Reviewer), `Grizz` (Gatekeeper), and `scrutineer` (Spec Auditor) in `LOOP.md`, `AGENTS.md`, and `PLAN.md` match exact names and roles.
        - **Spec Modules & Submodule References**: Validate spec names (`CSSOM Level 1`, `CSS Syntax Level 3`, `CSS Values Level 4`, `CSS Nesting Level 1`, `CSS Typed OM Level 1 & 2`, `CSS Logical Properties Level 1`, `Houdini`) and their underlying submodule paths (`submodules/csswg-drafts/`, `submodules/css-houdini-drafts/`).
-       - **Architectural Constraints**: Ensure consistent documentation of `ParseHooks` (`src/parse-hooks.ts`) for circular dependency inversion, and `API_BOUNDARIES.md` for documented spec deviations.
-       - **Execution Rules & Scripts**: Enforce that documentation consistently specifies native Node execution (`node script.ts`, NOT `npx tsx` or `ts-node`) and valid npm scripts (`pnpm run preflight`, `pnpm run codegen`, `pnpm run maintain`, `pnpm test`).
+       - **Architecture & Spec Boundaries**:
+         - Audit `README.md § Architecture & Spec Boundaries` against actual codebase exports in `src/index.ts` and `tests/api-surface.test.ts`.
+         - Ensure documented standard CSSOM / Houdini interfaces, Bridge utilities, intentional spec deviations, and non-goals (e.g. no `getComputedStyle()`) are factually accurate, up to date, and omit no methods or deviations.
+         - Ensure consistent documentation of `ParseHooks` (`src/parse-hooks.ts`) for circular dependency inversion.
+       - **Execution Rules & Scripts**: Enforce that documentation consistently specifies native Node execution (`node script.ts`, NOT `npx tsx` or `ts-node`) and valid npm scripts (`pnpm run preflight`, `pnpm run codegen`, `pnpm run maintain`, `pnpm test`, `wpt:node:*`, `wpt:browser:*`).
      - Identify any contradictory claims, outdated API signatures, or conflicting guidelines between files.
 
   2. **Codebase & Script Terminology Consistency Audit**:

.agents/skills/coherence-auditor/scripts/validate_links.ts

@@ -15,10 +15,9 @@ const CANONICAL_DOCS = [
   'README.md',
   'PLAN.md',
   'AGENTS.md',
-  'API_BOUNDARIES.md',
   'LOOP.md',
   'MAINTENANCE.md',
-  'contributing.md',
+  'CONTRIBUTING.md',
 ];
 
 function getLineNumber(content: string, index: number): number {

.npmignore

@@ -24,7 +24,6 @@ MAINTENANCE.md
 AGENTS.md
 CONTRIBUTING.md
 wpt-progress.md
-wpt-typed-om-progress.md
 
 # Logs & temp files
 *.log
@@ -33,4 +32,3 @@ wpt-typed-om-progress.md
 
 !pnpm-lock.yaml
 !pnpm-workspace.yaml
-!API_BOUNDARIES.md

AGENTS.md

@@ -5,7 +5,7 @@ Building a spec-compliant CSSOM (CSS Object Model) parser in pure TypeScript.
 - **Execution**: Run node scripts directly: `node script.ts`. Do NOT use `npx tsx` or `ts-node`.
 
 ## Spec References
-We are building a spec-compliant implementation. Agents MUST adhere to the W3C specifications listed below, except where intentional deviations are documented in `API_BOUNDARIES.md` for pragmatism, performance, or Node.js compatibility. You are expected to actively consult these Bikeshed (`.bs`) source files to understand the normative algorithms and edge cases before implementing or auditing features.
+We are building a spec-compliant implementation. Agents MUST adhere to the W3C specifications listed below, except where intentional deviations are documented in `README.md` for pragmatism, performance, or Node.js compatibility. You are expected to actively consult these Bikeshed (`.bs`) source files to understand the normative algorithms and edge cases before implementing or auditing features.
 
 Relevant Specifications:
 - CSSOM: `submodules/csswg-drafts/cssom-1/Overview.bs`
@@ -39,7 +39,7 @@ To avoid circular dependencies between the core parser and the CSSOM/Typed OM la
 
 ### API Boundaries
 We intentionally deviate from some specifications for pragmatism, performance, or Node.js compatibility (e.g., providing synchronous versions of Houdini APIs).
-- **Rule**: Before proposing refactors to align strictly with IDL, review `API_BOUNDARIES.md` to understand documented intentional deviations.
+- **Rule**: Before proposing refactors to align strictly with IDL, review `README.md` to understand documented intentional deviations.
 
 ## Spec Evolution & Maintainability
 

LOOP.md

@@ -21,19 +21,24 @@ graph TD
 ### The Personas & Segregation of Duties
 
 1.  **The Orchestrator**:
-    *   *Role*: Plans roadmaps (`PLAN.md`), updates progress logs (`wpt-progress.md`, `wpt-typed-om-progress.md`), and delegates tasks.
+    *   *Role*: Plans roadmaps (`PLAN.md`), updates progress logs (`wpt-progress.md`), and delegates tasks.
     *   *Constraint*: The Orchestrator **never writes code or runs manual fixes**. It coordinates subagents and enforces the gate transitions.
 2.  **The Developer (`champ`)**:
-    *   *Role*: Implements features, writes tests, runs `pnpm run preflight`, and commits changes to git.
-    *   *Constraint*: Naturally optimistic. Wants compilation and test runs to pass as quickly as possible.
+    *   *Role*: Implements features, writes tests, runs `pnpm run preflight`, and commits changes to git following the [champ skill](file:///usr/local/google/home/paulirish/code/cssom/.agents/skills/champ/SKILL.md).
+    *   *Standards*:
+        *   **Spec Anchor Citations**: Must cite exact normative specification anchors in code comments (e.g. `// cssom-1 § 6.5.3 #insert-a-css-rule`) mapping implementation to standard algorithms.
+        *   **Mandatory Pre/Post Cluster Triage & Delta Reconciliation**: When working on WPT conformance waves, start with `node scripts/wpt_cluster_failures.ts --spec=<target>` to record the baseline failure cluster. After implementation, run `wpt_cluster_failures` again. If the test increase is noticeably smaller than the targeted cluster, the developer **MUST diagnose the top remaining failure cluster** and fix any near-miss harness/serialization gaps (e.g. computed color formatting) before declaring the phase complete.
+        *   *Constraint*: Naturally optimistic. Wants compilation and test runs to pass as quickly as possible.
 3.  **The Reviewer (`codex_reviewer_cmd`)**:
-    *   *Role*: Senior engineer persona. Has command execution permissions and runs `git show HEAD` to audit styling, typing, and safety.
-    *   *Constraint*: Direct, factual, and zero-fluff. Rejects any lazy casts, hidden linter disables, or untested code paths.
+    *   *Role*: Senior engineer persona. Has command execution permissions and runs `git show HEAD` to audit styling, typing, spec citations, and safety.
+    *   *Standards*:
+        *   **Cluster Delta Audit**: Reviewers must check the test delta and audit the top remaining failure cluster in the target spec to ensure the developer did not leave trivial formatting, oracle, or normalization gaps behind.
+    *   *Constraint*: Direct, factual, and zero-fluff. Rejects any lazy casts, hidden linter disables, missing spec anchors, or untested code paths.
 4.  **The Hostile Auditor (`Grizz`)**:
     *   *Role*: A production-hardened principal engineer who **trusts nothing**.
-    *   *Constraint*: Grizz assumes the developer agent is trying to cheat or "greenwash" tests. He physically inspects the committed tests on disk and checks for linter config overrides, snapshot/regex sanitizers, or bypassed assertions. Grizz holds sole veto power over the final shipping gate.
+    *   *Constraint*: Grizz assumes the developer agent is trying to cheat or "greenwash" tests. He physically inspects the committed tests on disk and checks for linter config overrides, snapshot/regex sanitizers, bypassed assertions, or unaddressed failure clusters. Grizz holds sole veto power over the final shipping gate.
 5.  **The Spec Auditor (`scrutineer`)**:
-    *   *Role*: Validates implementation and test coverage directly against the normative Bikeshed specs (e.g. `submodules/csswg-drafts/**/*.bs`).
+    *   *Role*: Validates implementation and test coverage directly against the normative Bikeshed specs in `submodules/` (e.g. `submodules/csswg-drafts/**/*.bs`).
 
 ---
 
@@ -54,6 +59,7 @@ Since subagent definitions are session-specific and do not persist across conver
     - Reject silenced compiler warnings or linter overrides.
     - Reject snapshot sanitizers or regex output-censoring.
     - Ensure tests are strong and contain valid assertions.
+    - Conformance Delta Audit: Verify that the patch eliminated the target failure cluster without leaving trivial serialization / harness mismatches in the top remaining cluster.
 
     Format your response exactly as:
     # Code Review Report
@@ -76,6 +82,7 @@ Since subagent definitions are session-specific and do not persist across conver
     1. Suppressed eslint rules (e.g. `/* eslint-disable */` or `.oxlintrc.json` overrides).
     2. Test modifications that mute assertions (e.g., empty try-catch blocks, mock bypasses, or adding tests to WPT sandbox excludes/knownFailures).
     3. Output normalizers/regex-scrubbing that hides snapshot layout mismatches.
+    4. Conformance Delta Audit: Verify that the patch actually eliminated the targeted failure cluster, and reject changes that leave obvious harness or serialization mismatches in the top remaining cluster.
 
     Be hostile and thorough. State "No blocking findings discovered" only if the code is 100% clean and correct.
     ```
@@ -94,7 +101,7 @@ Reviewers and Grizz MUST reject any of the following shortcuts:
     *   No file-level `/* eslint-disable */`.
 *   **Assertion & Test Sandbox Integrity**:
     *   No test normalization/regex-scrubbing to hide layout or structural mismatches. Comparisons must be raw (e.g., `expect(actual).toEqual(expected)`).
-    *   No adding of failing WPT sandbox tests to the `exclude` or `knownFailures` lists in `tests/fixtures/baselines/wpt-sandbox-known-failures.json` unless it represents a spec deviation documented in `API_BOUNDARIES.md`.
+    *   No adding of failing WPT sandbox tests to the `exclude` or `knownFailures` lists in `tests/fixtures/baselines/wpt-sandbox-known-failures.json` unless it represents a spec deviation documented in `README.md`.
 *   **Oracle Isolation**:
     *   Do not modify the `submodules/` specs or test suites to make tests pass.