diff --git a/README.md b/README.md index 4301954..1e82fbe 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ Release drift note: current `main` is ahead of `v0.6.0` and contains the five-de - [`docs/reviewer-pack.md`](docs/reviewer-pack.md): demo matrix, artifact contract, and v1 readiness gate - [`docs/v1-contract-freeze.md`](docs/v1-contract-freeze.md): v1.0 five-demo contract freeze and release drift note - [`docs/v1-readiness-gate.md`](docs/v1-readiness-gate.md): fixed inputs, fixed outputs, schema validation, artifact regeneration, and test pass requirements +- [`docs/release-v1.0.md`](docs/release-v1.0.md): draft v1.0 reviewer-contract release notes and explicit non-SIEM boundary - [`docs/v0.6-to-v1-artifact-diff.md`](docs/v0.6-to-v1-artifact-diff.md): fourth-to-fifth-demo artifact contract and compatibility diff - [`docs/evidence-pipeline-contract.md`](docs/evidence-pipeline-contract.md): JSON schema contracts for reviewer-facing evidence artifacts - [`docs/reviewer-artifact-diff.md`](docs/reviewer-artifact-diff.md): release artifact diff contract for reviewer-facing outputs diff --git a/docs/README.md b/docs/README.md index bebd256..989609b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,6 +9,7 @@ This directory separates the current reviewer route from supporting design notes - [`reviewer-brief.md`](reviewer-brief.md): short problem, value, evidence, and boundary summary - [`v1-contract-freeze.md`](v1-contract-freeze.md): v1.0 five-demo contract freeze and release drift note - [`v1-readiness-gate.md`](v1-readiness-gate.md): fixed inputs, fixed outputs, schema validation, artifact regeneration, and test pass requirements +- [`release-v1.0.md`](release-v1.0.md): draft reviewer-contract release notes with the explicit non-SIEM boundary - [`v0.6-to-v1-artifact-diff.md`](v0.6-to-v1-artifact-diff.md): additive artifact contract and compatibility diff from the fourth demo to the fifth - [`evidence-pipeline-contract.md`](evidence-pipeline-contract.md): JSON schema contracts for reviewer-facing evidence artifacts - [`reviewer-artifact-diff.md`](reviewer-artifact-diff.md): release diff contract for reviewer-facing artifact changes diff --git a/docs/release-v1.0.md b/docs/release-v1.0.md new file mode 100644 index 0000000..7b7a802 --- /dev/null +++ b/docs/release-v1.0.md @@ -0,0 +1,80 @@ +# v1.0 Reviewer Contract Release Notes (Draft) + +**This is a reviewer-contract release, not a production SIEM.** + +Release status: Draft. This document does not create a `v1.0` tag or GitHub +release. Final publication remains gated by +[`docs/v1-readiness-gate.md`](v1-readiness-gate.md). + +## Release Scope + +v1.0 freezes the current five-demo reviewer contract: + +1. `telemetry-window-demo` +2. `ai-assisted-detection-demo` +3. `rule-evaluation-and-dedup-demo` +4. `config-change-investigation-demo` +5. `cloud-iam-change-investigation-demo` + +Demo expansion is closed. The release consolidates the current local, +file-based workflows instead of adding another demo or production platform +surface. + +## Reviewer Contract + +The v1.0 release contract requires: + +- fixed synthetic inputs for the five demos +- fixed reviewer-visible output paths +- JSON Schema validation for contracted evidence artifacts +- reproducible committed artifacts +- a passing full test suite + +See [`docs/v1-contract-freeze.md`](v1-contract-freeze.md) for the freeze scope +and [`docs/evidence-pipeline-contract.md`](evidence-pipeline-contract.md) for the +schema matrix. + +## Artifact Compatibility + +Relative to `v0.6.0`: + +- the fourth-demo artifact paths and committed contents remain unchanged +- the fifth demo adds four reviewer-visible artifact paths under its own demo + directory +- the overall artifact compatibility label is `additive-compatible` +- the two demo-local `investigation_summary.json` files use separate schemas + and intentionally different root shapes + +See [`docs/v0.6-to-v1-artifact-diff.md`](v0.6-to-v1-artifact-diff.md) for the +field-level and semantic diff. Future release diffs follow +[`docs/reviewer-artifact-diff.md`](reviewer-artifact-diff.md). + +## Validation Snapshot + +Current draft validation snapshot; refresh these results from the release +candidate commit before publication: + +```bash +python scripts/regenerate_artifacts.py --check +python -m pytest tests/test_evidence_pipeline_schemas.py +python -m pytest +``` + +- Artifact regeneration: passed; `23` committed artifacts matched and `6` + visual snapshots completed smoke checks. +- Schema validation: passed; `3 passed`. +- Full test suite: passed; `175 passed`. + +If any required command fails, v1.0 is not ready. + +## Boundaries + +- Synthetic, local, file-based inputs only. +- No live AWS account or production telemetry source. +- No real account ID or credentials. +- No production detection claim or operational alerting claim. +- No real-time ingestion, dashboard, alert routing, or case-management service. +- No autonomous response. +- No final incident verdict. + +This release does not claim production readiness. diff --git a/docs/reviewer-pack.md b/docs/reviewer-pack.md index 39ebfbb..bc2e9f0 100644 --- a/docs/reviewer-pack.md +++ b/docs/reviewer-pack.md @@ -108,6 +108,7 @@ Use the same Python interpreter for install, tests, and demo commands. - [`docs/reviewer-path.md`](reviewer-path.md): demo choice by review question - [`docs/v1-contract-freeze.md`](v1-contract-freeze.md): v1.0 five-demo contract freeze and release drift note - [`docs/v1-readiness-gate.md`](v1-readiness-gate.md): v1.0 readiness gate for fixed inputs, fixed outputs, schema validation, artifact regeneration, and test pass +- [`docs/release-v1.0.md`](release-v1.0.md): draft v1.0 reviewer-contract release notes and explicit non-SIEM boundary - [`docs/v0.6-to-v1-artifact-diff.md`](v0.6-to-v1-artifact-diff.md): fourth-to-fifth-demo artifact contract and compatibility diff - [`docs/evidence-pipeline-contract.md`](evidence-pipeline-contract.md): JSON schema contracts for five-demo evidence artifacts - [`docs/reviewer-artifact-diff.md`](reviewer-artifact-diff.md): release diff contract for reviewer-facing artifact changes diff --git a/docs/v1-contract-freeze.md b/docs/v1-contract-freeze.md index 7321f25..a5d7c9f 100644 --- a/docs/v1-contract-freeze.md +++ b/docs/v1-contract-freeze.md @@ -79,7 +79,12 @@ committed sample outputs in the same change. ## Release Notes Requirement -The v1.0 release notes should include: +Use [`docs/release-v1.0.md`](release-v1.0.md) as the maintained v1.0 release-note +draft. The final release notes must state exactly: + +> This is a reviewer-contract release, not a production SIEM. + +The v1.0 release notes should also include: - a `no new demo` statement - the five-demo matrix diff --git a/docs/v1-readiness-gate.md b/docs/v1-readiness-gate.md index 653bc24..11dd5bc 100644 --- a/docs/v1-readiness-gate.md +++ b/docs/v1-readiness-gate.md @@ -85,4 +85,4 @@ python -m pytest tests/test_evidence_pipeline_schemas.py python -m pytest ``` -The v1.0 release notes should include the command results and should state whether the reviewer-facing artifact diff is `no-artifact-change` or documents intentional compatibility changes. +The v1.0 release notes in [`docs/release-v1.0.md`](release-v1.0.md) should include the command results, should state whether the reviewer-facing artifact diff is `no-artifact-change` or documents intentional compatibility changes, and must retain the exact boundary statement: "This is a reviewer-contract release, not a production SIEM." diff --git a/tests/test_reviewer_docs.py b/tests/test_reviewer_docs.py index 0f327ff..1cdc1e3 100644 --- a/tests/test_reviewer_docs.py +++ b/tests/test_reviewer_docs.py @@ -156,6 +156,7 @@ def test_docs_index_separates_current_route_from_history() -> None: "reviewer-brief.md", "v1-contract-freeze.md", "v1-readiness-gate.md", + "release-v1.0.md", "v0.6-to-v1-artifact-diff.md", "evidence-pipeline-contract.md", "reviewer-artifact-diff.md", @@ -194,6 +195,7 @@ def test_top_level_reviewer_pack_covers_matrix_and_artifact_contract() -> None: assert "[`docs/reviewer-path.md`](reviewer-path.md)" in reviewer_pack assert "[`docs/v1-contract-freeze.md`](v1-contract-freeze.md)" in reviewer_pack assert "[`docs/v1-readiness-gate.md`](v1-readiness-gate.md)" in reviewer_pack + assert "[`docs/release-v1.0.md`](release-v1.0.md)" in reviewer_pack assert "[`docs/v0.6-to-v1-artifact-diff.md`](v0.6-to-v1-artifact-diff.md)" in reviewer_pack assert "[`docs/reviewer-artifact-diff.md`](reviewer-artifact-diff.md)" in reviewer_pack assert "[`docs/vocabulary.md`](vocabulary.md)" in reviewer_pack @@ -434,6 +436,45 @@ def test_v06_to_v1_artifact_diff_documents_additive_fifth_demo_contract() -> Non assert "v0.6-to-v1-artifact-diff.md" in text +def test_v1_release_note_states_reviewer_contract_boundary() -> None: + release_note = _read_repo_file("docs/release-v1.0.md") + docs_index = _read_repo_file("docs/README.md") + reviewer_pack = _read_repo_file("docs/reviewer-pack.md") + readme = _read_repo_file("README.md") + freeze_doc = _read_repo_file("docs/v1-contract-freeze.md") + readiness_gate = _read_repo_file("docs/v1-readiness-gate.md") + + boundary = "This is a reviewer-contract release, not a production SIEM." + + assert "# v1.0 Reviewer Contract Release Notes (Draft)" in release_note + assert boundary in release_note + assert "This document does not create a `v1.0` tag or GitHub" in release_note + assert "## Release Scope" in release_note + assert "## Reviewer Contract" in release_note + assert "## Artifact Compatibility" in release_note + assert "## Validation Snapshot" in release_note + assert "## Boundaries" in release_note + assert "python scripts/regenerate_artifacts.py --check" in release_note + assert "python -m pytest tests/test_evidence_pipeline_schemas.py" in release_note + assert "python -m pytest" in release_note + assert "This release does not claim production readiness." in release_note + + for demo_name in [ + "telemetry-window-demo", + "ai-assisted-detection-demo", + "rule-evaluation-and-dedup-demo", + "config-change-investigation-demo", + "cloud-iam-change-investigation-demo", + ]: + assert f"`{demo_name}`" in release_note + + for text in [docs_index, reviewer_pack, readme, freeze_doc, readiness_gate]: + assert "release-v1.0.md" in text + + assert boundary in freeze_doc + assert boundary in readiness_gate + + def test_bounded_correlation_boundaries_are_documented() -> None: architecture = _read_repo_file("docs/architecture.md") reviewer_pack = _read_repo_file("docs/reviewer-pack.md")