wip v14

Author: geraldarthurdavis

ENGI_SPEC.txt

@@ -1 +1 @@
-V12
+V14

ENGI_SPEC_TEMPLATEGUIDE.md

@@ -0,0 +1,132 @@
+# ENGI Spec V14 Notes
+
+## Why V14 exists
+
+V14 is the first full writing pass after V13 finalized the ENGI spec-file structure standard.
+
+With the V14 correction path, it is also the first version explicitly aligned to the standalone cross-version drafting guide at `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_TEMPLATEGUIDE.md`.
+
+The point of V14 is not to reopen ENGI design.
+The point is to write the current canon densely enough that:
+- the operating model is recoverable,
+- the artifact contracts are explicit,
+- host/runtime truth is canonical rather than incidental,
+- proof and settlement obligations are inspectable,
+- test coverage and operator-experience parity are canonical,
+- and current source parity is legible.
+
+## What V14 preserves
+
+V14 preserves the later design truths that should no longer drift:
+- depositing, needing, and fit are the center of the operator story,
+- Profile A and Profile B are distinguished by deposit mode and need mode,
+- identity/auth is one spine,
+- repo-to-settlement is one operating chain,
+- proof and settlement are closure,
+- bounded public proof is derived from private closure,
+- boundary reality is explicit supporting truth rather than hidden implementation detail.
+
+## What V14 restores
+
+V14 restores the denser explicitness that compressed versions lost, especially:
+- fuller schema detail,
+- stronger subsystem invariants,
+- stronger host capability and execution-truth treatment,
+- fuller inference/evaluator contracts,
+- fuller proof-family and witness-manifest treatment,
+- a real artifact appendix,
+- a real proof-obligations appendix,
+- a real test-coverage appendix,
+- a real spec-to-source parity appendix,
+- explicit operator-experience parity treatment where explainers or tooltips are canonical.
+
+## Template-guide alignment
+
+V14 now explicitly follows `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_TEMPLATEGUIDE.md`.
+
+That means this V14 file family now intentionally does all of the following:
+- keeps the V14 version executive summary separate from the canonical ENGI executive summary,
+- treats the spec, notes file, and implementation matrix as one coordinated file family,
+- preserves the latest-target vs last-fully-realized-canon distinction explicitly,
+- covers the whole ENGI operating chain rather than only the currently hottest subsystem,
+- treats host, inference, proof, test coverage, spec-to-source parity, and operator-experience parity as canonical structural material.
+
+## Important numbering decision
+
+V14 intentionally preserves the V12 semantic anchors for sections 6 through 13.
+
+That is not nostalgia.
+It is a practical traceability decision so the demo's explainer and reasoning surfaces can move from V12 references to V14 references without semantic remapping.
+
+## Important version-status nuance
+
+`ENGI_SPEC.txt = V14` means V14 is the current canonical/latest target.
+
+That does not erase the separate truth that V12 remains the last fully realized canon and the semantic implementation anchor for the current deterministic demo source.
+
+Both statements are required together.
+Dropping either one makes the repo easier to misread.
+
+## Important non-decision
+
+This tightening pass does not repoint `ENGI_SPEC.txt` away from V14.
+
+It also does not pretend that every V14 formalization is already fully source-realized.
+The current implementation is still the V12-target deterministic prototype, now interpreted and formalized through V14.
+
+## Writing posture for V14
+
+The right V14 posture is:
+- preserve current strong design truth,
+- restore explicitness around that current truth rather than reverting to obsolete framing,
+- prefer current builder, artifact, and subsystem names where they are already strong,
+- keep appendices purposeful rather than dumping notes,
+- record remaining doc/source lag explicitly in the implementation matrix rather than hiding it.
+
+## What should count as a real parity gap in this pass
+
+A real V14 parity gap is something like:
+- the spec and notes disagree about canonical pointer status,
+- the host/runtime section hand-waves execution truth instead of specifying it,
+- the inference appendix omits prompt contracts, context injectables, or parse contracts,
+- the proof appendix names proof families but does not map obligations and witnesses clearly,
+- the test appendix omits operator-experience parity where the demo depends on explainers,
+- the parity appendix fails to identify accepted boundaries or canonical UI interpretation surfaces.
+
+A non-gap is something like:
+- live GitHub token minting still being external,
+- live branch writes not happening in the local prototype,
+- real external settlement effects remaining modeled rather than executed,
+
+so long as those boundaries remain explicitly disclosed.
+
+## V14 validation emphasis
+
+The most important validation emphasis remains that browser e2e coverage is no longer "nice to have".
+It is canonical evidence that the operator story actually reads in the intended order.
+
+Where explainers, tooltips, or visual/raw dual renderings materially affect operator interpretation, their parity also counts as canonical validation material.
+
+## Tightening added in this correction path
+
+This correction path added or strengthened the following:
+- `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC_TEMPLATEGUIDE.md` as the standalone drafting guide for future enriched specs,
+- explicit V14 alignment to that guide,
+- explicit `ENGI_SPEC.txt = V14` plus `V12 remains the last fully realized canon` wording across the V14 file family,
+- stronger host capability treatment covering role, category boundaries, bootstrap/furnishing, containerization, telemetry/safety, and measurement/execution truth,
+- stronger inference appendix completeness covering moment contracts, prompt templates, context injectables, output ownership, and parse contracts,
+- stronger proof appendix completeness covering proof-family definitions, subsystem obligations, witness structures, theorem catalog material, and witness-manifest closure,
+- stronger operator-experience parity treatment in test and parity appendices.
+
+## Practical drafting reminder
+
+If a proposed addition makes the spec longer but not clearer, it is noise.
+
+If it makes:
+- subsystem obligations clearer,
+- execution truth clearer,
+- parity boundaries clearer,
+- validation traceability clearer,
+- or the operator chain easier to recover,
+
+then it is likely proper V14 material.

