docushell · docushell-dev · Jun 21, 2026 · Jun 21, 2026
diff --git a/.github/scripts/test_milestone_e_prep_guard_sequence_index.py b/.github/scripts/test_milestone_e_prep_guard_sequence_index.py
@@ -106,6 +106,7 @@
     "$(PYTHON) .github/scripts/test_milestone_e_package_publication_registry_assembly_activation_prep.py",
     "$(PYTHON) .github/scripts/test_milestone_e_package_publication_decision_bundle_validation_record.py",
     "$(PYTHON) .github/scripts/test_milestone_e_package_publication_pre_approval_gap_ledger.py",
+    "$(PYTHON) .github/scripts/test_milestone_e_public_facing_readiness_ledger.py",
     "$(PYTHON) .github/scripts/test_milestone_e_validation_command_index.py",
     "$(PYTHON) .github/scripts/test_milestone_e_validation_command_index_validation_record.py",
     "$(PYTHON) .github/scripts/test_milestone_e_validation_record_index.py",

diff --git a/.github/scripts/test_milestone_e_prep_scope.py b/.github/scripts/test_milestone_e_prep_scope.py
@@ -405,6 +405,7 @@ def test_make_target_is_narrow_and_guarded(self) -> None:
     "$(PYTHON) .github/scripts/test_milestone_e_package_publication_registry_assembly_activation_prep.py",
     "$(PYTHON) .github/scripts/test_milestone_e_package_publication_decision_bundle_validation_record.py",
     "$(PYTHON) .github/scripts/test_milestone_e_package_publication_pre_approval_gap_ledger.py",
+    "$(PYTHON) .github/scripts/test_milestone_e_public_facing_readiness_ledger.py",
     "$(PYTHON) .github/scripts/test_milestone_e_validation_command_index.py",
             "$(PYTHON) .github/scripts/test_milestone_e_validation_command_index_validation_record.py",
             "$(PYTHON) .github/scripts/test_milestone_e_validation_record_index.py",

diff --git a/.github/scripts/test_milestone_e_public_boundary_alignment.py b/.github/scripts/test_milestone_e_public_boundary_alignment.py
@@ -85,6 +85,10 @@ class BoundaryArtifact:
         "docs/milestone-e-package-publication-approval-prep.json",
         "schemas/ethos-milestone-e-package-publication-approval-prep.schema.json",
     ),
+    BoundaryArtifact(
+        "docs/milestone-e-public-facing-readiness-ledger.json",
+        "schemas/ethos-milestone-e-public-facing-readiness-ledger.schema.json",
+    ),
 )
 
 

