Merge branch 'main' into add-agents-md

Author: DUBSOpenHub

.github/workflows/ci.yml

@@ -9,19 +9,93 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
       - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
         with:
           python-version: "3.11"
 
       - name: Run Python validator tests
         run: cd validators && python -m unittest test_shadow_score -v
 
+      - name: Run conformance suite (Python validator)
+        run: python3 tests/conformance/run_conformance.py -v
+
       - name: Validate JSON schema syntax
         run: python -c "import json; json.load(open('validators/shadow-report-schema.json'))"
 
+      - name: Validate schema is a well-formed Draft-07 schema
+        run: |
+          pip install --quiet jsonschema
+          python -c "
+          import json
+          from jsonschema import Draft7Validator
+          Draft7Validator.check_schema(json.load(open('validators/shadow-report-schema.json')))
+          print('schema ok')
+          "
+
+      - name: Run schema conformance tests
+        run: python3 validators/test_schema.py
+
+      - name: Check spec version is consistent across spec and validators
+        run: |
+          python3 - <<'EOF'
+          import re, sys, pathlib
+          spec = pathlib.Path('SPEC.md').read_text()
+          m = re.search(r'\*\*Version:\*\*\s*([0-9]+\.[0-9]+\.[0-9]+)', spec)
+          if not m:
+              sys.exit('could not find version header in SPEC.md')
+          want = m.group(1)
+          checks = {
+              'validators/shadow-score.py': r'SPEC_VERSION = "([^"]+)"',
+              'validators/shadow-score.sh': r'SPEC_VERSION="([^"]+)"',
+              'validators/shadow-score.go': r'const specVersion = "([^"]+)"',
+          }
+          bad = False
+          for path, pat in checks.items():
+              got = re.search(pat, pathlib.Path(path).read_text())
+              got = got.group(1) if got else None
+              flag = 'ok ' if got == want else 'FAIL'
+              if got != want:
+                  bad = True
+              print(f'  {flag} {path}: {got} (spec: {want})')
+          sys.exit(1 if bad else 0)
+          EOF
+
+      - name: Check for stale gap-score naming
+        run: |
+          if grep -rn "gap_score\|gap-score\|Gap Report\|Gap Score" \
+               --include="*.md" --include="*.py" --include="*.json" \
+               --include="*.go" --include="*.sh" --include="*.yml" . \
+             | grep -v "minor-gaps\|critical-gaps" \
+             | grep -v "renamed to" \
+             | grep -v "^\./\.github/workflows/ci\.yml:" ; then
+            echo "::error::Stale gap-score naming found (renamed to shadow-score in v2.0.0)"
+            exit 1
+          fi
+          echo "no stale naming"
+
+      - name: Check all referenced repo files exist
+        run: |
+          python3 - <<'EOF'
+          import re, pathlib, sys
+          bad = False
+          for md in pathlib.Path('.').rglob('*.md'):
+              if '.git' in md.parts:
+                  continue
+              for link in re.findall(r'\]\(([^)#][^)]*)\)', md.read_text()):
+                  link = link.split('#')[0].strip()
+                  if not link or link.startswith(('http://', 'https://', 'mailto:')):
+                      continue
+                  target = (md.parent / link).resolve()
+                  if not target.exists():
+                      print(f'  FAIL {md}: broken link -> {link}')
+                      bad = True
+          print('link check done')
+          sys.exit(1 if bad else 0)
+          EOF
+
       - name: Validate example JSON files
         run: |
           python -c "
@@ -38,7 +112,7 @@ jobs:
           "
 
       - name: Set up Go
-        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff  # v5
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
         with:
           go-version: "1.21"
 

.github/workflows/codeql.yml

@@ -17,9 +17,9 @@ jobs:
       matrix:
         language: [python, go]
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
-      - uses: github/codeql-action/init@45580472a5bb82c4681c4ac726cfdb60060c2ee1  # v3
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81  # v4.37.3
         with:
           languages: ${{ matrix.language }}
-      - uses: github/codeql-action/autobuild@45580472a5bb82c4681c4ac726cfdb60060c2ee1  # v3
-      - uses: github/codeql-action/analyze@45580472a5bb82c4681c4ac726cfdb60060c2ee1  # v3
+      - uses: github/codeql-action/autobuild@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81  # v4.37.3
+      - uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81  # v4.37.3

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to Gap Score Spec
+# Contributing to Shadow Score Spec
 
-Thank you for your interest in contributing to the Gap Score Specification! This is an open specification and contributions are welcome.
+Thank you for your interest in contributing to the Shadow Score Specification! This is an open specification and contributions are welcome.
 
 ## How to Contribute
 
