wip v20

Author: geraldarthurdavis

ENGI_SPEC_V20.md

@@ -9,7 +9,7 @@
 - Prior generated proof appendix: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V19_PROVEN.md`
 - Current canonical/latest target: `V19`
 - Last fully realized canonical target preserved in source: `V19`
-- V20 state: draft specification in progress; source implementation, generated V20 quality reports, generated V20 appendix, and pointer advancement are pending
+- V20 state: draft implementation pass in progress; source implementation and generator support are implemented, generated V20 quality artifacts plus `ENGI_SPEC_V20_PROVEN.md` are pending canonical promotion output, and pointer advancement remains pending
 - Current realization basis for this pass: `engi-demo`
 
 ## Drafting and acceptance state
@@ -23,6 +23,14 @@ Those discoveries must update this spec, notes, and parity matrix before source
 Draft status does not weaken the accepted V20 direction.
 It means implementation-revealed changes must be explicit parity movement, not silent source/spec drift.
 
+Current implementation-revealed precision:
+- V20 quality reports are generated by deterministic report builders in `engi-demo/src/canonical/v20-quality.js`.
+- V20 `_PROVEN_` rendering is generated by `scripts/generate-engi-proven.mjs` through the canonical generator.
+- V20 canonical promotion is exposed by `npm run promote:canon -- --version V20 --commit <proof-source-commit>`.
+- V20 performance artifacts record budgets and normalized elapsed classes only; raw wall-clock timings remain test-runner telemetry and do not enter canonical artifact bytes.
+- V20 visual regression uses deterministic DOM/geometry signatures in the first gate; screenshot comparison remains an accepted deferral until local CI screenshot stability is pinned.
+- Browser E2E remains a standalone promotion gate; the default full test script runs the serial non-E2E suite so local browser listener setup is not duplicated by test discovery.
+
 ## Version executive summary
 
 V20 begins after three proof closures:

ENGI_SPEC_V20_NOTES.md

@@ -6,7 +6,7 @@
 - Prior canonical target: `V19`
 - Current canonical/latest target: `V19`
 - Prior generated proof appendix: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V19_PROVEN.md`
-- Current V20 state: draft specification in progress; source implementation, generated quality artifacts, generated appendix, and pointer advancement are pending
+- Current V20 state: draft implementation pass in progress; source implementation and generator support are implemented, generated quality artifacts plus generated appendix are pending canonical promotion output, and pointer advancement remains pending
 - Draft spec companion: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V20.md`
 - Draft parity companion: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_V20_SYSTEM_PARITY_MATRIX.md`
 
@@ -126,6 +126,17 @@ Excluded from the first gate:
 11. Generalize `promote:canon` to V20.
 12. Regenerate V20 docs/parity if implementation reveals budget or report-shape adjustments.
 
+## Implementation pass results
+
+- V20 report builders are implemented in `engi-demo/src/canonical/v20-quality.js`.
+- V20 generated artifacts are `.engi/v20-operator-acceptance-transcript.json`, `.engi/v20-visual-regression-report.json`, `.engi/v20-accessibility-report.json`, `.engi/v20-performance-budget-report.json`, `.engi/v20-projection-quality-smoke-matrix.json`, and `.engi/v20-quality-summary.json`.
+- V20 quality reports use fixed replay context fields and deterministic normalized timing classes; they do not store raw elapsed milliseconds.
+- V20 visual regression currently uses deterministic DOM/geometry signatures, with screenshot comparison explicitly deferred until local CI screenshot stability is pinned.
+- Browser posture is corrected to `V19 active canon / V20 operator-quality draft` and exposes generated appendix/report references.
+- V20 `_PROVEN_` generation renders inherited V19 proof closure plus V20 quality report sections and emits only `.engi/v20-*` artifacts for V20.
+- `promote:canon` accepts `--version V20` and exposes the inherited V19 gates, six V20 quality gates, full test suite, generated write/check, and diff check.
+- The `npm --prefix engi-demo run test:e2e` gate owns browser listener coverage; `npm --prefix engi-demo test` runs the serial non-E2E suite so canonical promotion does not duplicate localhost listener setup through test discovery.
+
 ## V20 success condition
 
 V20 is complete when the operator-facing ENGI shell is not only behaviorally demonstrable, but generated-report provable as legible, accessible, visually stable, performant within local budgets, projection-safe under quality review, and canonically promotable through generated `_PROVEN_`.

