Document release readiness and security posture

Author: code5717

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Added an installed `a7` CLI entrypoint via `pyproject.toml`.
   - Added `scripts/build_examples.py` to build debug/release native artifacts for Zig and C example outputs and verify each binary against golden fixtures.
   - Added `RELEASE.md` with local release gates, artifact layout, tagging steps, and security caveats.
+  - Added `SECURITY.md` and `RELEASE_READINESS_REVIEW.md` to document trust boundaries, residual release risks, and verification evidence.
   - Added release-tooling pytest coverage for the installed CLI and debug build script.
   - Added a GitHub Actions CI workflow for Python, backend, package, docs, and artifact checks.
 

README.md

@@ -158,6 +158,8 @@ All AST traversals are iterative with no recursion. The pipeline works with Pyth
 - Documentation website: `https://airbus5717.github.io/a7-py/`
 - `docs/SPEC.md` - Language specification
 - `RELEASE.md` - Release/debug build checklist
+- `SECURITY.md` - Security policy and trust boundary
+- `RELEASE_READINESS_REVIEW.md` - Current release-readiness audit
 - `examples/` - 36 sample programs
 - `MISSING_FEATURES.md` - Feature status and roadmap
 - `CHANGELOG.md` - Change history

RELEASE_READINESS_REVIEW.md

@@ -0,0 +1,64 @@
+# Release Readiness Review
+
+Date: 2026-05-07
+
+## Result
+
+The repository is substantially more release-ready than before this pass:
+
+- installable `a7` CLI entrypoint
+- compatibility `main.py` wrapper
+- debug and release artifact builder for Zig and C
+- committed docs lockfile for deterministic docs builds
+- CI workflow for tests, backends, artifacts, package build, and docs build
+- release checklist, security policy, and updated status docs
+
+This is not a claim that the implementation is free of all bugs or
+vulnerabilities. For a compiler and native-code build pipeline, that standard is
+not factually provable from local tests alone.
+
+## Evidence Checked
+
+- `uv run a7 --help`
+- `PYTHONPATH=. uv run pytest test/test_release_tooling.py -q`
+- `uv run python scripts/build_examples.py --profile debug --backend both --clean`
+- `uv run python scripts/build_examples.py --profile release --backend both --clean`
+- `./run_all_tests.sh`
+- `uv build`
+- `cd site && npm run build`
+- built wheel installed into a temporary virtualenv and invoked as `a7`
+- `git diff --check`
+
+## Fixed In This Pass
+
+- Package metadata now has a real description and a console script.
+- Runtime-only test dependency moved into the dev dependency group.
+- `main.py` now delegates to `src.cli:main`.
+- `scripts/build_examples.py` builds and verifies debug/release artifacts for
+  both backends.
+- `run_all_tests.sh` now covers C backend tests, C E2E, error-stage audit,
+  debug/release artifact builds, docs style, and full pytest.
+- GitHub CI now runs Python tests, backend verifiers, artifact builds, package
+  build, docs style, docs lint, and docs build.
+- GitHub Pages deploy now uses `npm ci` with `site/package-lock.json`.
+- README, SPEC, release docs, status docs, and agent docs describe the same
+  release commands.
+
+## Residual Risks
+
+- `a7-py` is not a sandbox. Do not compile or run untrusted A7 source.
+- `fall` is parsed but not semantically validated or lowered.
+- Full ownership/lifetime safety is not implemented.
+- Import/module loading still has fail-open behavior that should be hardened.
+- Backend parity is verified for examples, not all possible source programs.
+- Tag-based publishing is not wired.
+- Automated supply-chain scanning is not configured.
+
+## Recommended Next Pass
+
+1. Make import/module loading fail closed with source-language diagnostics.
+2. Replace Zig backend `@compileError("unsupported")` fallbacks with compiler
+   codegen errors.
+3. Add tag-based release workflow after choosing the package publishing target.
+4. Add dependency and secret scanning to CI.
+5. Expand differential backend tests beyond examples.

SECURITY.md

@@ -0,0 +1,46 @@
+# Security Policy
+
+## Supported Versions
+
+`a7-py` is pre-1.0. Security fixes are made on `master` unless a release branch
+is created later.
+
+## Trust Boundary
+
+`a7-py` is not a sandbox.
+
+The compiler reads A7 source, emits Zig or C, and the verification scripts build
+and execute native binaries. Compiled A7 programs can do anything the generated
+program and host runtime allow. Only compile and run A7 source you trust.
+
+## Local Verification
+
+Before release or broad testing, run:
+
+```bash
+./run_all_tests.sh
+uv build
+cd site && npm run build
+```
+
+The full gate includes parser/tokenizer tests, semantic tests, Zig and C backend
+tests, example runtime verification, debug/release artifact builds, error-stage
+checks, docs style checks, and full pytest.
+
+## Known Security-Relevant Limitations
+
+- No sandboxing for compiled programs.
+- No ownership or borrow-style lifetime model yet.
+- Import/module loading still needs stronger fail-closed behavior.
+- C and Zig backend parity checks exist for examples but are not a proof for all
+  possible programs.
+- Tag-based package publishing is not configured yet.
+
+These limitations are tracked in `MISSING_FEATURES.md`, `TODO.md`, and
+`RELEASE.md`.
+
+## Reporting
+
+Open a private security advisory or contact the repository owner before opening
+public issues for exploitable crashes, unsafe generated code, or release
+pipeline compromise.

scripts/check_docs_style.py

@@ -44,7 +44,13 @@ class Finding:
 def iter_doc_paths(root: Path) -> list[Path]:
     paths: set[Path] = set()
 
-    for fixed in [root / "README.md", root / "RELEASE.md", root / "site" / "README.md"]:
+    for fixed in [
+        root / "README.md",
+        root / "RELEASE.md",
+        root / "SECURITY.md",
+        root / "RELEASE_READINESS_REVIEW.md",
+        root / "site" / "README.md",
+    ]:
         if fixed.exists():
             paths.add(fixed)