Reduce external reproduction friction

Author: lloitesa013

README.md

@@ -85,6 +85,17 @@ claims.
 For a clean clone, expected outputs, and mismatch reporting, use the
 [reproduction guide](docs/REPRODUCTION.md).
 
+If dependencies are already installed in your current environment, the module
+commands are OS-neutral:
+
+```bash
+python -m pip install -r requirements-dev.txt
+python -m unittest discover -s tests
+python -m cognitive_os.benchmarks.cognitiveos_v0.run_external_reference_pack --pretty
+```
+
+Windows PowerShell using the local venv executable:
+
 ```powershell
 python -m venv .venv
 .\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
@@ -101,6 +112,9 @@ External reviewer-owned CSV/JSONL/JSON files can be run through the same
 adapter without exporting raw prompt text. See
 [docs/EXTERNAL_REPRODUCTION.md](docs/EXTERNAL_REPRODUCTION.md).
 
+Default reproduction uses the local `mock` provider and requires no API key,
+network call, or OpenAI model name.
+
 Optional FastAPI server:
 
 ```powershell
@@ -178,6 +192,7 @@ are not stored for later retrieval unless explicitly requested.
 - [docs/REPRODUCTION.md](docs/REPRODUCTION.md)
 - [docs/EXTERNAL_REPRODUCTION.md](docs/EXTERNAL_REPRODUCTION.md)
 - [docs/EXTERNAL_RESULT_REPORTING.md](docs/EXTERNAL_RESULT_REPORTING.md)
+- [docs/SELF_AUDIT_REPRODUCTION_REPORT.md](docs/SELF_AUDIT_REPRODUCTION_REPORT.md)
 - [docs/DEMO_SCRIPT_60_SEC.md](docs/DEMO_SCRIPT_60_SEC.md)
 - [docs/DEMO_SCRIPT_3_MIN.md](docs/DEMO_SCRIPT_3_MIN.md)
 

cognitive_os/benchmarks/cognitiveos_v0/run_external_reference_pack.py

@@ -45,11 +45,11 @@ def load_external_items(path: Path) -> List[Mapping[str, str]]:
     elif suffix == ".jsonl":
         rows = [
             json.loads(line)
-            for line in path.read_text(encoding="utf-8").splitlines()
+            for line in path.read_text(encoding="utf-8-sig").splitlines()
             if line.strip()
         ]
     elif suffix == ".json":
-        payload = json.loads(path.read_text(encoding="utf-8"))
+        payload = json.loads(path.read_text(encoding="utf-8-sig"))
         rows = payload.get("items", payload) if isinstance(payload, dict) else payload
     else:
         raise ValueError("External reference input must be .csv, .jsonl, or .json.")

docs/EXTERNAL_REPRODUCTION.md

@@ -30,19 +30,43 @@ is a public-safe smoke test. It is not a third-party benchmark result.
 
 Run the bundled public-safe fixture:
 
+OS-neutral:
+
+```bash
+python -m cognitive_os.benchmarks.cognitiveos_v0.run_external_reference_pack --pretty
+```
+
+Windows PowerShell with the local venv executable:
+
 ```powershell
 .\.venv\Scripts\python.exe -m cognitive_os.benchmarks.cognitiveos_v0.run_external_reference_pack --pretty
 ```
 
 Run a reviewer-owned local file:
 