ENGI_SPEC_V20_SYSTEM_PARITY_MATRIX.md

@@ -65,19 +65,19 @@ This matrix is grounded in:
 | Area | Current source truth | V20 implementation expectation | Closure signal | Judgment |
 |---|---|---|---|---|
 | Root canon posture | `ENGI_SPEC.txt` points to `V19`; V19 generated appendix and `.engi/v19-*` artifacts are present | V20 must remain draft until quality reports, V20 appendix, promotion, and pointer advancement are complete | V20 docs state V19 remains current canon and no V20 pointer advancement has occurred | closed for draft posture |
-| Browser version posture | Browser title and copy still say `Canonical V16`; JS constants still expose `CANON_VERSION_LABEL = 'V16'` and `CANON_OPERATOR_LABEL = 'canonical V16'` | V20 must distinguish active canon `V19`, draft target `V20`, and inherited historical surfaces without misleading operators | Browser tests assert visible active canon, draft target, and inherited surface labels | open |
+| Browser version posture | Browser title, hero copy, status language, API `specVersion`, and report context distinguish `V19` active canon from `V20` operator-quality draft while naming inherited `V16/V17/V18/V19` surfaces | V20 must distinguish active canon `V19`, draft target `V20`, and inherited historical surfaces without misleading operators | Browser/API assertions plus V20 quality summary assert visible active canon, draft target, inherited surface labels, and generated appendix/report references | implemented; canonical promotion pending |
 | Inherited workflow/projection canon | V17 E2E covers `8 x 2 x 4 = 64` browser scenario/branch/principal cells with exact projection inventories | V20 should inherit this as workflow/projection behavior and add quality gates over representative/high-risk states | V20 reports reference inherited V17 matrix and do not duplicate all quality checks across every cell unless reopened | accepted baseline |
 | Inherited positive proof canon | V18/V19 generated artifacts record `1832` inherited positive proof cells | V20 must preserve this proof baseline and avoid proof-family churn unless quality implementation reveals a proof gap | V20 `_PROVEN_` summarizes inherited proof closure | accepted baseline |
