diff --git a/README.md b/README.md index dee4e322..c94c65e7 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ The Enterprise Lab Cockpit provides controlled lab evidence, local reproducibili - Source-name guard allowlist review checklist: [`docs/SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md`](docs/SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md) gives reviewers docs/test-only allowlist candidate review criteria before any allowlist file or implementation without adding source scanning, report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, class renames, package moves, ArchUnit, Maven build changes, or enforcement claims. - Source-name guard allowlist sample plan: [`docs/SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md`](docs/SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md) gives reviewers docs/test-only static examples for future allowlist entry shapes before any allowlist file or implementation without adding source scanning, report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, class renames, package moves, ArchUnit, Maven build changes, or enforcement claims. - Source-name guard allowlist lifecycle plan: [`docs/SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md`](docs/SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md) gives reviewers docs/test-only future allowlist lifecycle rules before any allowlist file or implementation without adding source scanning, report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, class renames, package moves, ArchUnit, Maven build changes, or enforcement claims. +- Source-name guard allowlist exit criteria plan: [`docs/SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md`](docs/SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md) gives reviewers docs/test-only exit criteria for the allowlist planning lane before any allowlist file or implementation without adding source scanning, report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, class renames, package moves, ArchUnit, Maven build changes, or enforcement claims. - Decision Vector contract: [`docs/ENTERPRISE_LAB_DECISION_VECTOR.md`](docs/ENTERPRISE_LAB_DECISION_VECTOR.md); read-only Dominant Factor Analysis lane: [`docs/ENTERPRISE_LAB_DOMINANT_FACTOR_ANALYSIS.md`](docs/ENTERPRISE_LAB_DOMINANT_FACTOR_ANALYSIS.md); read-only Decision Delta Analysis lane: [`docs/ENTERPRISE_LAB_DECISION_DELTA_ANALYSIS.md`](docs/ENTERPRISE_LAB_DECISION_DELTA_ANALYSIS.md); read-only Decision Replay Snapshot lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_SNAPSHOT.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_SNAPSHOT.md); read-only Decision Replay Reconstruction Trace lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_RECONSTRUCTION_TRACE.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_RECONSTRUCTION_TRACE.md); read-only Decision Replay Capsule lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_CAPSULE.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_CAPSULE.md); read-only Decision Replay Readiness Checklist lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_READINESS_CHECKLIST.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_READINESS_CHECKLIST.md); read-only Decision Replay Evidence Source Map lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_SOURCE_MAP.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_SOURCE_MAP.md); read-only Decision Replay Evidence Boundary Summary lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_BOUNDARY_SUMMARY.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_BOUNDARY_SUMMARY.md); read-only Decision Replay Evidence Field Inventory lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_FIELD_INVENTORY.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_FIELD_INVENTORY.md); read-only Decision Evidence Null-Safety Summary lane: [`docs/ENTERPRISE_LAB_DECISION_EVIDENCE_NULL_SAFETY_SUMMARY.md`](docs/ENTERPRISE_LAB_DECISION_EVIDENCE_NULL_SAFETY_SUMMARY.md); read-only Decision Evidence Status Rollup lane: [`docs/ENTERPRISE_LAB_DECISION_EVIDENCE_STATUS_ROLLUP.md`](docs/ENTERPRISE_LAB_DECISION_EVIDENCE_STATUS_ROLLUP.md); read-only Decision Replay Evidence Lane Navigation Summary lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_LANE_NAVIGATION_SUMMARY.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_LANE_NAVIGATION_SUMMARY.md); read-only Decision Replay Evidence Lane Dependency Map lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_LANE_DEPENDENCY_MAP.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_LANE_DEPENDENCY_MAP.md); read-only Decision Replay Evidence Lane Reference Index lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_LANE_REFERENCE_INDEX.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_LANE_REFERENCE_INDEX.md); read-only Decision Replay Evidence Lane Dependency Summary lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_LANE_DEPENDENCY_SUMMARY.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_LANE_DEPENDENCY_SUMMARY.md); read-only Decision Replay Evidence Lane Consistency Summary lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_LANE_CONSISTENCY_SUMMARY.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_LANE_CONSISTENCY_SUMMARY.md); read-only Decision Replay Evidence Reviewer Snapshot lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_REVIEWER_SNAPSHOT.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_REVIEWER_SNAPSHOT.md); read-only Decision Replay Evidence Reviewer Guidance lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_REVIEWER_GUIDANCE.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_REVIEWER_GUIDANCE.md); read-only Decision Replay Evidence Reviewer Handoff Summary lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_REVIEWER_HANDOFF_SUMMARY.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_REVIEWER_HANDOFF_SUMMARY.md); read-only Decision Replay Evidence Reviewer Closure Summary lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_REVIEWER_CLOSURE_SUMMARY.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_REVIEWER_CLOSURE_SUMMARY.md); read-only Decision Replay Evidence Closure Rollup lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_CLOSURE_ROLLUP.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_CLOSURE_ROLLUP.md); read-only Decision Replay Evidence Closure Checklist lane: [`docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_CLOSURE_CHECKLIST.md`](docs/ENTERPRISE_LAB_DECISION_REPLAY_EVIDENCE_CLOSURE_CHECKLIST.md). LoadBalancerPro is becoming **LoadBalancerPro Enterprise Lab**: a Java 17 / Spring Boot lab for adaptive-routing scenarios, deterministic replay, LASE shadow/influence comparison, policy gates, scorecards, evidence export, SRE walkthroughs, and a carefully bounded Production Gateway Candidate track. diff --git a/docs/ENTERPRISE_READINESS_AUDIT.md b/docs/ENTERPRISE_READINESS_AUDIT.md index 13b46ee3..2a6102b2 100644 --- a/docs/ENTERPRISE_READINESS_AUDIT.md +++ b/docs/ENTERPRISE_READINESS_AUDIT.md @@ -98,6 +98,7 @@ The transition is mostly complete at the current reviewer-entry level: - `docs/SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md` records a docs/test-only allowlist review checklist for evaluating future source-name guard allowlist candidates without adding allowlist files, source scanning, dry-run report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, source-name guard enforcement, runtime naming enforcement, ArchUnit or package-boundary tooling, Maven build changes, routing/scoring/strategy/proxy behavior changes, or claiming production readiness. - `docs/SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md` records a docs/test-only allowlist sample plan with static examples for future source-name guard allowlist entries without adding allowlist files, source scanning, dry-run report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, source-name guard enforcement, runtime naming enforcement, ArchUnit or package-boundary tooling, Maven build changes, routing/scoring/strategy/proxy behavior changes, or claiming production readiness. - `docs/SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md` records a docs/test-only allowlist lifecycle plan for future source-name guard allowlist entries without adding allowlist files, source scanning, dry-run report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, source-name guard enforcement, runtime naming enforcement, ArchUnit or package-boundary tooling, Maven build changes, routing/scoring/strategy/proxy behavior changes, or claiming production readiness. +- `docs/SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md` records a docs/test-only allowlist exit criteria plan for deciding when the source-name guard allowlist planning lane is complete enough to consider a separately approved implementation sprint later without adding allowlist files, source scanning, dry-run report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, source-name guard enforcement, runtime naming enforcement, ArchUnit or package-boundary tooling, Maven build changes, routing/scoring/strategy/proxy behavior changes, or claiming production readiness. - `docs/PRODUCTION_READINESS_SUMMARY.md` says production-candidate rather than production-certified. - `docs/REVIEWER_TRUST_MAP.md` gives reviewer paths for lab workflow, controlled policy evidence, observability, the combined measured performance plus auth proof lane, CI evidence gate readiness/prototype, performance, mocked auth proof, and release evidence. - Static documentation tests guard against production-ready gateway and certification overclaims. diff --git a/docs/REVIEWER_TRUST_MAP.md b/docs/REVIEWER_TRUST_MAP.md index 2f038719..34a1dbfd 100644 --- a/docs/REVIEWER_TRUST_MAP.md +++ b/docs/REVIEWER_TRUST_MAP.md @@ -53,6 +53,7 @@ Recommended first paths: - I want to review future source-name guard allowlist candidates before implementation: start with [`SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md`](SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md). It is a docs/test-only allowlist review checklist, not an allowlist file, source scanning, rule implementation, report generation, JSON/YAML/TOML output, CI workflow change, PR comment/report artifact behavior, source-name guard enforcement, runtime naming enforcement, package-boundary enforcement, or production-readiness proof. - I want to see static examples of future source-name guard allowlist entries before implementation: start with [`SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md). It is a docs/test-only allowlist sample plan, not an allowlist file, source scanning, rule implementation, report generation, JSON/YAML/TOML output, CI workflow change, PR comment/report artifact behavior, source-name guard enforcement, runtime naming enforcement, package-boundary enforcement, or production-readiness proof. - I want to understand future source-name guard allowlist entry lifecycle rules before implementation: start with [`SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md). It is a docs/test-only allowlist lifecycle plan, not an allowlist file, source scanning, rule implementation, report generation, JSON/YAML/TOML output, CI workflow change, PR comment/report artifact behavior, source-name guard enforcement, runtime naming enforcement, package-boundary enforcement, or production-readiness proof. +- I want to know when the source-name guard allowlist planning lane is complete enough to consider implementation later: start with [`SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md). It is a docs/test-only allowlist exit criteria plan, not an allowlist file, source scanning, rule implementation, report generation, JSON/YAML/TOML output, CI workflow change, PR comment/report artifact behavior, source-name guard enforcement, runtime naming enforcement, package-boundary enforcement, or production-readiness proof. - I want the current enterprise-readiness verdict: start with [`ENTERPRISE_READINESS_AUDIT.md`](ENTERPRISE_READINESS_AUDIT.md), then use [`PRODUCTION_READINESS_SUMMARY.md`](PRODUCTION_READINESS_SUMMARY.md) for the production-candidate snapshot. - I want the reviewer-ready trust-hardening sprint packet: start with [`ENTERPRISE_LAB_TRUST_HARDENING_SPRINT.md`](ENTERPRISE_LAB_TRUST_HARDENING_SPRINT.md). - I want to review repo-side governance ownership and manual settings recommendations: start with [`MANUAL_GITHUB_GOVERNANCE_HARDENING.md`](MANUAL_GITHUB_GOVERNANCE_HARDENING.md). @@ -403,6 +404,7 @@ Safety boundaries preserved by this path: | How should reviewers evaluate future source-name guard allowlist candidates before implementation? | Source-Name Guard Allowlist Review Checklist | [`SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md`](SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md), `SourceNameGuardAllowlistReviewChecklistDocumentationTest` | Docs/test-only allowlist review checklist for candidate review, rationale review, scope/path review, rule-category review, re-review triggers, suppression review, privacy/secret-safety, misuse risks, and approval gates before allowlist implementation | Reviewers can decide whether a future allowlist candidate is narrow, specific, auditable, rationale-backed, privacy-safe, and explicitly non-proving before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, or enforcement exists | Source-name guard allowlist implementation, allowlist files, source-name guard rule implementation, source scanning, dry-run report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, ArchUnit tooling, class renames, package moves, routing/scoring/strategy/proxy behavior changes, production readiness, production certification, live-cloud validation, or real-tenant validation | | How could reviewers read examples of future source-name guard allowlist entries before implementation? | Source-Name Guard Allowlist Sample Plan | [`SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md), `SourceNameGuardAllowlistSamplePlanDocumentationTest` | Docs/test-only allowlist sample plan with static examples for narrow entries, documentation-clarification-preferred outcomes, rename-preferred outcomes, suppression-review-required outcomes, stale re-review, invalid entries, privacy constraints, and misuse cautions before allowlist files or scanning exist | Reviewers can rehearse evaluating allowlist entry shapes before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR artifact behavior, or enforcement exists | Source-name guard allowlist implementation, allowlist files, source-name guard implementation/rule implementation, source scanning, dry-run report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, ArchUnit tooling, class renames, package moves, routing/scoring/strategy/proxy behavior changes, production readiness, production certification, live-cloud validation, or real-tenant validation | | How should future source-name guard allowlist entries be created, re-reviewed, expired, retired, migrated, and audited before implementation? | Source-Name Guard Allowlist Lifecycle Plan | [`SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md), `SourceNameGuardAllowlistLifecyclePlanDocumentationTest` | Docs/test-only allowlist lifecycle plan for future states, creation, re-review, expiration, retirement, migration, audit, stale-entry risk handling, privacy/secret-safety, and implementation gates before allowlist files or scanning exist | Reviewers can reason about entry lifecycle and stale-risk handling before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR artifact behavior, or enforcement exists | Source-name guard allowlist implementation, allowlist files, source-name guard implementation/rule implementation, source scanning, dry-run report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, ArchUnit tooling, class renames, package moves, routing/scoring/strategy/proxy behavior changes, production readiness, production certification, live-cloud validation, or real-tenant validation | +| When is the source-name guard allowlist planning lane complete enough to consider a separately approved implementation sprint later? | Source-Name Guard Allowlist Exit Criteria Plan | [`SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md), `SourceNameGuardAllowlistExitCriteriaPlanDocumentationTest` | Docs/test-only allowlist exit criteria plan for documentation completeness, review readiness, privacy/secret-safety, determinism, allowlist quality, misuse-risk criteria, implementation-readiness gates, and non-exit conditions before allowlist files or scanning exist | Reviewers can decide whether the allowlist planning lane has enough non-proving, privacy-safe, deterministic, reviewable criteria to consider a separately approved implementation sprint later | Source-name guard allowlist implementation, allowlist files, source-name guard implementation/rule implementation, source scanning, dry-run report generation, JSON/YAML/TOML output files, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, ArchUnit tooling, class renames, package moves, routing/scoring/strategy/proxy behavior changes, production readiness, production certification, live-cloud validation, or real-tenant validation | | Is `v2.5.0` published and verified? | Post-release verification note | [`V2_5_0_POST_RELEASE_VERIFICATION.md`](V2_5_0_POST_RELEASE_VERIFICATION.md), [`RELEASE_NOTES_v2.5.0.md`](RELEASE_NOTES_v2.5.0.md) | Exact tag `v2.5.0`, exact release commit recorded in the note, release workflow success, exact asset set, checksum verification, SBOM JSON/XML presence, and artifact attestation verification | Reviewers can confirm the JAR/docs-first GitHub Release exists and its evidence chain passed | Production deployment certification, real IdP tenant proof, production TLS/IAM/ingress/monitoring, container publication, or container signing | | Should distribution stay JAR/docs-first or become container-based? | Two-track release decision summary | [`RELEASE_READINESS_DECISION_SUMMARY.md`](RELEASE_READINESS_DECISION_SUMMARY.md), [`V2_5_0_POST_RELEASE_VERIFICATION.md`](V2_5_0_POST_RELEASE_VERIFICATION.md), [`RELEASE_NOTES_v2.5.0.md`](RELEASE_NOTES_v2.5.0.md), [`CONTAINER_REGISTRY_SIGNING_ROLLOUT.md`](CONTAINER_REGISTRY_SIGNING_ROLLOUT.md) | Verified `v2.5.0` JAR/docs-first release evidence, container rollout cost/gates, release notes, and remaining non-certification limits | Reviewers can use the released JAR/docs bundle now or defer container distribution until registry/signing gates are implemented | Container publication or production certification | | Can a release candidate be rehearsed without publishing? | Dry-run packet and checklist | [`RELEASE_CANDIDATE_DRY_RUN_PACKET.md`](RELEASE_CANDIDATE_DRY_RUN_PACKET.md), [`RELEASE_INTENT_REVIEW.md`](RELEASE_INTENT_REVIEW.md), [`V2_5_0_RELEASE_AUTHORIZATION_CHECKLIST.md`](V2_5_0_RELEASE_AUTHORIZATION_CHECKLIST.md), [`RELEASE_CANDIDATE_DRY_RUN.md`](RELEASE_CANDIDATE_DRY_RUN.md) | Current-main packet script, release-intent review packet, exact-version authorization checklist, reviewer packet template, go/no-go table | CI artifacts, local verification, SBOM, checksums, security gates, jar smoke, status UI, demos, and the recommended `v2.5.0` JAR/docs-first human decision map into ignored review evidence | Any tag, GitHub Release, asset upload, registry image, or container signature | diff --git a/docs/SOURCE_NAME_GUARD_ALLOWLIST_DESIGN_PLAN.md b/docs/SOURCE_NAME_GUARD_ALLOWLIST_DESIGN_PLAN.md index 265b3c0e..4102d5cd 100644 --- a/docs/SOURCE_NAME_GUARD_ALLOWLIST_DESIGN_PLAN.md +++ b/docs/SOURCE_NAME_GUARD_ALLOWLIST_DESIGN_PLAN.md @@ -82,6 +82,8 @@ The future source-name guard allowlist sample plan is documented in [`SOURCE_NAM The future source-name guard allowlist lifecycle plan is documented in [`SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md). That lifecycle plan remains docs/test-only and defines future allowlist entry states, creation, re-review, expiration, retirement, migration, audit, stale-entry risk handling, privacy/secret-safety, and implementation gates before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. +The future source-name guard allowlist exit criteria plan is documented in [`SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md). That exit criteria plan remains docs/test-only and defines when the allowlist planning lane is complete enough to consider a separately approved implementation sprint later before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. + The future report acceptance criteria plan is documented in [`SOURCE_NAME_GUARD_REPORT_ACCEPTANCE_CRITERIA_PLAN.md`](SOURCE_NAME_GUARD_REPORT_ACCEPTANCE_CRITERIA_PLAN.md). The future report review checklist is documented in [`SOURCE_NAME_GUARD_REPORT_REVIEW_CHECKLIST.md`](SOURCE_NAME_GUARD_REPORT_REVIEW_CHECKLIST.md). Both remain docs/test-only references and do not add source scanning, allowlist files, report generation, JSON/YAML/TOML output, JSON output files, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. ## Why Allowlist Design Comes Before Implementation diff --git a/docs/SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md b/docs/SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md new file mode 100644 index 00000000..ff25772e --- /dev/null +++ b/docs/SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md @@ -0,0 +1,308 @@ +# Source-Name Guard Allowlist Exit Criteria Plan + +This document defines exit criteria for deciding when the source-name guard allowlist planning lane is complete enough to consider a separately approved implementation sprint later. It is exit criteria only, no allowlist implementation, and it does not add source scanning, allowlist files, JSON/YAML/TOML allowlist output, dry-run report generation, JSON output files, CI workflow changes, PR comments, artifacts, source-name guard enforcement, runtime naming enforcement, or package-boundary enforcement. + +This is docs/test only. No source scanning is added in this sprint. No allowlist file is added. No allowlist files are added. No JSON/YAML/TOML output is added. No JSON/YAML/TOML allowlist output is added. No report generation is added. No dry-run report generation is added. No JSON output is generated. No JSON output files are generated. No CI workflow change is added. No PR comment or artifact behavior is added. No runtime naming guard is active. No source-name guard is implemented. No source-name guard rule implementation exists. No report file is written. No dry-run command is added. No allowlist implementation is added. No JSON/YAML/TOML allowlist file is added. No runtime naming enforcement is added. No source-name guard enforcement is active. No classes are renamed in this sprint. No package moves are made in this sprint. No ArchUnit or package-boundary tool is added. No Maven build files are changed. No runtime interface, API field, routing behavior, scoring behavior, strategy behavior, proxy behavior, configuration behavior, CI behavior, Docker behavior, release behavior, registry behavior, governance behavior, or production behavior is added. + +## Executive Summary + +PR #234 added [`SOURCE_NAME_GUARD_ALLOWLIST_DESIGN_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_DESIGN_PLAN.md), which defines future allowlist semantics before implementation. PR #235 added [`SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md`](SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md), which defines reviewer criteria for future allowlist candidates. PR #236 added [`SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md), which provides static documentation-only examples for future allowlist entries. PR #237 added [`SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md), which defines future allowlist lifecycle states and workflows. + +This allowlist exit criteria plan is the closure layer for the allowlist planning lane. It defines the documentation completeness, review-readiness, privacy/secret-safety, determinism, allowlist-quality, misuse-risk, implementation-readiness, and non-exit criteria reviewers should satisfy before considering a separately approved implementation sprint later. + +The core rules are: + +Allowlist exit criteria do not certify production safety. + +Allowlist exit criteria do not replace package-boundary enforcement. + +Allowlist exit criteria do not replace human review. + +## Current Status: Exit Criteria Only, No Allowlist Implementation + +Current status: + +- exit criteria only; +- exit criteria only, no allowlist implementation; +- documentation and documentation guard tests only; +- docs/test only; +- no implementation; +- no source scanning; +- no source scanning logic in this sprint; +- no allowlist file; +- no allowlist files; +- no JSON/YAML/TOML output; +- no JSON/YAML/TOML allowlist output; +- no report generation; +- no dry-run report generation; +- no JSON output; +- no JSON output files; +- no CI workflow change is added; +- no PR comment or artifact behavior is added; +- no dry-run command is added; +- no dry-run implementation is added; +- no runtime naming guard is active; +- no source-name guard is implemented; +- source-name guard rule implementation does not exist; +- source-name guard allowlist is not implemented; +- source-name guard allowlist review checklist is not enforcement; +- source-name guard allowlist sample is not generated output; +- source-name guard allowlist lifecycle is not implemented; +- source-name guard allowlist exit criteria is not enforcement; +- source-name guard not implemented yet; +- source-name guard dry run not implemented yet; +- source-name guard report schema not implemented yet; +- source-name guard report review checklist is not enforcement; +- source-name guard report sample is not generated output; +- source-name guard report acceptance criteria is not enforcement; +- source-name guard rule catalog is not implementation; +- source-name guard rule review checklist is not enforcement; +- no runtime naming enforcement is added; +- no source-name guard enforcement is active; +- no package-boundary enforcement is active; +- no classes are renamed in this sprint; +- no package moves are made in this sprint; +- no production Java runtime behavior is added; +- no records/classes/interfaces/enums under `src/main/java`; +- no ArchUnit or package-boundary tool is added; +- no new dependency is added; +- no Maven build files are changed; +- no API fields are added; +- no routing, scoring, strategy, proxy, config, CI, Docker, release, signing, registry, governance, or production behavior changes are made. + +This allowlist exit criteria plan does not claim allowlist implementation exists. This allowlist exit criteria plan does not claim source-name guard rule implementation exists. This allowlist exit criteria plan does not claim report generation exists. This allowlist exit criteria plan does not claim source-name guard enforcement is active. This allowlist exit criteria plan does not claim a runtime-enforced LASE boundary. This allowlist exit criteria plan does not claim package-boundary enforcement is active. + +## Relationship To Source-Name Guard Allowlist Design Plan + +The allowlist design plan defines future allowlist purpose, entry fields, review workflow, expiration and re-review, suppression strategy, privacy/secret-safety rules, deterministic-output rules, misuse risks, and implementation gates. + +This exit criteria plan depends on [`SOURCE_NAME_GUARD_ALLOWLIST_DESIGN_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_DESIGN_PLAN.md). Reviewers should use the design plan to understand the intended future semantics, then use this document to decide whether the design lane is complete enough to consider a separately approved implementation sprint later. + +## Relationship To Source-Name Guard Allowlist Review Checklist + +The allowlist review checklist defines how reviewers should evaluate future allowlist candidates before any allowlist file or source-name guard implementation exists. + +This exit criteria plan depends on [`SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md`](SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md). Reviewers should use that checklist to evaluate candidate quality, then use this document to decide whether reviewer expectations are complete, non-proving, privacy-safe, deterministic, and implementation-ready. + +## Relationship To Source-Name Guard Allowlist Sample Plan + +The allowlist sample plan provides static documentation-only examples for future allowlist entry shapes, documentation-clarification-preferred outcomes, rename-preferred outcomes, suppression-review-required outcomes, stale re-review outcomes, and invalid entries. + +This exit criteria plan depends on [`SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md). Reviewers should use the sample plan to rehearse concrete entries, then use this document to decide whether those examples make allowlist quality, stale-entry handling, and rejection conditions clear enough before implementation is discussed. + +## Relationship To Source-Name Guard Allowlist Lifecycle Plan + +The allowlist lifecycle plan defines future lifecycle states, creation workflow, re-review workflow, expiration workflow, retirement workflow, migration workflow, audit workflow, stale-entry risk handling, privacy/secret-safety requirements, and implementation gates. + +This exit criteria plan depends on [`SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md). Reviewers should use the lifecycle plan to understand how entries would move through future states, then use this document to decide whether the planning lane has enough lifecycle, audit, stale-entry, rollback, and non-exit language to pause before a separately approved implementation sprint. + +The future source-name guard rule review checklist is documented in [`SOURCE_NAME_GUARD_RULE_REVIEW_CHECKLIST.md`](SOURCE_NAME_GUARD_RULE_REVIEW_CHECKLIST.md). The future source-name guard rule catalog plan is documented in [`SOURCE_NAME_GUARD_RULE_CATALOG_PLAN.md`](SOURCE_NAME_GUARD_RULE_CATALOG_PLAN.md). Both remain docs/test-only references and do not add allowlist files, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. + +## Why Exit Criteria Come Before Implementation + +Exit criteria come before implementation because allowlist planning can otherwise drift into vague permission to scan, suppress, or enforce names without enough reviewer agreement: + +- reviewers need a clear definition of planning completeness before any allowlist file exists; +- allowlist quality criteria need to be visible before future entries can reduce repeated findings; +- privacy and secret-safety rules need to be explicit before any future output includes paths or names; +- deterministic-output rules need to exist before future reports or allowlist entries are generated; +- misuse risks need to be reviewed before suppressions become normal; +- non-exit conditions need to block an implementation proposal if docs are incomplete, vague, stale, too broad, or overclaiming; +- implementation-readiness gates need to keep allowlist files, source scanning, report generation, JSON/YAML/TOML output, CI integration, PR comments, artifacts, and enforcement separate. + +This plan defines exit criteria only. It does not implement source scanning, allowlist files, JSON/YAML/TOML output, report generation, CI workflow changes, PR comment/report artifact behavior, or enforcement. + +## Required Documentation Completeness Criteria + +The allowlist planning lane should not be considered ready for a separately approved implementation sprint unless documentation completeness is clear: + +- allowlist design plan exists; +- allowlist review checklist exists; +- allowlist sample plan exists; +- allowlist lifecycle plan exists; +- rule catalog exists; +- rule review checklist exists; +- report schema plan exists; +- report review checklist exists; +- report acceptance criteria exists; +- all docs clearly say planning only; +- all docs clearly say no enforcement; +- all docs clearly say no production-readiness claim. + +Documentation completeness means reviewers can trace the allowlist lane back to report quality, rule categories, and non-proving source-name guard boundaries. + +## Required Review-Readiness Criteria + +The allowlist planning lane should be review-ready only when: + +- reviewer can understand why allowlists may be needed; +- reviewer can evaluate an allowlist candidate; +- reviewer can evaluate rationale quality; +- reviewer can evaluate scope/path boundaries; +- reviewer can identify overbroad suppressions; +- reviewer can identify stale entries; +- reviewer can identify invalid entries; +- reviewer can identify when rename or documentation clarification is preferred; +- reviewer can confirm an allowlist does not certify production safety. + +Review readiness is about human judgment. It does not replace human review, source scanning approval, package-boundary enforcement, runtime safety controls, or production-readiness review. + +## Required Privacy And Secret-Safety Criteria + +Future allowlist planning should preserve privacy and secret safety before any output exists: + +- future allowlist entries must not include secrets; +- future allowlist entries must not include tokens; +- future allowlist entries must not include environment variable values; +- future allowlist entries must not include private network details; +- future allowlist entries must not include absolute local machine paths; +- future allowlist entries must avoid real reviewer names; +- future allowlist entries must avoid generated unstable IDs unless separately approved. + +Privacy and secret-safety criteria are exit criteria for planning only. They do not add scanners, filters, validators, config, environment reads, system-property reads, artifact uploads, PR comments, or runtime behavior. + +## Required Determinism Criteria + +Future allowlist planning should define deterministic behavior before any implementation exists: + +- future allowlist review should avoid unstable timestamps unless separately approved; +- future allowlist entries should avoid UUID/random/hash identifiers unless separately approved; +- future allowlist matching must be deterministic if implemented later; +- future allowlist report output must be deterministic if implemented later; +- future allowlist ordering must be stable if implemented later; +- future allowlist lifecycle states must be reviewable and stable. + +Determinism criteria do not add MessageDigest, SHA, UUID, random, time, environment, system-property, generated-ID, or report-generation behavior in this sprint. + +## Required Allowlist-Quality Criteria + +Future allowlist candidates should not be considered acceptable unless each candidate has clear reviewer context: + +- each candidate has a rule category; +- each candidate has a name or naming pattern; +- each candidate has a path/scope boundary; +- each candidate has a rationale; +- each candidate has reviewer action; +- each candidate has re-review trigger; +- each candidate has notProofStatement; +- each candidate avoids production-readiness claims; +- each candidate avoids certification claims; +- each candidate avoids replacing human review; +- each candidate avoids replacing package-boundary enforcement. + +Allowlist quality criteria do not certify production safety. They make future candidate review more specific if a later implementation sprint is separately approved. + +## Required Misuse-Risk Criteria + +The allowlist planning lane should explicitly guard against misuse: + +- allowlist must not become production safety certification; +- allowlist must not hide real overclaim risk; +- allowlist must not be too broad; +- allowlist must not become stale after rule changes; +- allowlist must not hide intentionally risky examples incorrectly; +- allowlist must not target generated/build output unless separately approved; +- allowlist must not become a substitute for package-boundary enforcement; +- allowlist must not become a substitute for runtime safety controls. + +Misuse-risk criteria are non-proving review criteria. They do not imply that a clean future allowlist output proves production safety. + +## Required Implementation-Readiness Gates + +Before any future allowlist implementation is proposed, reviewers should confirm: + +- design plan reviewed; +- review checklist reviewed; +- sample plan reviewed; +- lifecycle plan reviewed; +- exit criteria reviewed; +- rule catalog reviewed; +- rule review checklist reviewed; +- report schema reviewed; +- report review checklist reviewed; +- acceptance criteria reviewed; +- privacy/secret-safety reviewed; +- deterministic-output strategy reviewed; +- false-positive risk reviewed; +- false-negative risk reviewed; +- rollback/removal plan reviewed; +- CI impact reviewed; +- enforcement remains future-only unless separately approved. + +These implementation-readiness gates are reviewer checkpoints only. They do not implement an allowlist, source scanner, report generator, JSON/YAML/TOML output, CI workflow, PR comment, artifact, runtime naming guard, source-name guard enforcement, or package-boundary enforcement. + +## Explicit Non-Exit Conditions + +The allowlist planning lane should not be treated as complete if any of these conditions remain: + +- missing not-proven boundaries; +- vague allowlist rationale rules; +- no stale-entry handling; +- no privacy/secret-safety criteria; +- no deterministic-output criteria; +- no rollback/removal path; +- no false-positive review path; +- no false-negative review path; +- allowlist described as production safety certification; +- allowlist described as package-boundary enforcement; +- allowlist described as runtime enforcement; +- source-name guard implementation bundled with unrelated behavior changes. + +Any non-exit condition should keep implementation out of scope until a later scoped sprint resolves it. + +## Safety Boundaries And Non-Goals + +Hard boundaries for this sprint: + +- no production Java runtime behavior; +- no records/classes/interfaces/enums under `src/main/java`; +- no class renames; +- no package moves or refactors; +- no source scanning logic in this sprint; +- no allowlist files; +- no JSON/YAML/TOML allowlist output; +- no JSON/YAML/TOML output; +- no dry-run command; +- no dry-run implementation; +- no report generation; +- no JSON output files; +- no JSON output; +- no CI workflow changes; +- no PR comment/report artifact behavior; +- no runtime naming enforcement; +- no source-name guard enforcement; +- no package-boundary enforcement; +- no runtime LASE boundary implementation; +- no runtime workload model implementation; +- no runtime signal ingestion; +- no ArchUnit or any new dependency; +- no Maven build changes; +- no external API clients; +- no HTTP calls; +- no secrets, tokens, environment variables, credentials, config, or properties; +- no telemetry, storage, or persistence; +- no MessageDigest, SHA, hash, UUID, random, time, environment, or system-property behavior; +- no replay execution; +- no what-if mutation; +- no upload/share/download/export/PDF/ZIP behavior; +- no Docker, CI, release, signing, registry, or governance changes; +- no proxy behavior change; +- no strategy behavior change; +- no core routing behavior change; +- no scoring-internals behavior change; +- no production readiness claim; +- no production certification claim; +- no live-cloud validation claim; +- no real-tenant validation claim; +- no GPU orchestration claim; +- no power/grid control claim; +- no carbon-aware routing implementation claim; +- no facility automation claim. + +This allowlist exit criteria plan does not claim allowlist implementation exists. This allowlist exit criteria plan does not claim source-name guard rule implementation exists. This allowlist exit criteria plan does not claim report generation exists. This allowlist exit criteria plan does not claim source-name guard enforcement is active. This allowlist exit criteria plan does not claim a runtime-enforced LASE boundary. This allowlist exit criteria plan does not claim package-boundary enforcement is active. + +## Reviewer-Facing Value + +This plan gives reviewers a stopping rule for the allowlist planning lane before any allowlist file or source-name guard implementation exists. It explains what documentation, review, privacy, determinism, quality, misuse-risk, implementation-gate, and non-exit criteria should be satisfied before a separate implementation sprint is even considered. + +The value is strategic architecture readiness only. Source-name guard allowlist is not implemented. Source-name guard enforcement is not active. Package-boundary enforcement is not active. Runtime LASE boundary enforcement is not active. Production readiness, production certification, live-cloud validation, real-tenant validation, GPU orchestration, power/grid control, carbon-aware routing implementation, and facility automation remain not proven. diff --git a/docs/SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md b/docs/SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md index 082e1888..197ad0ad 100644 --- a/docs/SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md +++ b/docs/SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md @@ -91,6 +91,12 @@ The allowlist sample plan provides static documentation-only examples for future This lifecycle plan depends on [`SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md). Reviewers should use those examples to rehearse what candidate entries might look like, then use this lifecycle plan to keep future entries from becoming stale, too broad, or incorrectly interpreted as production safety proof. +## Relationship To Source-Name Guard Allowlist Exit Criteria Plan + +The allowlist exit criteria plan defines when the allowlist planning lane is complete enough to consider a separately approved implementation sprint later. + +This lifecycle plan supports [`SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md). Reviewers should use this lifecycle plan to understand creation, re-review, expiration, retirement, migration, audit, and stale-entry handling, then use the exit criteria plan to decide whether the planning lane has enough documentation completeness, review readiness, privacy/secret-safety, determinism, allowlist quality, misuse-risk, implementation-gate, and non-exit coverage before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. + The future source-name guard rule review checklist is documented in [`SOURCE_NAME_GUARD_RULE_REVIEW_CHECKLIST.md`](SOURCE_NAME_GUARD_RULE_REVIEW_CHECKLIST.md). The future source-name guard rule catalog plan is documented in [`SOURCE_NAME_GUARD_RULE_CATALOG_PLAN.md`](SOURCE_NAME_GUARD_RULE_CATALOG_PLAN.md). Both remain docs/test-only references and do not add allowlist files, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. ## Why Allowlist Lifecycle Comes Before Implementation diff --git a/docs/SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md b/docs/SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md index f3d1b7d4..e4a5bd83 100644 --- a/docs/SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md +++ b/docs/SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md @@ -83,6 +83,8 @@ The future source-name guard allowlist sample plan is documented in [`SOURCE_NAM The future source-name guard allowlist lifecycle plan is documented in [`SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md). That lifecycle plan remains docs/test-only and defines future allowlist entry states, creation, re-review, expiration, retirement, migration, audit, stale-entry risk handling, privacy/secret-safety, and implementation gates before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. +The future source-name guard allowlist exit criteria plan is documented in [`SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md). That exit criteria plan remains docs/test-only and defines when the allowlist planning lane is complete enough to consider a separately approved implementation sprint later before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. + ## When This Checklist Should Be Used Use this checklist when a future report-only source-name guard output, rule review, or reviewer discussion proposes adding a name, pattern, path, or scope to a future allowlist. diff --git a/docs/SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md b/docs/SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md index 216b5e70..ffaac329 100644 --- a/docs/SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md +++ b/docs/SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md @@ -87,6 +87,8 @@ The future source-name guard rule review checklist is documented in [`SOURCE_NAM The future source-name guard allowlist lifecycle plan is documented in [`SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md). That lifecycle plan remains docs/test-only and defines future allowlist entry states, creation, re-review, expiration, retirement, migration, audit, stale-entry risk handling, privacy/secret-safety, and implementation gates before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. +The future source-name guard allowlist exit criteria plan is documented in [`SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md). That exit criteria plan remains docs/test-only and defines when the allowlist planning lane is complete enough to consider a separately approved implementation sprint later before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. + ## Why Sample Entries Come Before Implementation Sample entries come before implementation because future allowlists can become noisy or misleading if reviewers do not first agree on what a good entry looks like: diff --git a/docs/SOURCE_NAME_GUARD_RULE_CATALOG_PLAN.md b/docs/SOURCE_NAME_GUARD_RULE_CATALOG_PLAN.md index c89891ff..b8b70179 100644 --- a/docs/SOURCE_NAME_GUARD_RULE_CATALOG_PLAN.md +++ b/docs/SOURCE_NAME_GUARD_RULE_CATALOG_PLAN.md @@ -78,6 +78,8 @@ The future source-name guard allowlist sample plan is documented in [`SOURCE_NAM The future source-name guard allowlist lifecycle plan is documented in [`SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md). That lifecycle plan remains docs/test-only and defines future allowlist entry states, creation, re-review, expiration, retirement, migration, audit, stale-entry risk handling, privacy/secret-safety, and implementation gates before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. +The future source-name guard allowlist exit criteria plan is documented in [`SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md). That exit criteria plan remains docs/test-only and defines when the allowlist planning lane is complete enough to consider a separately approved implementation sprint later before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. + ## Why Rule Catalog Comes Before Implementation Rule catalog comes before implementation because naming rules can become noisy or misleading if categories are invented after scanning begins: diff --git a/docs/SOURCE_NAME_GUARD_RULE_REVIEW_CHECKLIST.md b/docs/SOURCE_NAME_GUARD_RULE_REVIEW_CHECKLIST.md index cb1cbd19..7042417f 100644 --- a/docs/SOURCE_NAME_GUARD_RULE_REVIEW_CHECKLIST.md +++ b/docs/SOURCE_NAME_GUARD_RULE_REVIEW_CHECKLIST.md @@ -79,6 +79,8 @@ The future source-name guard allowlist sample plan is documented in [`SOURCE_NAM The future source-name guard allowlist lifecycle plan is documented in [`SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md). That lifecycle plan remains docs/test-only and defines future allowlist entry states, creation, re-review, expiration, retirement, migration, audit, stale-entry risk handling, privacy/secret-safety, and implementation gates before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. +The future source-name guard allowlist exit criteria plan is documented in [`SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md`](SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md). That exit criteria plan remains docs/test-only and defines when the allowlist planning lane is complete enough to consider a separately approved implementation sprint later before any allowlist file, source scanning, report generation, JSON/YAML/TOML output, CI workflow changes, PR comment/report artifact behavior, runtime naming enforcement, source-name guard enforcement, package-boundary enforcement, class renames, package moves, ArchUnit tooling, Maven build changes, or behavior changes. + ## Why Rule Review Comes Before Implementation Rule review comes before implementation because a future source-name guard can become noisy, misleading, or too broad if individual rules are not reviewed before scanning begins: diff --git a/src/test/java/com/richmond423/loadbalancerpro/api/SourceNameGuardAllowlistExitCriteriaPlanDocumentationTest.java b/src/test/java/com/richmond423/loadbalancerpro/api/SourceNameGuardAllowlistExitCriteriaPlanDocumentationTest.java new file mode 100644 index 00000000..425b324e --- /dev/null +++ b/src/test/java/com/richmond423/loadbalancerpro/api/SourceNameGuardAllowlistExitCriteriaPlanDocumentationTest.java @@ -0,0 +1,348 @@ +package com.richmond423.loadbalancerpro.api; + +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.Locale; + +import org.junit.jupiter.api.Test; + +class SourceNameGuardAllowlistExitCriteriaPlanDocumentationTest { + private static final Path DOC = + Path.of("docs/SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md"); + private static final Path ALLOWLIST_DESIGN_PLAN = + Path.of("docs/SOURCE_NAME_GUARD_ALLOWLIST_DESIGN_PLAN.md"); + private static final Path ALLOWLIST_REVIEW_CHECKLIST = + Path.of("docs/SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md"); + private static final Path ALLOWLIST_SAMPLE_PLAN = + Path.of("docs/SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md"); + private static final Path ALLOWLIST_LIFECYCLE_PLAN = + Path.of("docs/SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md"); + private static final Path RULE_REVIEW_CHECKLIST = + Path.of("docs/SOURCE_NAME_GUARD_RULE_REVIEW_CHECKLIST.md"); + private static final Path RULE_CATALOG_PLAN = Path.of("docs/SOURCE_NAME_GUARD_RULE_CATALOG_PLAN.md"); + private static final Path REVIEWER_TRUST_MAP = Path.of("docs/REVIEWER_TRUST_MAP.md"); + private static final Path ENTERPRISE_AUDIT = Path.of("docs/ENTERPRISE_READINESS_AUDIT.md"); + private static final Path README = Path.of("README.md"); + private static final Path POM = Path.of("pom.xml"); + + @Test + void allowlistExitCriteriaPlanDocExistsAndStatesNoImplementation() throws Exception { + String doc = read(DOC); + + for (String expected : List.of( + "# Source-Name Guard Allowlist Exit Criteria Plan", + "exit criteria only, no allowlist implementation", + "exit criteria only", + "docs/test only", + "No source scanning is added in this sprint.", + "No allowlist file is added.", + "No allowlist files are added.", + "No JSON/YAML/TOML output is added.", + "No JSON/YAML/TOML allowlist output is added.", + "No report generation is added.", + "No CI workflow change is added.", + "No PR comment or artifact behavior is added.", + "No runtime naming guard is active.", + "No source-name guard is implemented.", + "No source-name guard rule implementation exists.", + "No dry-run report generation is added.", + "No report file is written.", + "No dry-run command is added.", + "source-name guard allowlist exit criteria is not enforcement", + "source-name guard allowlist lifecycle is not implemented", + "source-name guard allowlist sample is not generated output", + "source-name guard allowlist review checklist is not enforcement", + "source-name guard allowlist is not implemented", + "no source scanning", + "no allowlist files", + "no JSON/YAML/TOML output", + "no report generation", + "no runtime naming guard is active")) { + assertTrue(doc.contains(expected), "allowlist exit criteria plan should state " + expected); + } + } + + @Test + void allowlistExitCriteriaPlanLinksAdjacentAllowlistAndRuleDocs() throws Exception { + String doc = read(DOC); + + for (String expected : List.of( + "SOURCE_NAME_GUARD_ALLOWLIST_DESIGN_PLAN.md", + "SOURCE_NAME_GUARD_ALLOWLIST_REVIEW_CHECKLIST.md", + "SOURCE_NAME_GUARD_ALLOWLIST_SAMPLE_PLAN.md", + "SOURCE_NAME_GUARD_ALLOWLIST_LIFECYCLE_PLAN.md", + "SOURCE_NAME_GUARD_RULE_REVIEW_CHECKLIST.md", + "SOURCE_NAME_GUARD_RULE_CATALOG_PLAN.md", + "Relationship To Source-Name Guard Allowlist Design Plan", + "Relationship To Source-Name Guard Allowlist Review Checklist", + "Relationship To Source-Name Guard Allowlist Sample Plan", + "Relationship To Source-Name Guard Allowlist Lifecycle Plan")) { + assertTrue(doc.contains(expected), "allowlist exit criteria plan should link adjacent document " + + expected); + } + + for (Path path : List.of(ALLOWLIST_DESIGN_PLAN, ALLOWLIST_REVIEW_CHECKLIST, ALLOWLIST_SAMPLE_PLAN, + ALLOWLIST_LIFECYCLE_PLAN, RULE_REVIEW_CHECKLIST, RULE_CATALOG_PLAN)) { + assertTrue(read(path).contains("SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md"), + path + " should link the allowlist exit criteria plan"); + } + } + + @Test + void allowlistExitCriteriaPlanIncludesDocumentationCompletenessAndReviewReadinessCriteria() + throws Exception { + String doc = read(DOC); + + for (String expected : List.of( + "Required Documentation Completeness Criteria", + "allowlist design plan exists", + "allowlist review checklist exists", + "allowlist sample plan exists", + "allowlist lifecycle plan exists", + "rule catalog exists", + "rule review checklist exists", + "report schema plan exists", + "report review checklist exists", + "report acceptance criteria exists", + "all docs clearly say planning only", + "all docs clearly say no enforcement", + "all docs clearly say no production-readiness claim", + "Required Review-Readiness Criteria", + "reviewer can understand why allowlists may be needed", + "reviewer can evaluate an allowlist candidate", + "reviewer can evaluate rationale quality", + "reviewer can evaluate scope/path boundaries", + "reviewer can identify overbroad suppressions", + "reviewer can identify stale entries", + "reviewer can identify invalid entries", + "reviewer can identify when rename or documentation clarification is preferred", + "reviewer can confirm an allowlist does not certify production safety")) { + assertTrue(doc.contains(expected), "allowlist exit criteria plan should include criteria " + + expected); + } + } + + @Test + void allowlistExitCriteriaPlanIncludesPrivacyDeterminismAndQualityCriteria() throws Exception { + String doc = read(DOC); + + for (String expected : List.of( + "Required Privacy And Secret-Safety Criteria", + "future allowlist entries must not include secrets", + "future allowlist entries must not include tokens", + "future allowlist entries must not include environment variable values", + "future allowlist entries must not include private network details", + "future allowlist entries must not include absolute local machine paths", + "future allowlist entries must avoid real reviewer names", + "future allowlist entries must avoid generated unstable IDs unless separately approved", + "Required Determinism Criteria", + "future allowlist review should avoid unstable timestamps unless separately approved", + "future allowlist entries should avoid UUID/random/hash identifiers unless separately approved", + "future allowlist matching must be deterministic if implemented later", + "future allowlist report output must be deterministic if implemented later", + "future allowlist ordering must be stable if implemented later", + "future allowlist lifecycle states must be reviewable and stable", + "Required Allowlist-Quality Criteria", + "each candidate has a rule category", + "each candidate has a name or naming pattern", + "each candidate has a path/scope boundary", + "each candidate has a rationale", + "each candidate has reviewer action", + "each candidate has re-review trigger", + "each candidate has notProofStatement", + "each candidate avoids production-readiness claims", + "each candidate avoids certification claims", + "each candidate avoids replacing human review", + "each candidate avoids replacing package-boundary enforcement")) { + assertTrue(doc.contains(expected), "allowlist exit criteria plan should include quality/privacy " + + expected); + } + } + + @Test + void allowlistExitCriteriaPlanIncludesMisuseRisksImplementationGatesAndNonExitConditions() + throws Exception { + String doc = read(DOC); + + for (String expected : List.of( + "Required Misuse-Risk Criteria", + "allowlist must not become production safety certification", + "allowlist must not hide real overclaim risk", + "allowlist must not be too broad", + "allowlist must not become stale after rule changes", + "allowlist must not hide intentionally risky examples incorrectly", + "allowlist must not target generated/build output unless separately approved", + "allowlist must not become a substitute for package-boundary enforcement", + "allowlist must not become a substitute for runtime safety controls", + "Required Implementation-Readiness Gates", + "design plan reviewed", + "review checklist reviewed", + "sample plan reviewed", + "lifecycle plan reviewed", + "exit criteria reviewed", + "rule catalog reviewed", + "rule review checklist reviewed", + "report schema reviewed", + "report review checklist reviewed", + "acceptance criteria reviewed", + "privacy/secret-safety reviewed", + "deterministic-output strategy reviewed", + "false-positive risk reviewed", + "false-negative risk reviewed", + "rollback/removal plan reviewed", + "CI impact reviewed", + "enforcement remains future-only unless separately approved", + "Explicit Non-Exit Conditions", + "missing not-proven boundaries", + "vague allowlist rationale rules", + "no stale-entry handling", + "no privacy/secret-safety criteria", + "no deterministic-output criteria", + "no rollback/removal path", + "no false-positive review path", + "no false-negative review path", + "allowlist described as production safety certification", + "allowlist described as package-boundary enforcement", + "allowlist described as runtime enforcement", + "source-name guard implementation bundled with unrelated behavior changes")) { + assertTrue(doc.contains(expected), "allowlist exit criteria plan should include gate/risk " + + expected); + } + } + + @Test + void allowlistExitCriteriaPlanKeepsExitCriteriaNonProving() throws Exception { + String doc = read(DOC); + + for (String expected : List.of( + "Allowlist exit criteria do not certify production safety.", + "Allowlist exit criteria do not replace package-boundary enforcement.", + "Allowlist exit criteria do not replace human review.", + "Review readiness is about human judgment.", + "Misuse-risk criteria are non-proving review criteria.", + "They do not imply that a clean future allowlist output proves production safety.", + "Allowlist quality criteria do not certify production safety.", + "The value is strategic architecture readiness only.")) { + assertTrue(doc.contains(expected), "allowlist exit criteria plan should keep criteria non-proving " + + expected); + } + } + + @Test + void explicitNonGoalsPreventAllowlistFilesScanningGenerationEnforcementAndProductionOverclaims() + throws Exception { + String doc = read(DOC); + String normalized = doc.toLowerCase(Locale.ROOT); + + for (String expected : List.of( + "no production Java runtime behavior", + "no records/classes/interfaces/enums under `src/main/java`", + "no class renames", + "no package moves or refactors", + "no source scanning logic in this sprint", + "no allowlist files", + "no JSON/YAML/TOML allowlist output", + "no JSON/YAML/TOML output", + "no dry-run command", + "no dry-run implementation", + "no report generation", + "no JSON output files", + "no JSON output", + "no CI workflow changes", + "no PR comment/report artifact behavior", + "no runtime naming enforcement", + "no source-name guard enforcement", + "no package-boundary enforcement", + "no runtime LASE boundary implementation", + "no runtime workload model implementation", + "no runtime signal ingestion", + "no ArchUnit or any new dependency", + "no Maven build changes", + "no external API clients", + "no HTTP calls", + "no secrets, tokens, environment variables, credentials, config, or properties", + "no telemetry, storage, or persistence", + "no MessageDigest, SHA, hash, UUID, random, time, environment, or system-property behavior", + "no replay execution", + "no what-if mutation", + "no upload/share/download/export/PDF/ZIP behavior", + "no Docker, CI, release, signing, registry, or governance changes", + "no proxy behavior change", + "no strategy behavior change", + "no core routing behavior change", + "no scoring-internals behavior change", + "no production readiness claim", + "no production certification claim", + "no live-cloud validation claim", + "no real-tenant validation claim", + "no GPU orchestration claim", + "no power/grid control claim", + "no carbon-aware routing implementation claim", + "no facility automation claim", + "This allowlist exit criteria plan does not claim allowlist implementation exists.", + "This allowlist exit criteria plan does not claim source-name guard rule implementation exists.", + "This allowlist exit criteria plan does not claim report generation exists.", + "This allowlist exit criteria plan does not claim source-name guard enforcement is active.", + "This allowlist exit criteria plan does not claim a runtime-enforced LASE boundary.", + "This allowlist exit criteria plan does not claim package-boundary enforcement is active.")) { + assertTrue(doc.contains(expected), "allowlist exit criteria plan should keep explicit boundary " + + expected); + } + + for (String forbidden : List.of( + "allowlist implementation now exists", + "allowlist file is now active", + "allowlist files are implemented", + "json/yaml/toml output is generated by this sprint", + "source-name guard rule implementation now exists", + "source-name guard rules are implemented", + "report generation is now active", + "source-name guard enforcement is now active", + "runtime naming guard is now active", + "source scanning is now active", + "source-name guard is now implemented", + "this allowlist exit criteria plan enforces source names", + "this allowlist exit criteria plan enforces package boundaries", + "package-boundary enforcement is now active", + "runtime lase boundary is implemented", + "production readiness is proven", + "production certification is proven", + "live-cloud validation is complete", + "real-tenant validation is complete")) { + assertFalse(normalized.contains(forbidden), "allowlist exit criteria plan must not overclaim: " + + forbidden); + } + } + + @Test + void reviewerEntryPointsLinkAllowlistExitCriteriaPlanAsDocsOnlyReference() throws Exception { + for (Path path : List.of(README, REVIEWER_TRUST_MAP, ENTERPRISE_AUDIT)) { + assertTrue(read(path).contains("SOURCE_NAME_GUARD_ALLOWLIST_EXIT_CRITERIA_PLAN.md"), + path + " should link the allowlist exit criteria plan"); + } + + String readme = read(README); + String trustMap = read(REVIEWER_TRUST_MAP); + String audit = read(ENTERPRISE_AUDIT); + + assertTrue(readme.contains("docs/test-only exit criteria")); + assertTrue(trustMap.contains("Docs/test-only allowlist exit criteria plan")); + assertTrue(audit.contains("docs/test-only allowlist exit criteria plan")); + } + + @Test + void sprintDoesNotIntroduceArchUnitDependency() throws Exception { + assertFalse(read(POM).toLowerCase(Locale.ROOT).contains("archunit"), + "this sprint must not add an ArchUnit dependency or build change"); + } + + private static String read(Path path) throws Exception { + assertTrue(Files.exists(path), path + " should exist"); + return Files.readString(path, StandardCharsets.UTF_8); + } +}