docs: add v0.2 governance rules spec

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.