-| Inherited reproducible-canon promotion | V19 promotion command and generator produce clean replay-context generated output | V20 must preserve deterministic generation and generated-only appendix discipline | V20 generated reports and appendix pass check mode | open |
-| Operator acceptance transcript | Browser tests assert many workflow facts but do not emit a structured operator-readable transcript artifact | V20 must generate `.engi/v20-operator-acceptance-transcript.json` from executable browser flows | Transcript records required steps, extracted values, pass/fail, elapsed times, and inherited-canon dependencies | open |
-| Visual regression budget | No screenshot or deterministic visual signature budget exists; E2E asserts text/order but not rendered layout stability | V20 must generate `.engi/v20-visual-regression-report.json` for required operator states | Report passes with zero blocking visual drift or records accepted screenshot deferral with DOM/geometry signatures | open |
-| Accessibility budget | HTML has labels and focusable controls, but no automated accessibility budget checks exist | V20 must generate `.engi/v20-accessibility-report.json` covering labels, focus, keyboard flow, live status, landmarks, contrast, reduced motion, and selected-state semantics | Accessibility report passes with zero blocking failures | open |
-| Performance budget | E2E records elapsed test durations only as test runner output; no operator operation budget report exists | V20 must generate `.engi/v20-performance-budget-report.json` for initial load, scenario/projection switch, branch creation, proof rendering, surface toggles, and reset | Performance report passes hard budgets or updates spec/parity before closure | open |
-| Quality report determinism | V19 generator check mode proves canonical bytes must be stable; V20 quality reports would become stale if raw wall-clock samples enter committed artifacts | V20 must record normalized timing classes, pass/fail, budgets, and fixed replay context instead of raw volatile timing samples in canonical artifacts | Generated quality reports pass check mode from clean replay context | open |
-| Projection-quality smoke matrix | Existing browser matrix proves projection behavior; no quality-specific report proves quality checks avoid forbidden private artifacts | V20 must generate `.engi/v20-projection-quality-smoke-matrix.json` for public, reviewer, buyer, and internal representative states | Matrix proves quality checks pass without private leakage or forbidden artifact dependence | open |
-| Quality summary | No V20 quality aggregate exists | V20 must generate `.engi/v20-quality-summary.json` aggregating operator, visual, accessibility, performance, and projection-quality reports | Summary passes only when every blocking quality gate passes | open |
-| V20 `_PROVEN_` rendering | Generator supports V19 reproducible-canon sections but no V20 quality sections | V20 must render inherited proof closure plus V20 quality report summaries | `ENGI_SPEC_V20_PROVEN.md` generated and check mode passes | open |
-| Promotion command | `promote:canon` is V19-specific and rejects other versions | V20 must support `--version V20` or provide an accepted equivalent command with visible gates | Dry-run and full promotion run show V20 quality gates and generated report checks | open |
+| Inherited reproducible-canon promotion | V20 generator preserves inherited V19 deterministic replay, volatility, negative mutation, contract ledger, and generated-only appendix discipline while emitting only `.engi/v20-*` new artifacts | V20 must preserve deterministic generation and generated-only appendix discipline | V20 generated reports render from clean replay context and V20 promotion dry-run exposes inherited V19 gates before pointer advancement | implemented; full promotion run pending |
+| Operator acceptance transcript | `buildV20OperatorAcceptanceTranscript` emits `.engi/v20-operator-acceptance-transcript.json` from required workflow summaries and generated evidence refs | V20 must generate `.engi/v20-operator-acceptance-transcript.json` from executable browser flows | `test:v20-operator-transcript` verifies required flow ids, step ids, appendix/report reference discovery, pass/fail, and inherited-canon dependencies without raw elapsed samples | implemented |
+| Visual regression budget | `buildV20VisualRegressionReport` emits deterministic DOM/geometry signatures for required states and records screenshot stability as an accepted first-gate deferral | V20 must generate `.engi/v20-visual-regression-report.json` for required operator states | `test:v20-visual` verifies all required visual states, signature digests, zero blocking drift, and accepted screenshot deferral | implemented |
+| Accessibility budget | Browser shell exposes status live-region, focus-visible styling, reduced-motion bounds, and surface-mode tab selected state; report builder records deterministic accessibility checks | V20 must generate `.engi/v20-accessibility-report.json` covering labels, focus, keyboard flow, live status, landmarks, contrast, reduced motion, and selected-state semantics | `test:v20-accessibility` verifies labels/names/focus/live status/landmarks/toggles/contrast/reduced-motion/projection-safety checks with zero blocking failures | implemented |
+| Performance budget | `buildV20PerformanceBudgetReport` records deterministic budgets and normalized timing classes only; raw test runner durations remain noncanonical telemetry | V20 must generate `.engi/v20-performance-budget-report.json` for initial load, scenario/projection switch, branch creation, proof rendering, surface toggles, and reset | `test:v20-performance` verifies operation budgets, normalized classes, report-only suite duration, and absence of raw timing fields | implemented |
+| Quality report determinism | V20 quality report builders use fixed replay context fields and normalized classes; generated artifact tests reject dirty-preview state, local paths, and raw timing fields | V20 must record normalized timing classes, pass/fail, budgets, and fixed replay context instead of raw volatile timing samples in canonical artifacts | V20 generator stdout renders deterministic V20 sections; generated check mode remains a canonical-promotion step | implemented; generated file check pending promotion |
+| Projection-quality smoke matrix | `buildV20ProjectionQualitySmokeMatrix` emits public/reviewer/buyer/internal smoke cells and records inherited V17 `64`-cell browser matrix | V20 must generate `.engi/v20-projection-quality-smoke-matrix.json` for public, reviewer, buyer, and internal representative states | `test:v20-projection-quality` verifies every principal and rejects forbidden artifact dependence | implemented |
+| Quality summary | `buildV20QualitySummary` aggregates operator, visual, accessibility, performance, and projection-quality reports plus inherited V19 proof closure | V20 must generate `.engi/v20-quality-summary.json` aggregating operator, visual, accessibility, performance, and projection-quality reports | `test:v20-quality-summary` passes only when every blocking quality gate passes and inherited V19 proof counts remain `1832`/`10` | implemented |
+| V20 `_PROVEN_` rendering | Generator renders `## V20 Operator Quality Reports`, inherited V19 closure, quality report summaries, visual/accessibility/performance/projection sections, and emits only `.engi/v20-*` artifacts for V20 | V20 must render inherited proof closure plus V20 quality report summaries | V20 stdout generation renders `2583` lines with V20 quality sections; `ENGI_SPEC_V20_PROVEN.md` write/check remains canonical-promotion output | implemented; generated file pending promotion |
+| Promotion command | `promote:canon` accepts `--version V20`, runs inherited V19 gates, six V20 quality gates, serial non-E2E full suite after the standalone E2E gate, generated write/check, and diff check | V20 must support `--version V20` or provide an accepted equivalent command with visible gates | `npm run promote:canon -- --version V20 --commit HEAD --dry-run` shows full V20 gate plan | implemented; full promotion pending |
 | Full source projection-security matrix | V17 browser matrix and V19 changed-policy mutation remain accepted; no V20 policy change exists yet | V20 excludes full source projection-security matrix unless implementation changes projection policy | Boundary remains accepted or reopens if projection source changes | accepted boundary |
 | Full mutation cross-products | V19 representative mutation matrix remains accepted | V20 excludes full mutation cross-products unless quality implementation reveals mutation-class variance | Boundary remains accepted or reopens on unexpected mutation behavior | accepted boundary |
 