ENGI_SPEC_V14.md

@@ -1,6 +1,8 @@
 {
   "inspectedAt": "2026-04-03",
-  "specVersion": "ENGI Spec V9 deterministic local prototype",
+  "specVersion": "ENGI Spec V14 canonical target over the deterministic local prototype",
+  "canonicalPointerVersion": "V14",
+  "lastFullyRealizedCanonVersion": "V12",
   "repo": "engi-demo",
   "host": {
     "os": "Darwin 25.4.0",
@@ -84,7 +86,7 @@
     {
       "configurationId": "native-runtime",
       "command": "npm start",
-      "purpose": "Serve the local V9 demo UI and API"
+      "purpose": "Serve the local deterministic demo UI and API"
     },
     {
       "configurationId": "native-test",
@@ -93,14 +95,14 @@
     },
     {
       "configurationId": "docker-runtime",
-      "buildCommand": "docker build -t engi-demo-v9 .",
-      "runCommand": "docker run --rm -p 4318:4318 -e HOST=0.0.0.0 engi-demo-v9",
+      "buildCommand": "docker build -t engi-demo-v14 .",
+      "runCommand": "docker run --rm -p 4318:4318 -e HOST=0.0.0.0 engi-demo-v14",
       "purpose": "Serve the demo in a container"
     },
     {
       "configurationId": "docker-test",
-      "buildCommand": "docker build -t engi-demo-v9 .",
-      "runCommand": "docker run --rm engi-demo-v9 npm test",
+      "buildCommand": "docker build -t engi-demo-v14 .",
+      "runCommand": "docker run --rm engi-demo-v14 npm test",
       "purpose": "Run the regression suite in a container"
     }
   ],

ENGI_SPEC_V14_NOTES.md

@@ -1,21 +1,27 @@
 # ENGI Demo Host Capabilities
 
 Last inspected: 2026-04-03 (America/Los_Angeles)
-Host scope: local machine capabilities relevant to the ENGI Spec V9 demo implementation in this repo.
+Host scope: local machine capabilities relevant to the ENGI Spec V14 canonical target over the current deterministic demo implementation in this repo.
+
+## Canon status
+
+- Canonical pointer: `/Users/garrettmaring/Developer/ENGI/ENGI_SPEC.txt -> V14`
+- Current canonical/latest target: `V14`
+- Last fully realized canon preserved in the demo source: `V12`
 
 ## Purpose
 
-This document records what the host actually needs to run the current V9 demo, what it can optionally support, what remains modeled instead of executed, and how the repo can be furnished natively or in a container without overclaiming production readiness.
+This document records what the host actually needs to run the current deterministic demo implementation, what it can optionally support, what remains modeled instead of executed, and how the repo can be furnished natively or in a container without overclaiming production readiness.
 
 The source of truth for this document is:
 
 - live host inspection commands run on 2026-04-03
 - the current repo implementation in `server.js`, `src/engi-demo.js`, `public/app.js`, and `test/`
-- the current V9 artifact and proof flow, not older V8 assumptions
+- the current V14-canonical / V12-realized artifact and proof flow, not older V8/V9 framing
 
 ## Program usage truth
 
-### Required for the current V9 demo
+### Required for the current demo implementation
 
 The repo needs only a local Node runtime plus filesystem access to execute its real control-plane behavior:
 
@@ -25,7 +31,7 @@ The repo needs only a local Node runtime plus filesystem access to execute its r
 - assemble proof/materialization/accounting artifacts
 - run the Node test suite
 
-In the current implementation, the following V9 stages are real local program usage, but they are all executed by deterministic in-process Node logic rather than external commands:
+In the current implementation, the following stages are real local program usage, but they are all executed by deterministic in-process Node logic rather than external commands:
 
 - benchmark parser normalization: `github-actions.benchmark-parser.v9`
 - repo code-analysis derivation: `github.repo-context.extract.v9`
@@ -51,7 +57,7 @@ These are useful for inspection, authoring, proof-log generation outside the cor
 
 ### Proof-program usage truth
 
-The current V9 demo does **not** execute external proof engines as part of the core flow.
+The current demo does **not** execute external proof engines as part of the core flow.
 
 Instead it:
 
@@ -72,7 +78,7 @@ Observed on this host:
 - `gh` is installed
 - `gh auth status` currently reports the default token as invalid for `garrettmaring`
 
-V9 interpretation:
+Current interpretation:
 
 - GitHub CLI presence is real
 - GitHub CLI authorization is **not** currently healthy
@@ -141,14 +147,14 @@ For this repo specifically, furnishing is simpler:
 
 ### `docker-runtime`
 
-- build command: `docker build -t engi-demo-v9 .`
-- run command: `docker run --rm -p 4318:4318 -e HOST=0.0.0.0 engi-demo-v9`
+- build command: `docker build -t engi-demo-v14 .`
+- run command: `docker run --rm -p 4318:4318 -e HOST=0.0.0.0 engi-demo-v14`
 - purpose: containerized local serving with no host Node requirement beyond Docker
 
 ### `docker-test`
 
-- build command: `docker build -t engi-demo-v9 .`
-- run command: `docker run --rm engi-demo-v9 npm test`
+- build command: `docker build -t engi-demo-v14 .`
+- run command: `docker run --rm engi-demo-v14 npm test`
 - purpose: containerized regression check using the same image contents
 
 ## Telemetry and safety