+OS-neutral:
+
+```bash
+python -m cognitive_os.benchmarks.cognitiveos_v0.run_external_reference_pack \
+  --input /path/to/reviewer_dataset.jsonl \
+  --dataset-label "reviewer-local-redteam-v1" \
+  --pretty
+```
+
+Windows PowerShell with the local venv executable:
+
 ```powershell
 .\.venv\Scripts\python.exe -m cognitive_os.benchmarks.cognitiveos_v0.run_external_reference_pack `
   --input C:\path\to\reviewer_dataset.jsonl `
   --dataset-label "reviewer-local-redteam-v1" `
   --pretty
 ```
 
+By default the adapter uses `--provider mock`. That path is deterministic and
+does not require an API key, an OpenAI model name, or a network call. If a
+reviewer chooses `--provider openai` or `--provider openai:<model>`, that is a
+separate provider smoke test and must use explicit local credentials.
+
 ## What The Report Emits
 
 - source labels
@@ -89,3 +113,11 @@ source project and transform it locally into the four-field schema above.
 Any such run should be described as reviewer-provided local evidence unless the
 dataset source, transformation, command, and environment are independently
 auditable.
+
+## Maintainer Self-Audit
+
+The first maintainer self-audit is recorded in
+[SELF_AUDIT_REPRODUCTION_REPORT.md](SELF_AUDIT_REPRODUCTION_REPORT.md). It is
+not an outside reproduction report. It documents one friction fix: JSON/JSONL
+inputs with a UTF-8 BOM are now accepted, which matters for files created by
+some Windows tools.

docs/REPRODUCTION.md

@@ -20,8 +20,8 @@ CI currently runs on:
 - Python 3.7
 - `requirements-dev.txt`
 
-Local Windows PowerShell reproduction is expected to work with Python 3.7 or
-newer.
+Local reproduction is expected to work with Python 3.7 or newer on Windows,
+macOS, or Linux.
 
 ## Fresh Clone
 
@@ -33,6 +33,16 @@ python -m venv .venv
 .\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
 ```
 
+macOS/Linux venv equivalent:
+
+```bash
+git clone https://github.com/lloitesa013/cognitive-os-api.git
+cd cognitive-os-api
+python -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -r requirements-dev.txt
+```
+
 ## Verification Commands
 
 ```powershell
@@ -42,11 +52,25 @@ python -m venv .venv
 .\.venv\Scripts\python.exe -m cognitive_os.benchmarks.cognitiveos_v0.run_benchmark --pretty
 .\.venv\Scripts\python.exe -m cognitive_os.benchmarks.cognitiveos_v0.run_baselines --pretty
 .\.venv\Scripts\python.exe -m cognitive_os.benchmarks.cognitiveos_v0.run_conformance --pretty
+.\.venv\Scripts\python.exe -m cognitive_os.benchmarks.cognitiveos_v0.run_external_reference_pack --pretty
+```
+
+OS-neutral module commands, assuming dependencies are installed in the active
+environment:
+
+```bash
+python -m unittest -v tests.test_api tests.test_benchmark tests.test_provider
+python -m cognitive_os.benchmarks.cognitiveos_v0.run_adversarial
+python -m cognitive_os.benchmarks.cognitiveos_v0.run_challenge_pack --pretty
+python -m cognitive_os.benchmarks.cognitiveos_v0.run_benchmark --pretty
+python -m cognitive_os.benchmarks.cognitiveos_v0.run_baselines --pretty
+python -m cognitive_os.benchmarks.cognitiveos_v0.run_conformance --pretty
+python -m cognitive_os.benchmarks.cognitiveos_v0.run_external_reference_pack --pretty
 ```
 
 ## Expected Result
 
-The unit command should report 16 tests passing, with one OpenAI integration
+The unit command should report 19 tests passing, with one OpenAI integration
 test skipped unless explicitly enabled.
 
 Included seed/adversarial suites should reproduce the README's headline
@@ -65,6 +89,10 @@ third_party_benchmark: false
 The lower challenge-pack gate score is limitation evidence. It should not be
 rewritten into a success claim.
 
+The external reference adapter uses `mock` by default and requires no network
+access, API key, or OpenAI model name. The OpenAI adapter is separate and
+disabled unless a reviewer explicitly selects it and provides local credentials.
+
 ## Evidence Privacy Check
 
 Public evidence endpoints and exports should not expose raw prompt text or raw