@@ -105,15 +105,15 @@ The first gate excludes full mutation cross-products, full source-level projecti
 
 | Workstream | Required artifact or command | Current status | Required V20 judgment |
 |---|---|---|---|
-| Version posture | browser copy plus assertion coverage | current browser still labels shell as `Canonical V16` | required |
-| Operator transcript | `v20-operator-acceptance-transcript` | absent | required |
-| Visual regression | `v20-visual-regression-report` | absent | required |
-| Accessibility | `v20-accessibility-report` | absent | required |
-| Performance | `v20-performance-budget-report` | absent | required |
-| Projection-quality smoke | `v20-projection-quality-smoke-matrix` | absent | required |
-| Quality summary | `v20-quality-summary` | absent | required |
-| V20 `_PROVEN_` rendering | generated V20 appendix with quality report summaries | absent | required |
-| Promotion command | V20 promotion support | V19-only command exists | required |
+| Version posture | browser copy plus assertion coverage | implemented as `V19 active canon / V20 operator-quality draft` with inherited `V16/V17/V18/V19` posture | required; canonical pointer pending |
+| Operator transcript | `v20-operator-acceptance-transcript` | implemented in `buildV20OperatorAcceptanceTranscript`; tested by `test:v20-operator-transcript` | required |
+| Visual regression | `v20-visual-regression-report` | implemented as deterministic DOM/geometry signatures with screenshot deferral recorded | required |
+| Accessibility | `v20-accessibility-report` | implemented with deterministic checks and source-side live-region/focus/tab semantics | required |
+| Performance | `v20-performance-budget-report` | implemented with budgets and normalized timing classes only | required |
+| Projection-quality smoke | `v20-projection-quality-smoke-matrix` | implemented for public/reviewer/buyer/internal representative cells | required |
+| Quality summary | `v20-quality-summary` | implemented with inherited V19 proof closure and all V20 quality reports | required |
+| V20 `_PROVEN_` rendering | generated V20 appendix with quality report summaries | implemented in generator; canonical file generation pending promotion | required |
+| Promotion command | V20 promotion support | implemented; dry-run exposes full V20 gate sequence, `test:e2e` owns browser listener coverage, and `test` runs the serial non-E2E suite to avoid duplicate localhost listener variance | required |
 | Source projection security | inherited V17 browser proof plus no V20 projection-policy source change, or promoted source matrix if policy changes | inherited browser proof present | accepted boundary |
 | Mutation expansion | V19 representative mutation matrix | inherited mutation proof present | accepted boundary |
 

engi-demo/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "start": "node server.js",
-    "test": "node --test",
+    "test": "node --test --test-concurrency=1 test/api.test.js test/contract-change-ledger.test.js test/core.test.js test/deterministic-replay.test.js test/negative-proof-mutation-matrix.test.js test/proof-member-matrix.test.js test/proven-generator.test.js test/state-machine.integration.test.js test/theorem-evidence-matrix.test.js test/volatility-inventory.test.js test/workflow.integration.test.js test/v20-accessibility.test.js test/v20-operator-transcript.test.js test/v20-performance-budget.test.js test/v20-projection-quality.test.js test/v20-quality-summary.test.js test/v20-visual-regression.test.js",
     "test:unit": "node --test test/core.test.js test/proven-generator.test.js",
     "test:integration": "node --test test/api.test.js test/workflow.integration.test.js test/state-machine.integration.test.js",
     "test:e2e": "node --test test/e2e.test.js",