spec: v8, explicit settlement semantics

   Finalize the ENGI demo’s V8 closure pass and bring the repo’s current-state
   implementation, docs, and operator story into clean alignment.

   Core implementation alignment
   - rename the canonical demo engine from src/spec-v7-demo.js to src/engi-demo.js
   - update runtime/test imports and references accordingly
   - preserve historical V7 coverage material rather than collapsing versioned history

   Current-state V8 repo cleanup
   - update README, SCRIPT, SCRIPT_SHORT, and CHECKLIST to describe the demo as V8
   - remove stale V7 framing from current operator-facing surfaces
   - keep SPEC_V7_COVERAGE_MATRIX.md as historical reference
   - refresh SPEC_V8_COVERAGE_MATRIX.md so it serves as the authoritative
   audit/design/closure document for the current demo

   Settlement semantics closure
   - keep the deterministic marginal-contribution settlement logic unchanged
   - make the semantics explicit instead of implying that all selected
   settlement-eligible assets must receive positive credit
   - distinguish in artifacts/UI/tests between:
   - selected branch assets
   - settlement participants
   - credited settlement assets
   - zero-credit participants
   - extend settlement preview surfaces with explicit IDs, richer allocations,
   rationale text, and operator-facing semantics notes
   - update ENGI_NEED markdown and UI summaries to reflect credited vs zero-credit
   outcomes clearly

   Verification
   - refresh seeded state to clean V8-aligned repo data
   - add/adjust tests to pin the seeded settlement semantics intentionally
   - npm test passes cleanly: 52/52

Author: geraldarthurdavis

engi-demo/CHECKLIST.md

@@ -1,6 +1,6 @@
-# ENGI Demo Checklist — Spec V7
+# ENGI Demo Checklist — Spec V8
 
-Use this before an interactive V7 demo, QA pass, or live walkthrough.
+Use this before an interactive V8 demo, QA pass, or live walkthrough.
 
 ---
 
@@ -15,7 +15,7 @@ npm start
 
 - [ ] Open: `http://127.0.0.1:4318`
 - [ ] Confirm the page loads
-- [ ] Confirm the hero says **Spec V7**
+- [ ] Confirm the hero says **Spec V8**
 - [ ] Confirm the primary CTA is **Make ENGI branch**
 - [ ] Confirm no stale V6/query-era language is visible in the main flow
 - [ ] Confirm JSON-heavy surfaces default to **Visual** mode and can be flipped to **Raw**
@@ -40,7 +40,7 @@ Expected seeded scenario cues:
 
 ---
 
-## 2. V7 gold-path interactive run
+## 2. V8 gold-path interactive run
 
 ### A. Need measurement
 
@@ -105,7 +105,7 @@ What should be visible after the run:
 
 ---
 
-## 3. Advanced V7 surfaces
+## 3. Advanced V8 surfaces
 
 ### Content-unit semantics / vector interfaces
 
@@ -140,12 +140,12 @@ What should be visible after the run:
 
 ## 4. E2E QA verdict
 
-Call the demo **interactive V7 E2E-QA ready** only if all of the following are true:
+Call the demo **interactive V8 E2E-QA ready** only if all of the following are true:
 
 - [ ] page loads cleanly
 - [ ] reset works
 - [ ] make-ENGI-branch gold path works end-to-end
-- [ ] V7 profile/derivation/rights/telemetry surfaces are visible
+- [ ] V8 profile/derivation/rights/telemetry surfaces are visible
 - [ ] settlement invariants hold
 - [ ] no stale query-first story is required to understand the demo
 - [ ] docs/checklist match the actual UI/runtime behavior
@@ -160,7 +160,7 @@ Call the demo **interactive V7 E2E-QA ready** only if all of the following are t
 
 ### If the UI seems stale
 - [ ] Hard refresh browser
-- [ ] Verify `data/state.json` was regenerated from the current V7 model if needed
+- [ ] Verify `data/state.json` was regenerated from the current V8 model if needed
 
 ### If the server is not responding
 
@@ -184,6 +184,6 @@ Do not present the demo as:
 - a real policy publication / authz enforcement plane
 
 Present it as:
