From 901b8704665031a0059886f540ea7c197e082421 Mon Sep 17 00:00:00 2001 From: CoderDeltaLAN Date: Tue, 16 Jun 2026 23:47:17 +0100 Subject: [PATCH] docs: sync strategy and threat model with v0.2 state --- CHANGELOG.md | 1 + docs/PRODUCT-STRATEGY.md | 74 ++++++++++++++++++---------------------- docs/THREAT-MODEL.md | 12 +++---- 3 files changed, 41 insertions(+), 46 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a4c0e2c..0b3bc3b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ This project has a published GitHub Release line, but no stable support or API g ### Changed - Added Ruff linting to local checks and CI by installing project development dependencies before running `./scripts/check.sh`. +- Synced product strategy and threat model wording with the published `v0.2.0` release line and unreleased post-`v0.2.0` main state. - Synced support, security, README, and release-truth documentation after the published `v0.2.0` GitHub Release. - Added CLI output examples and governance rules reference documentation after the `v0.2.0` tag. diff --git a/docs/PRODUCT-STRATEGY.md b/docs/PRODUCT-STRATEGY.md index 1f5ff32..9d2a672 100644 --- a/docs/PRODUCT-STRATEGY.md +++ b/docs/PRODUCT-STRATEGY.md @@ -1,12 +1,12 @@ # Product Strategy Roadmap -This document defines the product direction for agent-rules-kit after the public v0.1.0 pre-release. +This document defines the product direction for agent-rules-kit after the published v0.2.0 GitHub Release and current post-v0.2.0 main fixes. It is a strategy document, not an implementation plan for a specific feature. It must not be used to claim capabilities that are not already implemented. ## Current product truth -agent-rules-kit v0.1.0 is a local Python CLI for repositories that use AI coding agents or assistant-specific instruction files. +agent-rules-kit has a published v0.2.0 GitHub Release line. Current main contains unreleased post-v0.2.0 fixes intended for a future patch release. The implemented product currently supports: @@ -16,8 +16,10 @@ The implemented product currently supports: - explicit `init --dry-run` planning; - explicit `init --write` behavior for root `AGENTS.md`; - backup before replacing an existing root `AGENTS.md`; -- pattern-based redaction for supported secret-like values; -- local tests, CI, release assets, and documented safety boundaries. +- conservative governance diagnostics for `AIRK-GOV001` through `AIRK-GOV006`; +- structured evidence for line-based governance findings; +- pattern-based redaction for supported secret-like values in supported output paths; +- local tests, Ruff linting, CI, release assets, and documented safety boundaries. The implemented product does not yet provide: @@ -32,7 +34,7 @@ The implemented product does not yet provide: - dependency or supply-chain scanning; - proof that a repository is safe. -The current strength is not feature breadth. The current strength is a narrow local tool with explicit boundaries. +The current strength is not feature breadth. The current strength is a narrow local tool with explicit boundaries and a published governance baseline. ## Product hypothesis @@ -150,7 +152,7 @@ Allowed claims: - baseline diagnostics for AI agent instruction files; - explicit write mode for supported init behavior; - pattern-based redaction for supported secret-like values; -- pre-release support boundary for 0.1.x. +- best-effort support boundary for the current GitHub Release line. Forbidden claims: @@ -170,18 +172,20 @@ Any claim that depends on measured results must be backed by tests, fixtures, be ### v0.2: Governance baseline -Goal: introduce the first narrow governance layer without changing the product into a generator, packager, or security scanner. +Status: published in v0.2.0, with unreleased post-v0.2.0 fixes on main. -Candidate capabilities: +Implemented scope: -- detect missing authority or scope sections in instruction files; -- detect risky instruction phrases related to secrets, direct pushes, ignored CI, destructive commands, network calls, or unsupported security claims; -- emit findings with severity, rule id, message, path, and optional line number; -- keep `check` read-only; -- preserve console, JSON, and Markdown output; -- keep findings conservative and explainable. +- missing authority or scope diagnostics; +- missing secret-handling boundary diagnostics; +- review or CI bypass diagnostics; +- unsafe command execution diagnostics; +- runtime network, LLM, or external API dependency diagnostics; +- unsupported security or maturity claim diagnostics; +- structured finding evidence for line-based governance findings; +- console, JSON, and Markdown output through the existing `check` command. -Non-goals for v0.2: +Still non-goals for v0.2: - automatic remediation; - broad rewriting; @@ -260,39 +264,29 @@ Candidate criteria: - private vulnerability reporting path or explicit documented alternative; - no unsupported security or maturity claims. -## First implementation candidate after strategy - -The first implementation candidate after this strategy should be narrow: - -`feat/add-governance-baseline-findings` - -Possible scope: - -- add a small rule set for instruction governance findings; -- analyze only supported instruction files already discovered by the current tool; -- keep `check` read-only; -- emit findings in existing output formats; -- include tests and fixtures; -- avoid a new top-level command unless the existing `check` design becomes unclear. +## Next implementation direction after v0.2 -This candidate must not be implemented until its exact rules, output shape, and non-goals are written down and reviewed. +The next implementation phase should be justified against the current repository state, not against the old v0.1 strategy snapshot. -A safer intermediate phase may be: +Good next candidates are narrow and evidence-backed: -`docs/add-v0.2-governance-rules-spec` +- release and package smoke hardening; +- additional instruction-file discovery only when official tool documentation supports it; +- a `doctor` baseline that summarizes existing scan and governance behavior without inventing new capabilities; +- context budget approximation only after output contracts are stable. -That phase would define the initial rules before touching code. +Any next code phase must preserve local-first behavior, read-only default behavior, no runtime network access, no runtime LLM dependency, no execution of repository commands, and conservative claims. ## Decision record -Decision: document product strategy before implementing v0.2 features. +Decision: keep product strategy as the boundary document after v0.2. Reason: -- the current v0.1 product is narrow and honest; -- adjacent tools already cover repository packaging, context frameworks, and rule generation; -- the real product wedge is instruction governance; -- building code before fixing the product boundary increases the risk of scope drift; -- a strategy document gives future features a reviewable standard. +- v0.2.0 already published the first governance baseline; +- current main contains post-v0.2.0 fixes that should become a future patch release; +- adjacent tools still cover repository packaging, context frameworks, and broad rule generation better than this project should; +- the real product wedge remains instruction governance; +- future features must be justified against this document to avoid scope drift. -The next code phase must be justified against this document. +The next code phase must be justified against the current repo, current docs, current tests, and current external tool behavior. diff --git a/docs/THREAT-MODEL.md b/docs/THREAT-MODEL.md index 3238439..56e39ae 100644 --- a/docs/THREAT-MODEL.md +++ b/docs/THREAT-MODEL.md @@ -1,12 +1,12 @@ # Threat Model -This document defines the v0.1 threat model for agent-rules-kit. +This document defines the threat model for agent-rules-kit. It was last reviewed for the published v0.2.0 release line and the current post-v0.2.0 main state. It is intentionally narrow. agent-rules-kit is a local CLI for diagnosing AI agent instruction files. It is not a security scanner, malware detector, CI/CD auditor, sandbox, secret manager, or autonomous remediation agent. ## Scope -In scope for v0.1: +In scope for the current release line and current main state: - local repository paths provided by the user; - supported agent instruction files such as AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, GitHub Copilot instructions, and GitHub instruction files; @@ -15,7 +15,7 @@ In scope for v0.1: - explicit init write behavior for baseline AGENTS.md creation or replacement with backup; - secret-like value redaction in findings and output. -Out of scope for v0.1: +Out of scope: - network access; - LLM calls; @@ -97,8 +97,8 @@ Risk: repository content or findings could be sent outside the machine. Mitigation: -- v0.1 runtime behavior has no network access by design; -- no telemetry, remote API, or LLM call is part of v0.1. +- runtime behavior has no network access by design; +- no telemetry, remote API, or LLM call is part of the current runtime design. ### Misleading security claims @@ -139,7 +139,7 @@ Any such change must include tests and must preserve the documented boundaries. ## Residual risk -Known residual risks for v0.1: +Known residual risks: - redaction patterns may miss unknown or unusual secret formats; - diagnostics may be incomplete;