diff --git a/.github/scripts/test_milestone_e_public_facing_readiness_ledger.py b/.github/scripts/test_milestone_e_public_facing_readiness_ledger.py
@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+#
+# Copyright 2026 The Ethos maintainers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import unittest
+from pathlib import Path
+
+from makefile_guard import target_block
+
+
+ROOT = Path(__file__).resolve().parents[2]
+LEDGER = ROOT / "docs/milestone-e-public-facing-readiness-ledger.json"
+SCHEMA = ROOT / "schemas/ethos-milestone-e-public-facing-readiness-ledger.schema.json"
+PUBLIC_BETA_PREP = ROOT / "docs/milestone-e-public-beta-approval-prep.json"
+PACKAGE_PREP = ROOT / "docs/milestone-e-package-publication-approval-prep.json"
+RECORD = (
+    ROOT
+    / "docs/validation/"
+    "milestone-e-public-facing-readiness-ledger-validation-2026-06-21.md"
+)
+VALIDATION_README = ROOT / "docs/validation/README.md"
+PREP_SCOPE = ROOT / "docs/milestone-e-prep-scope.md"
+ROADMAP = ROOT / "docs/roadmap.md"
+EXECUTION_STATUS = ROOT / "docs/execution-status.md"
+SCHEMAS_README = ROOT / "schemas/README.md"
+VALIDATE_EXAMPLES = ROOT / "schemas/validate_examples.py"
+CI_WORKFLOW = ROOT / ".github/workflows/ci.yml"
+
+CURRENT_MAIN_COMMIT = "847e12db42d4519665b1486ccb35c85fe01f00b0"
+CURRENT_MAIN_TREE = "9d3701aa14d98017626583c2a0a0ef45ac0df79f"
+EXPECTED_BOUNDARY = [
+    "public reports remain blocked",
+    "release artifacts remain blocked",
+    "package publication remains blocked",
+    "hosted surfaces remain blocked",
+    "public result wording remains blocked",
+    "performance claims remain blocked",
+    "quality claims remain blocked",
+    "footprint claims remain blocked",
+    "table-quality claims remain blocked",
+    "parser-quality claims remain blocked",
+]
+FORBIDDEN_SCOPE_EXPANSION = [
+    "public reports are approved",
+    "public result wording approved",
+    "release-ready",
+    "release artifact approved",
+    "package-ready",
+    "package publication is approved",
+    "package publication approved",
+    "packages are published",
+    "published packages",
+    "production-ready",
+    "production positioning approved",
+    "benchmark-validated",
+    "public benchmark pass",
+    "speed validated",
+    "fastest",
+    "launch-ready",
+    "hosted surface approved",
+    "hosted demo approved",
+    "demo-ready",
+    "performance validated",
+    "quality validated",
+    "footprint validated",
+    "table-quality validated",
+    "parser-quality validated",
+]
+
+
+def read(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def normalized(path: Path) -> str:
+    return re.sub(r"\s+", " ", read(path))
+
+
+def load_json(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def git(*args: str) -> str:
+    return subprocess.check_output(
+        ["git", *args],
+        cwd=ROOT,
+        encoding="utf-8",
+        stderr=subprocess.DEVNULL,
+    ).strip()
+
+
+class MilestoneEPublicFacingReadinessLedgerTests(unittest.TestCase):
+    def test_ledger_records_current_main_without_new_approval(self) -> None:
+        ledger = load_json(LEDGER)
+
+        self.assertEqual(1, ledger["schema_version"])
+        self.assertEqual("source-only-pre-alpha-internal-milestone-e-prep", ledger["status"])
+        self.assertEqual("public_facing_readiness_current_main_ledger", ledger["scope"])
+        self.assertEqual(
+            "current_main_readiness_recorded_without_new_approval",
+            ledger["ledger_state"],
+        )
+        self.assertEqual(CURRENT_MAIN_COMMIT, ledger["validated_current_main"]["commit"])
+        self.assertEqual(CURRENT_MAIN_TREE, ledger["validated_current_main"]["tree"])
+        self.assertIn("refresh candidate only", ledger["validated_current_main"]["candidate_status"])
+        self.assertEqual(EXPECTED_BOUNDARY, ledger["public_boundary"])
+
+    def test_current_main_binding_resolves_in_repository_history(self) -> None:
+        ledger = load_json(LEDGER)
+
+        self.assertEqual(CURRENT_MAIN_COMMIT, git("rev-parse", CURRENT_MAIN_COMMIT))
+        self.assertEqual(CURRENT_MAIN_TREE, git("rev-parse", f"{CURRENT_MAIN_COMMIT}^{{tree}}"))
+        subprocess.check_call(
+            ["git", "merge-base", "--is-ancestor", CURRENT_MAIN_COMMIT, "HEAD"],
+            cwd=ROOT,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        self.assertEqual(CURRENT_MAIN_COMMIT, ledger["current_main_refresh_candidate"]["candidate_commit"])
+        self.assertEqual(
+            git("rev-parse", f"{CURRENT_MAIN_COMMIT}^{{tree}}"),
+            ledger["current_main_refresh_candidate"]["candidate_tree"],
+        )
+
+    def test_existing_public_beta_binding_stays_separate(self) -> None:
+        ledger = load_json(LEDGER)
+        public_beta = load_json(PUBLIC_BETA_PREP)
+
+        self.assertEqual(
+            public_beta["approved_public_beta_source"],
+            ledger["approved_public_beta_source"],
+        )
+        self.assertEqual("d755e7c", ledger["approved_public_beta_source"]["reviewed_commit"])
+        self.assertEqual("3f9e1c4", ledger["approved_public_beta_source"]["merged_main_commit"])
+        self.assertNotEqual(
+            ledger["approved_public_beta_source"]["tree"],
+            ledger["current_main_refresh_candidate"]["candidate_tree"],
+        )
+        self.assertIn(
+            "requires dedicated source-only public beta refresh approval",
+            ledger["current_main_refresh_candidate"]["refresh_status"],
+        )
+
+    def test_package_resolution_criteria_match_gap_ledger(self) -> None:
+        ledger = load_json(LEDGER)
+        package_prep = load_json(PACKAGE_PREP)
+        gap_ledger = package_prep["package_publication_pre_approval_gap_ledger"]
+        criteria = ledger["package_publication_resolution_criteria"]
+
+        self.assertEqual("pre_approval_gaps_remain_unresolved", criteria["criteria_state"])
+        self.assertEqual(
+            gap_ledger["required_resolution_inputs"],
+            criteria["required_resolution_inputs"],
+        )
+        self.assertEqual(gap_ledger["retained_blockers"], criteria["retained_blockers"])
+
+    def test_cross_lane_blockers_and_non_approvals_are_explicit(self) -> None:
+        ledger = load_json(LEDGER)
+
+        self.assertEqual(14, len(ledger["cross_lane_blockers"]))
+        self.assertEqual(12, len(ledger["non_approvals"]))
+        self.assertIn("package publication remains blocked", ledger["cross_lane_blockers"])
+        self.assertIn("public installation remains blocked", ledger["cross_lane_blockers"])
+        self.assertIn("hosted surfaces remain blocked", ledger["cross_lane_blockers"])
+        self.assertIn("production positioning remains blocked", ledger["cross_lane_blockers"])
+        self.assertIn("public benchmark claims remain blocked", ledger["cross_lane_blockers"])
+        self.assertIn(
+            "this ledger does not refresh the reviewed public beta source state",
+            ledger["non_approvals"],
+        )
+        self.assertIn("this ledger does not approve package publication", ledger["non_approvals"])
+        self.assertIn("this ledger does not approve public installation", ledger["non_approvals"])
+
+    def test_schema_validation_covers_readiness_ledger(self) -> None:
+        schema = load_json(SCHEMA)
+        validate_examples = read(VALIDATE_EXAMPLES)
+        schemas_readme = read(SCHEMAS_README)
+
+        self.assertEqual(False, schema["additionalProperties"])
+        self.assertIn("current_main_refresh_candidate", schema["required"])
+        self.assertIn("package_publication_resolution_criteria", schema["required"])
+        self.assertEqual(14, schema["properties"]["cross_lane_blockers"]["minItems"])
+        self.assertEqual(12, schema["properties"]["non_approvals"]["minItems"])
+        self.assertIn("ethos-milestone-e-public-facing-readiness-ledger.schema.json", validate_examples)
+        self.assertIn("docs\" / \"milestone-e-public-facing-readiness-ledger.json", validate_examples)
+        self.assertIn("ethos-milestone-e-public-facing-readiness-ledger.schema.json", schemas_readme)
+        self.assertIn("docs/milestone-e-public-facing-readiness-ledger.json", schemas_readme)
+
+    def test_validation_record_indexes_commands_and_boundaries(self) -> None:
+        readme = read(VALIDATION_README)
+        record = normalized(RECORD)
+        ledger = load_json(LEDGER)
+
+        self.assertIn(RECORD.name, readme)
+        self.assertIn("public-facing readiness ledger validation", re.sub(r"\s+", " ", readme))
+        self.assertIn("Validated source HEAD before this record: `847e12d`", read(RECORD))
+        for gate in ledger["required_gates"]:
+            self.assertIn(gate, record)
+        for blocker in ledger["cross_lane_blockers"]:
+            self.assertIn(blocker, record)
+        self.assertIn("Ethos remains source-only pre-alpha", record)
+        self.assertIn("Public reports remain blocked", record)
+        self.assertIn("Public result wording remains blocked", record)
+
+    def test_docs_reference_public_facing_readiness_ledger(self) -> None:
+        for path in (PREP_SCOPE, ROADMAP, EXECUTION_STATUS, VALIDATION_README):
+            doc = normalized(path)
+
+            self.assertIn("docs/milestone-e-public-facing-readiness-ledger.json", doc, str(path))
+            self.assertIn("public-facing readiness ledger", doc, str(path))
+            self.assertIn("current-main refresh candidate", doc, str(path))
+            self.assertIn("package publication remains blocked", doc, str(path))
+
+    def test_make_and_ci_run_readiness_ledger_after_package_gap_ledger(self) -> None:
+        make_block = target_block("milestone-e-prep")
+        ci = read(CI_WORKFLOW)
+        package_gap_guard = "test_milestone_e_package_publication_pre_approval_gap_ledger.py"
+        ledger_guard = "test_milestone_e_public_facing_readiness_ledger.py"
+        command_guard = "test_milestone_e_validation_command_index.py"
+
+        for text, prefix in ((make_block, "$(PYTHON) .github/scripts/"), (ci, "python3 .github/scripts/")):
+            self.assertIn(prefix + ledger_guard, text)
+            self.assertEqual(1, text.count(prefix + ledger_guard))
+            self.assertLess(text.index(prefix + package_gap_guard), text.index(prefix + ledger_guard))
+            self.assertLess(text.index(prefix + ledger_guard), text.index(prefix + command_guard))
+
+    def test_ledger_avoids_scope_expansion_language_or_private_paths(self) -> None:
+        lower = json.dumps(load_json(LEDGER), sort_keys=True).lower()
+        record_lower = normalized(RECORD).lower()
+        raw = read(LEDGER) + read(RECORD)
+
+        for phrase in FORBIDDEN_SCOPE_EXPANSION:
+            self.assertNotIn(phrase, lower)
+            self.assertNotIn(phrase, record_lower)
+        self.assertNotIn("/Users/", raw)
+        self.assertNotIn("/private/tmp", raw)
+        self.assertNotIn("/private/var", raw)
+        self.assertNotIn("/var/folders", raw)
+        self.assertNotIn("saumildiwaker", raw)
+        self.assertNotIn("Desktop/Stuff", raw)
+        self.assertNotIn("project/repo/ethos", raw)
+        self.assertNotIn("docs/.roadmap.md.swp", raw)
+        self.assertNotIn("web/", raw)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/.github/scripts/test_milestone_e_schema_registry_alignment.py b/.github/scripts/test_milestone_e_schema_registry_alignment.py
@@ -94,6 +94,11 @@ def schema_name(self) -> str:
         "docs/milestone-e-package-publication-approval-prep.json",
         "package_publication_approval_prep",
     ),
+    RegistryEntry(
+        "schemas/ethos-milestone-e-public-facing-readiness-ledger.schema.json",
+        "docs/milestone-e-public-facing-readiness-ledger.json",
+        "public_facing_readiness_current_main_ledger",
+    ),
 )
 
 
@@ -155,7 +160,7 @@ def assert_tracked_file(self, path: str) -> None:
         self.assertEqual(0, result.returncode, path)
 
     def test_registry_has_exact_tracked_schema_artifact_pairs(self) -> None:
-        self.assertEqual(9, len(EXPECTED_REGISTRY))
+        self.assertEqual(10, len(EXPECTED_REGISTRY))
         self.assertEqual(
             len(EXPECTED_REGISTRY),
             len({(entry.schema, entry.artifact) for entry in EXPECTED_REGISTRY}),

diff --git a/.github/scripts/test_milestone_e_source_status_alignment.py b/.github/scripts/test_milestone_e_source_status_alignment.py
@@ -111,6 +111,10 @@ class SourceStatusArtifact:
         "docs/milestone-e-package-publication-approval-prep.json",
         "schemas/ethos-milestone-e-package-publication-approval-prep.schema.json",
     ),
+    SourceStatusArtifact(
+        "docs/milestone-e-public-facing-readiness-ledger.json",
+        "schemas/ethos-milestone-e-public-facing-readiness-ledger.schema.json",
+    ),
 )
 
 STATUS_VALIDATION_RECORDS = (

diff --git a/.github/scripts/test_milestone_e_validation_record_index.py b/.github/scripts/test_milestone_e_validation_record_index.py
@@ -258,6 +258,10 @@ class RecordCoverage:
         "milestone-e-package-publication-pre-approval-gap-ledger-validation-2026-06-21.md",
         "test_milestone_e_package_publication_pre_approval_gap_ledger.py",
     ),