-- a **Spec V7 Profile A deterministic prototype**
+- a **Spec V8 Profile A deterministic prototype**
 - with explicit **Profile B production-boundary intent**
 - and with strong inspectability across ranking, verification, artifacts, telemetry, and settlement

engi-demo/README.md

@@ -1,10 +1,10 @@
-# ENGI Demo — Spec V7 Deterministic Local Prototype
+# ENGI Demo — Spec V8 Deterministic Local Prototype
 
-This demo now tracks the Spec V7 core flow much more closely:
+This demo now tracks the Spec V8 core flow closely:
 
 1. parse mocked GitHub Actions evidence through a declared benchmark parser contract and build a `GitHubNeedDescriptor`,
 2. model hybrid candidate recall across task, failure-mode, technical-context, lexical, symbol, path, config, and artifact-kind channels,
-3. rank deposited candidate assets with explicit Spec V7 subscores, explainability traces, and penalties,
+3. rank deposited candidate assets with explicit Spec V8 score groups, explainability traces, and penalties,
 4. apply separate verification determinisms, issuer policy, and downstream use-tier propagation,
 5. assemble a locked `AssetPack` plus selected source-material manifest,
 6. stage a private remediation branch artifact set with deliverable metadata, authorization decisions, and sensitive-data-flow records,
@@ -13,7 +13,7 @@ This demo now tracks the Spec V7 core flow much more closely:
 
 ## What this prototype is
 
-A deterministic, local, no-dependency Node app that models the V7 Profile A architecture faithfully enough to demo while explicitly labeling Profile B production intent:
+A deterministic, local, no-dependency Node app that models the V8 Profile A architecture faithfully enough to demo while explicitly labeling Profile B production intent:
 
 - need measurement from GitHub-bound benchmark evidence,
 - parser fail-closed behavior and canonical run-evidence normalization,
@@ -48,7 +48,7 @@ All of those surfaces are represented deterministically in local state.
 - `Profile A — local deterministic prototype`: what this repo implements and demos now.
 - `Profile B — production-boundary intent`: live GitHub binding, real branch/privacy/authz enforcement, real embeddings/evaluators/prompts, and external integrations still outside the local prototype boundary.
 
-## Advanced V7 interface notes
+## Advanced V8 interface notes
 
 - Content units now carry explicit semantic/embedding contracts so real embedding providers can replace deterministic stand-ins without changing downstream schemas.
 - Measurement provenance distinguishes static deterministic analysis from inferred evaluator surfaces.
@@ -107,4 +107,5 @@ npm test
 - `ARCHITECTURE_MAP.md` — tight map of the original/current demo architecture baseline
 - `SPEC_V6_GAP_ANALYSIS.md` — earlier gap analysis and implementation guide used for the V6 refactor
 - `SPEC_V6_COVERAGE_MATRIX.md` — durable section-by-section coverage audit against the V6 spec
-- `SPEC_V7_COVERAGE_MATRIX.md` — section-by-section coverage audit against the V7 spec, including V6→V7 deltas and Profile A/Profile B splits
+- `SPEC_V7_COVERAGE_MATRIX.md` — preserved historical coverage audit for the V7 spec and V6→V7 deltas
+- `SPEC_V8_COVERAGE_MATRIX.md` — authoritative audit/design/closure plan for the current V8 demo

engi-demo/SCRIPT.md

@@ -1,6 +1,6 @@
-# ENGI Demo Script — Spec V7
+# ENGI Demo Script — Spec V8
 
-This is the live presentation / interactive QA script for the current ENGI V7 deterministic prototype.
+This is the live presentation / interactive QA script for the current ENGI V8 deterministic prototype.
 
 ---
 
@@ -12,7 +12,7 @@ ENGI measures a GitHub-bound engineering need, matches the right technical intel
 
 ## What this demo is
 
-This demo is **Profile A — local deterministic prototype** behavior for ENGI Spec V7.
+This demo is **Profile A — local deterministic prototype** behavior for ENGI Spec V8.
 
 It is meant to demonstrate:
 - need measurement from GitHub-bound benchmark evidence,
@@ -41,10 +41,10 @@ Say something like:
 
 > ENGI is a system for turning engineering knowledge into an inspectable remediation pipeline.
 >
