diff --git a/docs/V0.2-GOVERNANCE-RULES-SPEC.md b/docs/V0.2-GOVERNANCE-RULES-SPEC.md new file mode 100644 index 0000000..6b56d9d --- /dev/null +++ b/docs/V0.2-GOVERNANCE-RULES-SPEC.md @@ -0,0 +1,393 @@ +# v0.2 Governance Rules Specification + +This document defines the first candidate governance rules 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. + +## Purpose + +The purpose of v0.2 is to add a narrow governance baseline for AI agent instruction files. + +The implementation should help maintainers identify obvious instruction governance risks while preserving the existing product boundaries: + +* local-first behavior; +* read-only behavior by default; +* no runtime network calls; +* no runtime LLM calls; +* no execution of commands from analyzed repositories; +* conservative findings; +* no unsupported security or maturity claims. + +## Source of truth + +This specification depends on docs/PRODUCT-STRATEGY.md. + +If a proposed rule conflicts with the product strategy, the strategy wins and the rule must be narrowed or rejected. + +## Current implementation boundary + +The current v0.1 implementation already supports: + +* discovering supported instruction files; +* reporting discovered files through `check`; +* console, JSON, and Markdown output for `check`; +* explicit init planning; +* explicit init write behavior for root `AGENTS.md`; +* backup before replacing an existing root `AGENTS.md`; +* 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. + +## v0.2 goal + +The v0.2 goal is to add explainable governance findings for supported instruction files. + +A governance finding is a conservative diagnostic about instruction-file quality, safety boundaries, maintainability, or contradictory guidance. + +A governance finding is not proof that a repository is safe. + +## Non-goals + +v0.2 must not include: + +* automatic remediation; +* broad rewriting of instruction files; +* a full rule generator; +* repository packaging for AI prompts; +* exact token accounting; +* cost prediction; +* dependency vulnerability scanning; +* malware detection; +* CI/CD security auditing; +* infrastructure or permission hardening; +* LLM-based evaluation; +* network-based validation; +* execution of repository commands; +* claims that the repository is secure. + +## Output model + +v0.2 should reuse the existing Finding model where possible. + +Each finding should include: + +* rule_id; +* severity; +* message; +* path when available; +* line 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. + +Console and Markdown output should remain human-readable and should not expose raw secret-like values. + +## Severity semantics + +The implementation must confirm the existing Severity enum before coding. + +The intended semantics are: + +* info: useful governance observation with no immediate risk; +* warning: likely governance issue that should be reviewed; +* error: strong boundary or claim problem that could mislead users or assistants. + +v0.2 should prefer warning over error unless the issue is clearly dangerous or misleading. + +## Rule design principles + +Rules must be: + +* local; +* deterministic; +* explainable; +* testable with fixtures; +* conservative; +* based on supported instruction files only; +* independent from network and LLM behavior; +* safe to run on untrusted repository text. + +Rules must not rely on broad semantic interpretation. Simple pattern matching is acceptable when documented and tested. + +## Candidate rules + +### AIRK-GOV001: Missing instruction scope or authority + +Purpose: +Detect instruction files that do not clearly state their scope, authority, or relationship to other project instructions. + +Severity: +info or warning, depending on implementation evidence. + +Trigger candidates: + +* no section or phrase indicating scope; +* no section or phrase indicating which files, directories, assistants, or repository areas the instruction applies to; +* no mention of higher-priority project instructions when multiple instruction files exist. + +Evidence: +Path of the file and optional line references if a partial marker exists. + +Message style: +Instruction file may lack clear scope or authority. + +Non-goals: + +* deciding the correct authority hierarchy automatically; +* rewriting the file; +* resolving cross-file conflicts. + +### AIRK-GOV002: Missing secret-handling boundary + +Purpose: +Detect instruction files that provide no visible guidance about secrets, tokens, credentials, private URLs, or customer data. + +Severity: +warning. + +Trigger candidates: + +* no mention of secrets, tokens, credentials, private data, private URLs, or customer data; +* no instruction to avoid committing or printing sensitive values. + +Evidence: +Path of the file. + +Message style: +Instruction file may lack an explicit secret-handling boundary. + +Non-goals: + +* full secret scanning; +* proving that a repository contains no secrets; +* validating actual secret policy compliance. + +### AIRK-GOV003: Review or CI bypass guidance + +Purpose: +Detect instructions that appear to encourage bypassing review, CI, branch protection, or safe integration flow. + +Severity: +warning or error. + +Trigger candidates: + +* direct push to main; +* skip CI; +* ignore failing tests; +* force push as a normal workflow; +* merge without review; +* bypass branch protection; +* commit secrets for debugging. + +Evidence: +Path and line number. + +Message style: +Instruction file appears to encourage bypassing review, CI, or safe integration boundaries. + +Non-goals: + +* auditing GitHub branch protection; +* determining whether the repository actually enforces CI; +* blocking legitimate emergency procedures if clearly documented with human approval. + +### AIRK-GOV004: Unsafe command execution guidance + +Purpose: +Detect instructions that ask assistants to run destructive, privileged, or broad commands without explicit human confirmation. + +Severity: +warning or error. + +Trigger candidates: + +* destructive shell commands; +* broad deletion; +* chmod or chown across wide paths; +* sudo as a normal instruction; +* install or uninstall commands without confirmation; +* executing downloaded scripts; +* executing repository scripts as trusted instructions. + +Evidence: +Path and line number. + +Message style: +Instruction file appears to encourage unsafe command execution without an explicit confirmation boundary. + +Non-goals: + +* full shell safety analysis; +* blocking all commands; +* determining whether a command is safe in every context. + +### AIRK-GOV005: Runtime network or LLM dependency guidance + +Purpose: +Detect instruction files that tell the tool or assistant workflow to send repository content to remote services, call LLMs, or rely on network behavior in a way that conflicts with agent-rules-kit boundaries. + +Severity: +warning. + +Trigger candidates: + +* upload repository contents to an external service; +* call a remote LLM for validation; +* use an API token to analyze files; +* send instruction files to a third-party endpoint. + +Evidence: +Path and line number. + +Message style: +Instruction file may depend on network or LLM behavior outside the local-first boundary. + +Non-goals: + +* prohibiting developers from using hosted assistants generally; +* detecting every external service; +* enforcing network isolation. + +### AIRK-GOV006: Unsupported security or maturity claim + +Purpose: +Detect instruction files that claim the repository, tool, or process is secure, safe, production-ready, or guaranteed without evidence. + +Severity: +warning or error. + +Trigger candidates: + +* guaranteed security; +* guaranteed safety; +* makes the repository secure; +* complete secret scanning; +* production-ready without criteria; +* enterprise-grade as a maturity claim. + +Evidence: +Path and line number. + +Message style: +Instruction file may contain an unsupported security or maturity claim. + +Non-goals: + +* banning all maturity language; +* 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. + +Preferred first code slice after this specification: + +1. AIRK-GOV006 unsupported security or maturity claim. +2. AIRK-GOV003 review or CI bypass guidance. +3. AIRK-GOV002 missing secret-handling boundary. + +Reason: +These are high-signal, easy to fixture, and aligned with current safety boundaries. + +AIRK-GOV001, AIRK-GOV004, and AIRK-GOV005 may follow after the first slice if the output model remains clean. + +## Fixture expectations + +v0.2 implementation should add or reuse fixtures that show: + +* a clean single-agent instruction file; +* missing secret-handling boundary; +* review or CI bypass language; +* unsupported security claim; +* multiple instruction files with overlapping guidance. + +Fixtures must use fake secrets only. + +Fixtures must not include real tokens, private URLs, customer data, or real infrastructure details. + +## Output expectations + +For console output: + +* keep discovery summary visible; +* show findings only after discovered files; +* keep messages short; +* avoid scary language unless severity justifies it. + +For JSON output: + +* include findings as structured objects; +* preserve stable keys where possible; +* include rule_id and severity; +* include path and line when available. + +For Markdown output: + +* include a findings section; +* keep rule ids visible; +* keep wording conservative. + +## Backward compatibility + +v0.2 may extend output, but it should not break basic `check` behavior: + +* exit code remains 0 when supported instruction files are found and no blocking error occurs; +* exit code remains 1 when no supported instruction files are found; +* exit code remains 2 for invalid usage or invalid repository input. + +Any change to exit codes must be documented before implementation. + +## Claims policy for v0.2 + +Allowed: + +* governance findings; +* baseline instruction-file diagnostics; +* local deterministic checks; +* conservative warnings; +* read-only by default. + +Forbidden: + +* security scanner; +* complete scanner; +* guaranteed safety; +* guaranteed security; +* exact token savings; +* exact cost reduction; +* enterprise-grade; +* autonomous remediation; +* proof that a repository is safe. + +## Implementation gate + +No v0.2 code should be written until this specification is reviewed against: + +* docs/PRODUCT-STRATEGY.md; +* docs/THREAT-MODEL.md; +* SECURITY.md; +* current CLI output behavior; +* existing test fixtures. + +The next implementation phase must name the exact subset of rules it will implement. + +## 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. + +If that still feels too large, split again: + +`feat/add-unsupported-claim-finding` + +The first code phase must preserve read-only behavior and existing runtime boundaries.