@@ -19,13 +19,13 @@ Reference validators in additional languages are welcome. PRs for Go, Rust, Type
 Requirements for new validators:
 - Must conform to the current spec version
 - Must handle the same input format as the existing validators (or document differences)
-- Must produce output conforming to `validators/gap-report-schema.json`
+- Must produce output conforming to `validators/shadow-report-schema.json`
 - Must include unit tests
 - Must pass against all examples in `examples/`
 
 ### Adopter Listings
 
-If you're using Gap Score in your project, add it to the Adopters table in `README.md`:
+If you're using Shadow Score in your project, add it to the Adopters table in `README.md`:
 
 1. Fork the repository
 2. Add your project to the table with conformance level and description
@@ -41,14 +41,14 @@ Found an inconsistency, typo, or bug in a validator? Open an issue with:
 ## Development Setup
 
 ```bash
-git clone https://github.com/DUBSOpenHub/gap-score-spec.git
-cd gap-score-spec
+git clone https://github.com/DUBSOpenHub/shadow-score-spec.git
+cd shadow-score-spec
 
 # Run the validator unit tests
-python -m pytest validators/test_gap_score.py -v
+python -m pytest validators/test_shadow_score.py -v
 
 # Run a validator against an example
-python validators/gap-score.py \
+python validators/shadow-score.py \
   --sealed examples/02-minor-gaps/sealed-results.json \
   --open examples/02-minor-gaps/open-results.json \
   --format summary

README.md

@@ -1,8 +1,8 @@
 # 📊 Shadow Score Spec
 
-[![Spec Version](https://img.shields.io/badge/spec-v1.0.0-blue.svg)](SPEC.md)
+[![Spec Version](https://img.shields.io/badge/spec-v2.0.0-blue.svg)](SPEC.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Conformance Levels](https://img.shields.io/badge/conformance-L1%20%7C%20L2%20%7C%20L3-green.svg)](SPEC.md#6-conformance-levels)
+[![Conformance Levels](https://img.shields.io/badge/conformance-L1%20%7C%20L2%20%7C%20L3%20%7C%20L4-green.svg)](SPEC.md#6-conformance-levels)
 
 **A framework-agnostic metric for measuring AI code generation quality.**
 
@@ -56,11 +56,11 @@ cd validators && go build -o shadow-score-go . && cd ..
 
 ### Option B: Compute it yourself
 
-1. **Write sealed tests** from your spec (requirements → test cases, before code exists)
+1. **Write sealed tests** from your spec (requirements → test cases, before code exists) — using a *different model family* than the one that will implement
 2. **Build the code** — the implementer never sees the sealed tests
-3. **Run both suites** — sealed tests and the implementer's own tests
+3. **Run both suites** — in a disposable workspace built from the implementer's commit
 4. **Compute**: `failed_sealed / total_sealed × 100`
-5. **Report**: Use the [JSON schema](validators/shadow-report-schema.json) or markdown format
+5. **Report**: Use the [JSON schema](validators/shadow-report-schema.json) or markdown format, including which families authored each side
 
 That's it. Framework, language, and tooling don't matter — Shadow Score works anywhere.
 
@@ -71,12 +71,16 @@ Shadow Score is computed using the **Sealed-Envelope Protocol** — a 4-phase te
 ```
  SPEC ──► SEAL GENERATION ──► IMPLEMENTATION ──► VALIDATION ──► HARDENING
            (tests from spec,     (code + own        (run both      (fix from
-            hidden from          tests, never       suites,       failure msgs
-            implementer)         sees sealed)       compute gap)   only — no
-                                                                  test code)
+            hidden from          tests, never       suites in a   failure msgs
+            implementer,         sees sealed)       disposable    only — no
+            different model                        workspace)     test code)
+            family)
 ```
 
-**The critical rule:** The implementer **never sees** the sealed tests. During hardening, they receive only failure messages (test name, expected, actual) — never the test source code. This forces root-cause fixes, not test-targeting hacks.
+**The two critical rules:**
+
+1. **Isolation** — the implementer **never sees** the sealed tests. During hardening it receives only failure messages (test name, expected, actual), never test source. This forces root-cause fixes, not test-targeting hacks.
+2. **Independence** — the sealed tests are written by a **different model family** than the implementation. Isolation stops the builder seeing the tests; it does not stop it thinking like their author. Same-family agents share blind spots, so the scenario nobody tested is the scenario nobody handled.
 
 Full protocol details: [**SPEC.md §4**](SPEC.md#4-sealed-envelope-protocol)
 
@@ -87,10 +91,13 @@ Full protocol details: [**SPEC.md §4**](SPEC.md#4-sealed-envelope-protocol)
 | **L1** — Shadow Score | Compute + report Shadow Score | Retrofitting onto existing test suites |
 | **L2** — Sealed Envelope | L1 + test isolation + tamper hash | AI agent pipelines |
 | **L3** — Full Protocol | L2 + hardening loop + velocity tracking | Production autonomous builds |
+| **L4** — Adversarial Independence | L3 + cross-family authorship + disposable verify workspace + provenance in report | Published or gate-blocking scores |
+
+**Why L4 exists:** L1–L3 harden *information* isolation — they stop the builder from **seeing** the tests. They are all silently defeated by one configuration choice: pointing the seal author and the implementer at the same model. Same-family agents share blind spots, so the untested defect is also the unhandled defect. The sealed test is never written, the score reads 0%, and the bug ships green. That bias is directional — it always overclaims quality. See [**SPEC.md §3.6**](SPEC.md#36-authorship-independence).
 
 ## Reference Implementations
 
-The reference Level 3 implementation is **[Dark Factory](https://github.com/DUBSOpenHub/dark-factory)** — an autonomous agentic build system for the GitHub Copilot CLI with sealed-envelope testing.
+The reference Level 4 implementation is **[Dark Factory](https://github.com/DUBSOpenHub/dark-factory)** — an autonomous agentic build system for the GitHub Copilot CLI with sealed-envelope testing, cross-family model independence enforced pre-dispatch, and seal plurality.
 
 The reference Level 2 implementation is **[Terminal Stampede](https://github.com/DUBSOpenHub/terminal-stampede)** — a parallel agent runtime that shadow-scores each agent's work during merge using sealed tests with tamper-hash verification.
 
@@ -110,10 +117,15 @@ Shadow Reports can be produced in JSON (machine-readable) or Markdown (human-rea
 
 ```json
 {
-  "shadow_score_spec_version": "1.0.0",
+  "shadow_score_spec_version": "2.0.0",
   "report": {
     "shadow_score": 11.1,
-    "level": "minor"
+    "level": "minor",
+    "conformance_level": 4,
+    "independence": "strong",
+    "implementer_family": "anthropic",
+    "seal_author_families": ["openai", "google"],
+    "workspace_isolation": "strict"
   },
   "sealed_tests": { "total": 18, "passed": 16, "failed": 2 },
   "failures": [
@@ -128,13 +140,15 @@ Shadow Reports can be produced in JSON (machine-readable) or Markdown (human-rea
 }
 ```
 
+A Shadow Score without provenance cannot be interpreted: 0% under `strong` independence and 0% under `weak` independence are different claims about the world, and only one of them is evidence.
+
 Full schema: [**SPEC.md §5**](SPEC.md#5-reporting-format)
 
 ## Adopters
 
 | Project | Conformance | Description |
 |---------|-------------|-------------|
-| [Dark Factory](https://github.com/DUBSOpenHub/dark-factory) | Level 3 | Reference implementation — autonomous agentic build system |
+| [Dark Factory](https://github.com/DUBSOpenHub/dark-factory) | Level 4 | Reference implementation — autonomous agentic build system with cross-family adversarial independence |
 | [Terminal Stampede](https://github.com/DUBSOpenHub/terminal-stampede) | Level 2 | Parallel agent runtime — shadow-scores each agent's work during merge via sealed tests |
 
 *Using Shadow Score? [Open a PR](https://github.com/DUBSOpenHub/shadow-score-spec/pulls) to add your project.*

SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Reporting a Vulnerability
 
-If you discover a security vulnerability in the Gap Score reference validators or specification, please report it responsibly.
+If you discover a security vulnerability in the Shadow Score reference validators or specification, please report it responsibly.
 
 ### How to Report
 
@@ -23,9 +23,9 @@ If you discover a security vulnerability in the Gap Score reference validators o
 ### Scope
 
 This security policy covers:
-- **Reference validators** (`validators/gap-score.py`, `validators/gap-score.sh`) — e.g., input injection, path traversal
-- **JSON Schema** (`validators/gap-report-schema.json`) — e.g., schema bypass enabling malicious payloads
-- **Specification** (`SPEC.md`) — e.g., protocol weaknesses that could allow gaming the Gap Score
+- **Reference validators** (`validators/shadow-score.py`, `validators/shadow-score.sh`) — e.g., input injection, path traversal
+- **JSON Schema** (`validators/shadow-report-schema.json`) — e.g., schema bypass enabling malicious payloads
+- **Specification** (`SPEC.md`) — e.g., protocol weaknesses that could allow gaming the Shadow Score
 
 ### Out of Scope