From 856e67518e525b18230c5bf5340136dceb62dcc8 Mon Sep 17 00:00:00 2001 From: hyeokjun32 Date: Fri, 19 Jun 2026 21:19:00 +0900 Subject: [PATCH] Document Lab decision policy rules --- README.ko.md | 1 + README.md | 2 +- docs/pipeline_contract.md | 3 ++ docs/policy/lab_decision_policy.md | 69 ++++++++++++++++++++++++++++++ tests/test_deployment_decision.py | 31 ++++++++++++++ 5 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 docs/policy/lab_decision_policy.md diff --git a/README.ko.md b/README.ko.md index d2d4dd2..47ad966 100644 --- a/README.ko.md +++ b/README.ko.md @@ -92,6 +92,7 @@ Guardrail: - `portfolio-demo-check`는 committed Studio fixture, README/PPT 수치, portfolio docs, local Studio asset을 검증합니다. - `core4-conformance-check`는 Forge manifest/metadata fixture, Runtime result JSON, Lab compare/deployment decision surface, AIGuard `guard_analysis` evidence를 기존 schema 변경 없이 검증합니다. +- Lab decision surface는 `policy_version`, `triggered_rules`, `policy_summary`를 노출하며, reviewer는 [Lab Decision Policy](docs/policy/lab_decision_policy.md)에서 rule별 의미를 확인할 수 있습니다. 추가 report path: diff --git a/README.md b/README.md index e4061aa..7f71d47 100644 --- a/README.md +++ b/README.md @@ -202,7 +202,7 @@ Guardrails: - `portfolio-demo-check` validates committed Studio fixtures, README/PPT metrics, portfolio docs, and local Studio assets without starting workers, queues, databases, or a production SaaS service. - `core4-conformance-check` validates bundled Forge manifest/metadata, Runtime result JSON, Lab compare bundle aliases/rendered outputs, Lab deployment decision surface, and AIGuard `guard_analysis` without mutating existing schemas. -- The Lab decision surface exposes `policy_version`, `triggered_rules`, and `policy_summary` so reviewers can see which local policy rules produced deploy/review/block/unknown outcomes. +- The Lab decision surface exposes `policy_version`, `triggered_rules`, and `policy_summary` so reviewers can see which local policy rules produced deploy/review/block/unknown outcomes; see [Lab Decision Policy](docs/policy/lab_decision_policy.md). Additional report paths: diff --git a/docs/pipeline_contract.md b/docs/pipeline_contract.md index f781d2c..50ad6f9 100644 --- a/docs/pipeline_contract.md +++ b/docs/pipeline_contract.md @@ -128,6 +128,9 @@ Deployment decisions include a backward-compatible policy trace: - `triggered_rules`: compact rule IDs explaining which Lab/Guard/contract conditions affected the decision. - `policy_summary`: reviewer-facing rule effects and descriptions. +The reviewer-facing policy reference is maintained in +[Lab Decision Policy](policy/lab_decision_policy.md). + The v1 policy keeps existing decision behavior stable while making review/block reasoning explicit. Examples include Guard error evidence mapping to `blocked`, Guard warning evidence mapping to `review_required`, shape mismatch mapping to review, and latency/accuracy trade-off risk mapping to review. ## SaaS Boundary diff --git a/docs/policy/lab_decision_policy.md b/docs/policy/lab_decision_policy.md new file mode 100644 index 0000000..851da1d --- /dev/null +++ b/docs/policy/lab_decision_policy.md @@ -0,0 +1,69 @@ +# InferEdgeLab Decision Policy + +Policy version: `inferedge-lab-decision-policy-v1` + +This document is the reviewer-facing reference for the Lab-owned +`deployment_decision` surface. It explains why a comparison is marked +`deployable`, `deployable_with_note`, `review_required`, `blocked`, or +`unknown` without changing the existing compare, Runtime result, or AIGuard +contracts. + +## Scope + +InferEdgeLab owns the final deployment decision. Forge and Runtime provide +provenance and execution evidence, and AIGuard provides optional deterministic +diagnosis evidence. AIGuard, EdgeEnv, Orchestrator, and CI artifacts can add +context, but they do not replace Lab policy ownership. + +## Decision Trace Fields + +Every Lab deployment decision includes: + +- `policy_version`: the policy identifier used to produce the decision. +- `triggered_rules`: compact rule IDs explaining which evidence paths affected + the decision. +- `policy_summary`: reviewer-facing rule effects and descriptions for each + triggered rule. + +These fields are additive policy trace metadata. They do not remove or rename +existing deployment decision fields. + +## Rule Table + +| Rule | Effect | Description | +|---|---|---| +| `guard_error_block` | `blocked` | AIGuard reported error-level diagnosis evidence. | +| `guard_warning_review` | `review_required` | AIGuard reported warning-level diagnosis evidence. | +| `guard_skipped_unknown` | `unknown` | AIGuard was skipped, so diagnosis evidence is incomplete. | +| `guard_unavailable_unknown` | `unknown` | AIGuard evidence is unavailable for this comparison. | +| `guard_ok_lab_favorable_deployable` | `deployable` | Lab comparison is favorable and AIGuard passed. | +| `guard_ok_lab_neutral_deployable_note` | `deployable_with_note` | Lab comparison is neutral and AIGuard passed. | +| `guard_ok_lab_unfavorable_review` | `review_required` | Lab comparison indicates regression or mismatch despite AIGuard passing. | +| `guard_ok_lab_unknown` | `unknown` | Lab comparison judgement is not recognized by the decision policy. | +| `guard_status_unrecognized_unknown` | `unknown` | AIGuard status is not recognized by the decision policy. | +| `shape_mismatch_review` | `review_required` | Input shape mismatch requires explicit deployment review. | +| `system_mismatch_unfavorable_review` | `review_required` | System mismatch combined with unfavorable Lab judgement requires review. | +| `system_mismatch_note` | `deployable_with_note` | System mismatch reduces confidence and must be noted in release evidence. | +| `tradeoff_risk_review` | `review_required` | Latency/accuracy trade-off risk requires deployment review. | +| `worker_uncompared_unknown` | `unknown` | Worker result has not been compared by Lab yet. | +| `edgeenv_runtime_regression_review` | `review_required` | EdgeEnv same-condition runtime regression evidence requires review. | + +## Reviewer Interpretation + +- `blocked` means deployment should not proceed until the blocking evidence is + resolved. +- `review_required` means a human reviewer should inspect the cited Lab, + AIGuard, EdgeEnv, or contract evidence before deployment. +- `deployable_with_note` means deployment can proceed only with the noted + evidence retained in the release record. +- `unknown` means Lab does not have enough compatible evidence to make a + confident deployment call. + +## Boundaries + +- This policy does not mutate `metadata.json`, `manifest.json`, Runtime + `result.json`, compare output, or AIGuard `guard_analysis`. +- This policy does not make AIGuard, EdgeEnv, Orchestrator, or CI the final + deployment decision owner. +- This policy is local-first validation evidence. It is not a production SaaS + approval workflow, cloud control plane, or model zoo automation policy. diff --git a/tests/test_deployment_decision.py b/tests/test_deployment_decision.py index 59ce2b6..7267609 100644 --- a/tests/test_deployment_decision.py +++ b/tests/test_deployment_decision.py @@ -1,5 +1,8 @@ from __future__ import annotations +from pathlib import Path + +from inferedgelab.services.deployment_decision import POLICY_RULES from inferedgelab.services.deployment_decision import POLICY_VERSION from inferedgelab.services.deployment_decision import build_deployment_decision @@ -217,3 +220,31 @@ def test_diagnosis_guard_verdict_review_requires_lab_review(): assert decision["guard_status"] == "warning" assert decision["guard_verdict"] == "review_required" assert_policy(decision, "guard_warning_review") + + +def test_lab_decision_policy_reference_documents_current_rules(): + root = Path(__file__).resolve().parents[1] + policy_doc = (root / "docs" / "policy" / "lab_decision_policy.md").read_text( + encoding="utf-8" + ) + readme = (root / "README.md").read_text(encoding="utf-8") + readme_ko = (root / "README.ko.md").read_text(encoding="utf-8") + pipeline_contract = (root / "docs" / "pipeline_contract.md").read_text( + encoding="utf-8" + ) + + assert POLICY_VERSION in policy_doc + assert "Lab owns the final deployment decision" in policy_doc + assert "policy_version" in policy_doc + assert "triggered_rules" in policy_doc + assert "policy_summary" in policy_doc + assert "not mutate `metadata.json`, `manifest.json`, Runtime" in policy_doc + assert "not make AIGuard, EdgeEnv, Orchestrator, or CI" in policy_doc + assert "production SaaS" in policy_doc + for rule, metadata in POLICY_RULES.items(): + assert f"`{rule}`" in policy_doc + assert f"| `{rule}` | `{metadata['effect']}` | {metadata['description']} |" in policy_doc + + assert "docs/policy/lab_decision_policy.md" in readme + assert "docs/policy/lab_decision_policy.md" in readme_ko + assert "policy/lab_decision_policy.md" in pipeline_contract