diff --git a/docs/V0.2-GOVERNANCE-RULES-SPEC.md b/docs/V0.2-GOVERNANCE-RULES-SPEC.md index 6b56d9d..f5938ec 100644 --- a/docs/V0.2-GOVERNANCE-RULES-SPEC.md +++ b/docs/V0.2-GOVERNANCE-RULES-SPEC.md @@ -1,8 +1,10 @@ # v0.2 Governance Rules Specification -This document defines the first candidate governance rules for agent-rules-kit after the v0.1.0 pre-release. +This document defines the v0.2 governance rules specification for agent-rules-kit after the v0.1.0 pre-release. -It is a specification document, not an implementation. It must not be used to claim that v0.2 behavior already exists. +It originally described candidate rules. Current `main` now contains unreleased v0.2 governance diagnostics based on this specification, including structured finding evidence and supported redaction for finding message, path, and evidence payload fields. + +This document must not be used to claim that v0.2 has been published as a versioned release. ## Purpose @@ -26,7 +28,7 @@ If a proposed rule conflicts with the product strategy, the strategy wins and th ## Current implementation boundary -The current v0.1 implementation already supports: +The published v0.1.0 pre-release supports: * discovering supported instruction files; * reporting discovered files through `check`; @@ -37,7 +39,18 @@ The current v0.1 implementation already supports: * pattern-based redaction helpers; * a Finding model with rule id, severity, message, and optional location fields. -v0.2 should build on this boundary. It should not introduce a new product category. +Current `main` additionally includes unreleased v0.2 governance diagnostics: + +* AIRK-GOV006 unsupported security or maturity claim; +* AIRK-GOV003 review or CI bypass guidance; +* AIRK-GOV004 unsafe command execution guidance; +* AIRK-GOV005 runtime network or LLM dependency guidance; +* AIRK-GOV002 missing secret-handling boundary; +* AIRK-GOV001 missing instruction scope or authority; +* structured finding evidence for line-based governance findings; +* supported redaction for finding message, path, and evidence payload fields. + +This unreleased v0.2 behavior builds on the v0.1.0 boundary. It does not introduce a new product category, and it has not been published as a versioned release yet. ## v0.2 goal @@ -77,6 +90,7 @@ Each finding should include: * message; * path when available; * line when available; +* evidence when available; * column only when useful and cheap to compute. The JSON output should remain machine-readable. Adding a findings list is acceptable if existing top-level behavior remains understandable. @@ -279,20 +293,20 @@ Non-goals: * judging real organizational compliance; * replacing human release review. -## Rule ordering for implementation - -The first implementation should not add every rule if that makes the change too large. +## Implemented rule ordering on current main -Preferred first code slice after this specification: +Current `main` evaluates unreleased governance findings in this stable order: 1. AIRK-GOV006 unsupported security or maturity claim. 2. AIRK-GOV003 review or CI bypass guidance. -3. AIRK-GOV002 missing secret-handling boundary. +3. AIRK-GOV004 unsafe command execution guidance. +4. AIRK-GOV005 runtime network or LLM dependency guidance. +5. AIRK-GOV002 missing secret-handling boundary. +6. AIRK-GOV001 missing instruction scope or authority. -Reason: -These are high-signal, easy to fixture, and aligned with current safety boundaries. +This order documents current `main` behavior. It is not proof of a published v0.2 release. -AIRK-GOV001, AIRK-GOV004, and AIRK-GOV005 may follow after the first slice if the output model remains clean. +Future rule-order changes must remain deterministic, documented, fixture-backed, and conservative. ## Fixture expectations @@ -362,32 +376,39 @@ Forbidden: * autonomous remediation; * proof that a repository is safe. -## Implementation gate +## Release gate -No v0.2 code should be written until this specification is reviewed against: +Before publishing a versioned v0.2 release, the maintainer must verify this specification against: * docs/PRODUCT-STRATEGY.md; * docs/THREAT-MODEL.md; * SECURITY.md; * current CLI output behavior; -* existing test fixtures. +* existing test fixtures; +* README.md; +* CHANGELOG.md. -The next implementation phase must name the exact subset of rules it will implement. +The release review must confirm that: + +* local checks pass; +* CI passes for the release SHA; +* console, JSON, and Markdown governance output are covered by tests or fixtures; +* finding evidence is redacted before supported output is emitted; +* v0.2 documentation does not claim that the project is a security scanner; +* v0.2 documentation does not claim proof of repository safety; +* tag and GitHub Release point to the verified release SHA. ## Recommended next phase after this document Recommended next phase: -`feat/add-governance-baseline-findings` - -Only if scope is limited to the first small subset: - -* AIRK-GOV006; -* AIRK-GOV003; -* AIRK-GOV002. +`test/add-governance-golden-output-coverage` -If that still feels too large, split again: +Only if scope is limited to existing unreleased v0.2 behavior: -`feat/add-unsupported-claim-finding` +* no new governance rules; +* no output redesign; +* no release, tag, or version change; +* no security or maturity claims. -The first code phase must preserve read-only behavior and existing runtime boundaries. +The next test phase must preserve read-only behavior and existing runtime boundaries.