-> In Spec V7, the key idea is not just storing or retrieving technical knowledge. The key idea is measuring a real GitHub-bound need, selecting the right technical intelligence supply for that need, materializing governed artifacts for remediation, and proving how value and rights flow through the system.
+> In Spec V8, the key idea is not just storing or retrieving technical knowledge. The key idea is measuring a real GitHub-bound need, selecting the right technical intelligence supply for that need, materializing governed artifacts for remediation, and proving how value and rights flow through the system.
 
 Then point out:
-- Spec V7
+- Spec V8
 - Profile A / Profile B framing
 - the seeded GitHub-bound auth rollback scenario
 
@@ -182,7 +182,7 @@ Operator note:
 
 ---
 
-### 5. Telemetry and advanced V7 surfaces
+### 5. Telemetry and advanced V8 surfaces
 
 #### Where to look
 
@@ -192,7 +192,7 @@ Operator note:
 
 #### What to say
 
-> V7 adds stronger interface codification around unitization, semantics, embeddings, evaluator surfaces, and telemetry.
+> V8 adds stronger interface codification around unitization, semantics, embeddings, evaluator surfaces, and telemetry.
 >
 > So now the demo can show not only what was selected, but how units were derived, what metadata/vector contracts exist, how recall/scoring hand-offs happened, and how those choices fed settlement and proof.
 
@@ -239,7 +239,7 @@ Important line:
 
 > ENGI turns engineering knowledge into a measurable, governable, inspectable remediation pipeline.
 >
-> In this V7 prototype, the system measures a GitHub-bound need, selects the right technical intelligence supply, materializes a governed branch artifact set, and proves both the operational and economic consequences.
+> In this V8 prototype, the system measures a GitHub-bound need, selects the right technical intelligence supply, materializes a governed branch artifact set, and proves both the operational and economic consequences.
 
 ---
 
@@ -249,7 +249,7 @@ Use this sequence when verifying the demo live:
 
 1. open the app
 2. reset seeded state
-3. confirm Profile A + Spec V7 labels
+3. confirm Profile A + Spec V8 labels
 4. confirm the auth rollback scenario
 5. click **Make ENGI branch**
 6. inspect evaluated candidates
@@ -266,7 +266,7 @@ Use this sequence when verifying the demo live:
 - Repo: `frontier/demo-auth`
 - Scenario: auth issuer rollback / migration recovery
 - Expected strongest asset: `Enterprise auth migration rollback playbook`
-- Important V7-only surfaces:
+- Important V8-only surfaces:
   - field derivations
   - use-tier rights
   - asset-pack-lock closure
@@ -286,5 +286,5 @@ Do **not** present the current demo as:
 - a real external proof-publication system.
 
 Present it as:
-- a **Spec V7 Profile A deterministic prototype**
-- with strong codification of the production-facing hand-offs and artifact contracts.
+- a **Spec V8 Profile A deterministic prototype**
+- with strong codification of the production-facing hand-offs and artifact contracts.

engi-demo/SCRIPT_SHORT.md

@@ -1,4 +1,4 @@
-# ENGI Demo Script — Short Version (Spec V7)
+# ENGI Demo Script — Short Version (Spec V8)
 
 Use this when you want the cleanest possible live explanation in ~90 seconds.
 
@@ -12,7 +12,7 @@ ENGI measures a GitHub-bound engineering need, matches the right technical intel
 
 ## 90-second script
 
-> This demo shows ENGI as a Spec V7 deterministic prototype.
+> This demo shows ENGI as a Spec V8 deterministic prototype.
 >
 > A buyer has a concrete GitHub-bound auth rollback incident with benchmark evidence from GitHub Actions. ENGI first normalizes that evidence into a measured need descriptor instead of treating the task as a loose prompt.
 >
@@ -46,7 +46,7 @@ ENGI measures a GitHub-bound engineering need, matches the right technical intel
 - Repo: `frontier/demo-auth`
 - Scenario: auth issuer rollback / migration recovery
 - Expected strongest asset: `Enterprise auth migration rollback playbook`
-- V7-specific artifacts to mention if asked:
+- V8-specific artifacts to mention if asked:
   - `.engi/unit-catalog.json`
   - `.engi/pipeline-telemetry.json`
   - `.engi/policy-release.json`