docs/SELF_AUDIT_REPRODUCTION_REPORT.md

@@ -0,0 +1,87 @@
+# Maintainer Self-Audit Reproduction Report
+
+This is a maintainer self-audit, not an outside reproduction report and not a
+third-party benchmark result. Its purpose is to test the reviewer-provided local
+file path before asking an outside person to use it.
+
+## Result
+
+- Reproduced as documented: yes
+- Input type: reviewer-style local JSONL
+- Dataset label: `maintainer-self-audit-v1`
+- Provider: `mock`
+- Network required: no
+- API key required: no
+- OpenAI model name required: no
+- Raw prompts included in this report: no
+- Candidate/model output text included in this report: no
+
+## Environment
+
+- OS: Windows
+- Shell: PowerShell
+- Python: local `.venv` Python
+- Commit tested before this report: `f7f48f0`
+
+## Command Shape
+
+The local JSONL contained one public-safe item with the required fields:
+`source`, `item_id`, `category`, and `prompt`. The prompt itself is not pasted
+here; the adapter emitted only the prompt hash.
+
+```powershell
+.\.venv\Scripts\python.exe -m cognitive_os.benchmarks.cognitiveos_v0.run_external_reference_pack `
+  --input .self_audit_reviewer.jsonl `
+  --dataset-label maintainer-self-audit-v1 `
+  --pretty
+```
+
+OS-neutral equivalent:
+
+```bash
+python -m cognitive_os.benchmarks.cognitiveos_v0.run_external_reference_pack \
+  --input ./self_audit_reviewer.jsonl \
+  --dataset-label maintainer-self-audit-v1 \
+  --pretty
+```
+
+## Redacted Summary Metrics
+
+```json
+{
+  "benchmark_type": "external_reference_pack",
+  "run_type": "reviewer_provided_local_file",
+  "third_party_benchmark": false,
+  "external_input_provided": true,
+  "dataset_label": "maintainer-self-audit-v1",
+  "provider": "mock",
+  "item_count": 1,
+  "profile_count": 3,
+  "total_decisions": 3,
+  "trace_completeness": 1.0,
+  "redaction_pass_rate": 1.0,
+  "profile_separation_rate": 1.0,
+  "gate_distribution_by_profile": {
+    "guardian": {"DENY": 1},
+    "truth_first": {"DEGRADE": 1},
+    "progress_max": {"DEGRADE": 1}
+  }
+}
+```
+
+## Friction Found And Fixed
+
+The first PowerShell-created JSONL file included a UTF-8 byte-order mark. The
+adapter initially rejected that file with a JSON decode error. The loader now
+reads `.json` and `.jsonl` inputs with `utf-8-sig`, matching the already tolerant
+CSV path.
+
+This matters because a reviewer using Windows tooling can create a valid-looking
+JSONL file that carries a BOM. The adapter should handle that case clearly.
+
+## Boundary
+
+This report proves only that the maintainer could run the local-file path and
+that the default adapter path does not require network access. It does not prove
+external adoption, third-party benchmark performance, broad model safety, or
+production readiness.

tests/test_benchmark.py

@@ -116,6 +116,19 @@ def test_external_reference_missing_required_fields_fails_clearly(self):
             with self.assertRaisesRegex(ValueError, "missing required fields"):
                 load_external_items(path)
 
+    def test_external_reference_jsonl_accepts_utf8_bom(self):
+        with TemporaryDirectory() as temp_dir:
+            path = Path(temp_dir) / "reviewer_fixture.jsonl"
+            path.write_text(
+                (
+                    '\ufeff{"source":"local","item_id":"case-1",'
+                    '"category":"finance","prompt":"Use verified sources."}\n'
+                ),
+                encoding="utf-8",
+            )
+            rows = load_external_items(path)
+        self.assertEqual(rows[0]["item_id"], "case-1")
+
 
 if __name__ == "__main__":
     unittest.main()