from __future__ import annotations
import re
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
REQUIRED = (
"README.md",
"AGENTS.md",
"LICENSE",
"SECURITY.md",
"CONTRIBUTING.md",
"CODE_OF_CONDUCT.md",
"CHANGELOG.md",
"docs/ARCHITECTURE.md",
"docs/ASSESSOR_HANDOFF.md",
"docs/EXTERNAL_ASSESSMENT.md",
"docs/AUTHORITY_PROTOCOL.md",
"docs/E2E_TESTING.md",
"docs/EVALUATION_PRODUCT_DECISION.md",
"docs/EVALUATION_PRODUCTISATION_DECISION.md",
"docs/RC2_EVALUATION_RELEASE_DECISION.md",
"docs/RC2_RELEASE_PRESENTATION_REVIEW.md",
"docs/RC2_FREEZE_RECORD.md",
"docs/RC3_EVALUATION_RELEASE_DECISION.md",
"docs/RC3_RELEASE_PRESENTATION_REVIEW.md",
"docs/RC3_FREEZE_RECORD.md",
"docs/EVALUATION_CLI.md",
"docs/EVALUATION_LIFECYCLE.md",
"docs/INTEGRATION_CONTRACT.md",
"docs/REDIS_INTEGRATION.md",
"docs/POSTGRESQL_INTEGRATION.md",
"docs/HTTP_JSON_INTEGRATION.md",
"docs/OPERATOR_DIAGNOSTICS.md",
"docs/PRIVATE_BUNDLE.md",
"docs/CANDIDATE_SIGNING.md",
"docs/BUILD_PROVENANCE.md",
"docs/ADVERSARIAL_COVERAGE.md",
"docs/SUSTAINED_ADVERSARIAL_LOAD.md",
"docs/OBSERVATION_QUORUM.md",
"docs/KUBERNETES_REAL_CLUSTER.md",
"docs/IMPLEMENTATION_PLAN.md",
"docs/PUBLIC_OPENING_DECISION.md",
"docs/HISTORY_PRIVACY_MIGRATION.md",
"docs/GITHUB_PAGES.md",
"docs/DILIGENCE_REFRESH_2026-08-08.md",
"assets/brand/BRAND_ASSET_MANIFEST.json",
"scripts/build-brand-assets.py",
"scripts/validate-brand.py",
"scripts/build-pages-site.py",
"scripts/validate-pages-site.py",
"scripts/validate-hosted-workflows.py",
".github/workflows/ci.yml",
".github/workflows/pages.yml",
".github/workflows/release.yml",
"site/index.html",
"site/styles.css",
"site/assets/telosieve-architecture.svg",
"scripts/validate-release-presentation.py",
"docs/RELEASE.md",
"docs/REQUIREMENTS_TRACEABILITY.md",
"docs/SUPPLY_CHAIN.md",
"docs/THREAT_MODEL.md",
"docs/VALIDATION.md",
"docs/WITNESS_OPERATOR_HANDOFF.md",
"assessment/manifest.json",
"assessment/witness-operator-request.json",
"evaluation/contract.json",
"evaluation/adversarial-coverage.json",
"evaluation/config.example.json",
"scripts/evaluation-lifecycle.py",
"scripts/run-evaluation-lifecycle-qualification.py",
"scripts/evaluation-diagnostics.py",
"scripts/validate-adversarial-coverage.py",
"scripts/run-sustained-adversarial-load.py",
"scripts/run-diagnostics-qualification.py",
"scripts/build-private-bundle.py",
"scripts/run-private-bundle-qualification.py",
"scripts/run-reproducible-build-qualification.py",
"scripts/run-kubernetes-real-cluster.py",
)
LINK = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
PLACEHOLDER = re.compile(r"\b(?:TODO|FIXME|REPLACE_WITH)\b")
def main() -> int:
errors: list[str] = []
for relative in REQUIRED:
if not (ROOT / relative).is_file():
errors.append(f"missing required file: {relative}")
for path in sorted(ROOT.glob("**/*.md")):
if "target" in path.parts:
continue
relative = path.relative_to(ROOT)
text = path.read_text(encoding="utf-8")
if not text.startswith("# "):
errors.append(f"missing H1: {relative}")
if PLACEHOLDER.search(text):
errors.append(f"placeholder marker: {relative}")
if re.search(r"[ \t]+$", text, re.MULTILINE):
errors.append(f"trailing whitespace: {relative}")
for link in LINK.findall(text):
if link.startswith(("http://", "https://", "#", "mailto:")):
continue
target = (path.parent / link.split("#", 1)[0]).resolve()
if not target.exists():
errors.append(f"broken local link in {relative}: {link}")
plan = (ROOT / "docs/IMPLEMENTATION_PLAN.md").read_text(encoding="utf-8")
if "- [ ] " not in plan:
errors.append("implementation plan has no unchecked work")
release = (ROOT / "docs/RELEASE.md").read_text(encoding="utf-8").lower()
for phrase in ("local ci", "github actions", "complete local gate"):
if phrase not in release:
errors.append(f"release policy missing required phrase: {phrase}")
workflows = ROOT / ".github/workflows"
for name in ("ci.yml", "pages.yml", "release.yml"):
if not (workflows / name).is_file():
errors.append(f"required public workflow is missing: {name}")
for error in errors:
print(f"project-validation: {error}", file=sys.stderr)
if errors:
return 1
print("project-validation: passed")
return 0
if __name__ == "__main__":
raise SystemExit(main())