+    RecordCoverage(
+        "milestone-e-public-facing-readiness-ledger-validation-2026-06-21.md",
+        "test_milestone_e_public_facing_readiness_ledger.py",
+    ),
     RecordCoverage(
         "milestone-e-validation-command-index-validation-2026-06-20.md",
         "test_milestone_e_validation_command_index_validation_record.py",
@@ -357,6 +361,7 @@ def test_index_guards_run_after_row_and_schema_records(self) -> None:
             "test_milestone_e_package_publication_decision_bundle_validation_record.py"
         )
         package_gap_ledger_guard = "test_milestone_e_package_publication_pre_approval_gap_ledger.py"
+        readiness_guard = "test_milestone_e_public_facing_readiness_ledger.py"
         command_guard = "test_milestone_e_validation_command_index_validation_record.py"
         index_guard = "test_milestone_e_validation_record_index.py"
         index_record_guard = "test_milestone_e_validation_record_index_validation_record.py"
@@ -413,8 +418,9 @@ def test_index_guards_run_after_row_and_schema_records(self) -> None:
                 text.index(prefix + package_decision_bundle_guard),
                 text.index(prefix + package_gap_ledger_guard),
             )
-            self.assertLess(text.index(prefix + package_gap_ledger_guard), text.index(prefix + command_guard))
-            self.assertLess(text.index(prefix + package_gap_ledger_guard), text.index(prefix + index_guard))
+            self.assertLess(text.index(prefix + package_gap_ledger_guard), text.index(prefix + readiness_guard))
+            self.assertLess(text.index(prefix + readiness_guard), text.index(prefix + command_guard))
+            self.assertLess(text.index(prefix + readiness_guard), text.index(prefix + index_guard))
             self.assertLess(text.index(prefix + package_manifest_activation_guard), text.index(prefix + command_guard))
             self.assertLess(text.index(prefix + package_manifest_activation_guard), text.index(prefix + index_guard))
             self.assertLess(text.index(prefix + package_tag_guard), text.index(prefix + command_guard))

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -226,6 +226,8 @@ jobs:
         run: python3 .github/scripts/test_milestone_e_package_publication_decision_bundle_validation_record.py
       - name: Milestone E package publication pre-approval gap ledger tests
         run: python3 .github/scripts/test_milestone_e_package_publication_pre_approval_gap_ledger.py
+      - name: Milestone E public-facing readiness ledger tests
+        run: python3 .github/scripts/test_milestone_e_public_facing_readiness_ledger.py
       - name: Milestone E validation-command index tests
         run: python3 .github/scripts/test_milestone_e_validation_command_index.py
       - name: Milestone E validation-command index validation record tests

diff --git a/Makefile b/Makefile
@@ -220,6 +220,7 @@ milestone-e-prep:
 	$(PYTHON) .github/scripts/test_milestone_e_package_publication_registry_assembly_activation_prep.py
 	$(PYTHON) .github/scripts/test_milestone_e_package_publication_decision_bundle_validation_record.py
 	$(PYTHON) .github/scripts/test_milestone_e_package_publication_pre_approval_gap_ledger.py
+	$(PYTHON) .github/scripts/test_milestone_e_public_facing_readiness_ledger.py
 	$(PYTHON) .github/scripts/test_milestone_e_validation_command_index.py
 	$(PYTHON) .github/scripts/test_milestone_e_validation_command_index_validation_record.py
 	$(PYTHON) .github/scripts/test_milestone_e_validation_record_index.py