From 40b17b00c2d3821642b28defc1fc395f41fd289e Mon Sep 17 00:00:00 2001 From: stacknil Date: Mon, 15 Jun 2026 11:57:44 +0800 Subject: [PATCH] docs(review): align v1 contract stabilization language --- README.md | 7 ++++--- docs/README.md | 2 +- docs/architecture.md | 2 +- docs/reviewer-brief.md | 2 +- docs/reviewer-pack.md | 4 ++-- tests/test_reviewer_docs.py | 19 +++++++++++++++++++ 6 files changed, 28 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 356aab8..9561fa8 100644 --- a/README.md +++ b/README.md @@ -166,18 +166,19 @@ Cooldown behavior: - [`docs/architecture.md`](docs/architecture.md) diagrams the local file-based detection workflow - [`docs/event-time-model.md`](docs/event-time-model.md) defines event, observed, window, and artifact time semantics - [`docs/sample-output.md`](docs/sample-output.md) summarizes the committed sample artifacts -- [`docs/roadmap.md`](docs/roadmap.md) sketches the v0.7 / v1.0 consolidation direction +- [`docs/roadmap.md`](docs/roadmap.md) defines the v1 reviewer contract stabilization phase - [`data/processed/summary.json`](data/processed/summary.json) captures the default run in machine-readable form - [`data/processed/richer_sample/summary.json`](data/processed/richer_sample/summary.json) captures the richer scenario pack - [`tests/`](tests/) keeps regression coverage close to the CLI behavior and windowing logic -## v0.7 / v1.0 Direction +## v1 Reviewer Contract Stabilization +- demo expansion is closed - stabilize the five-demo matrix and avoid broad platform expansion - freeze reviewer-visible artifact names unless a rename is intentionally coordinated across docs, tests, and sample outputs - use [`docs/reviewer-pack.md`](docs/reviewer-pack.md) and [`docs/architecture.md`](docs/architecture.md) as the consolidation entrypoints - use the [`v1 readiness gate`](docs/reviewer-pack.md#v1-readiness-gate) before treating the repo as consolidated -- avoid additional demo expansion before v1-style consolidation +- avoid additional demo expansion during v1 reviewer contract stabilization ## Scope diff --git a/docs/README.md b/docs/README.md index 4ea4175..2fd1259 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ This directory separates the current reviewer route from supporting design notes - [`reviewer-path.md`](reviewer-path.md): choose a demo by review question - [`reviewer-brief.md`](reviewer-brief.md): short problem, value, evidence, and boundary summary - [`architecture.md`](architecture.md): local file-based workflow diagram -- [`roadmap.md`](roadmap.md): v0.7 / v1.0 consolidation direction +- [`roadmap.md`](roadmap.md): v1 reviewer contract stabilization phase ## Supporting docs diff --git a/docs/architecture.md b/docs/architecture.md index ce66791..92e7fc4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -33,7 +33,7 @@ flowchart TD - Detection decisions stay deterministic and inspectable. - The AI-assisted demo is limited to bounded JSON-only case drafting. - Artifacts are file-based and suitable for local regeneration or GitHub review. -- Artifact names are reviewer-visible contracts during the v0.7 / v1.0 consolidation path. +- Artifact names are reviewer-visible contracts during the v1 reviewer contract stabilization phase. - The repository does not provide production monitoring, real-time ingestion, dashboards, alert routing, case management, autonomous response, or final incident verdicts. ## Demo Boundaries diff --git a/docs/reviewer-brief.md b/docs/reviewer-brief.md index 24dad67..21678fd 100644 --- a/docs/reviewer-brief.md +++ b/docs/reviewer-brief.md @@ -73,4 +73,4 @@ The other demos emit reviewer-facing artifacts such as `dedup_report.md`, `inves ## Next milestone -Consolidate the current reviewer path for v0.7 / v1.0: keep the demo matrix stable, freeze reviewer-visible artifact names, maintain one top-level reviewer pack, and keep the architecture diagram aligned with actual CLI and artifact behavior. +Demo expansion is closed. The next phase is v1 reviewer contract stabilization: keep the demo matrix stable, freeze reviewer-visible artifact names, maintain one top-level reviewer pack, and keep the architecture diagram aligned with actual CLI and artifact behavior. diff --git a/docs/reviewer-pack.md b/docs/reviewer-pack.md index 83df660..43b916d 100644 --- a/docs/reviewer-pack.md +++ b/docs/reviewer-pack.md @@ -30,7 +30,7 @@ The important shape is: ## Artifact Naming Contract -The current artifact names are reviewer-facing contracts for the v0.7 / v1.0 consolidation path. +The current artifact names are reviewer-facing contracts for the v1 reviewer contract stabilization phase. - Keep the demo matrix stable unless a demo is intentionally retired. - Prefer additive artifacts over renaming existing reviewer-visible outputs. @@ -83,7 +83,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/architecture.md`](architecture.md): local file-based workflow diagram - [`docs/sample-output.md`](sample-output.md): committed output counts and sample artifacts -- [`docs/roadmap.md`](roadmap.md): v0.7 / v1.0 consolidation direction +- [`docs/roadmap.md`](roadmap.md): v1 reviewer contract stabilization phase - [`tests/test_reviewer_docs.py`](../tests/test_reviewer_docs.py): regression checks for reviewer-facing docs ## Boundaries diff --git a/tests/test_reviewer_docs.py b/tests/test_reviewer_docs.py index 98bb0f6..b2adf5e 100644 --- a/tests/test_reviewer_docs.py +++ b/tests/test_reviewer_docs.py @@ -219,6 +219,25 @@ def test_reviewer_pack_defines_v1_readiness_gate() -> None: assert "[`v1 readiness gate`](docs/reviewer-pack.md#v1-readiness-gate)" in readme +def test_current_docs_use_v1_contract_stabilization_language() -> None: + current_docs = { + "README.md": _read_repo_file("README.md"), + "docs/README.md": _read_repo_file("docs/README.md"), + "docs/reviewer-pack.md": _read_repo_file("docs/reviewer-pack.md"), + "docs/reviewer-brief.md": _read_repo_file("docs/reviewer-brief.md"), + "docs/architecture.md": _read_repo_file("docs/architecture.md"), + "docs/roadmap.md": _read_repo_file("docs/roadmap.md"), + } + + assert "Demo expansion is closed." in current_docs["docs/roadmap.md"] + assert "Next phase: v1 reviewer contract stabilization." in current_docs["docs/roadmap.md"] + assert "## v1 Reviewer Contract Stabilization" in current_docs["README.md"] + + for path, text in current_docs.items(): + assert "v1 reviewer contract stabilization" in text, path + assert "v0.7 / v1.0" not in text, path + + def test_architecture_doc_keeps_local_file_based_boundaries() -> None: architecture = _read_repo_file("docs/architecture.md")