ai-docs-toolkit 0.2.0__tar.gz → 0.3.0__tar.gz

{ai_docs_toolkit-0.2.0 → ai_docs_toolkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-docs-toolkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: AI-oriented documentation toolkit.
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -30,10 +30,12 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-The stable 0.2.0 package includes:
+Version 0.3.0 includes:
+
 - schema and structure validation for Markdown documents with YAML front matter;
 - document graph output;
-- impact analysis;
+- impact analysis with linked test cases and changed-path discovery coverage;
+- optional saved review evidence and the read-only `ai-docs review-check` command;
 - context bundle output;
 - an executable `ai-docs` CLI;
 - optional local MCP runtime entrypoint.
@@ -43,27 +45,53 @@ The stable 0.2.0 package includes:
 Install the stable release with Python 3.14 or newer:
 
 ```bash
-python -m pip install ai-docs-toolkit==0.2.0
+python -m pip install ai-docs-toolkit==0.3.0
 ai-docs --version
 ```
 
 For ephemeral execution with `uvx`:
 
 ```bash
-uvx --python 3.14 --from ai-docs-toolkit==0.2.0 ai-docs --version
+uvx --python 3.14 --from ai-docs-toolkit==0.3.0 ai-docs --version
 ```
 
 For the optional local MCP runtime:
 
 ```bash
-python -m pip install "ai-docs-toolkit[mcp]==0.2.0"
+python -m pip install "ai-docs-toolkit[mcp]==0.3.0"
 ai-docs-mcp --project-root .
 ```
 
 For the latest stable release, use `python -m pip install --upgrade ai-docs-toolkit`
 without an exact version pin.
 
-## Stable 0.2.0
+## Release 0.3.0
+
+Impact now reaches explicitly linked test cases from business rules, scenarios
+and acceptance criteria. Test cases end traversal. Changed-mode JSON adds a
+`coverage` object with path counts and unmapped reasons; strict JSON clients
+must accept that field. Explicit-id output keeps its shape. Coverage describes
+discovery and does not establish semantic completeness or successful tests.
+
+The optional `ai-docs review-check RECORD --format json` command compares a
+saved YAML review with current input hashes, tool identity, impact candidates
+and decisions. It supports YAML files and fenced YAML in Markdown. It is
+read-only; exit 0 means no mechanical discrepancy, not review approval.
+Git discovery preserves literal Unicode/whitespace paths and rename/deletion
+evidence. Existing CLI/MCP entrypoints and independent project gates remain.
+
+After upgrading from 0.2.0, review `ai-docs init --check` and `ai-docs init
+--dry-run`, reconcile local overrides, then refresh the existing managed review
+skill/reference with `ai-docs init`. Run project validation and representative
+impact checks. No schema, id, layout or mandatory review-record migration is
+required. Preserve historical review evidence; a new tool identity requires a
+new reviewed round instead of silently rewriting previous evidence.
+
+See the packaged `ai_docs_toolkit/docs/agent-installation.md`,
+“Migration 0.2.0 To 0.3.0”, for commands, preservation rules and rollback.
+Consumers on 0.1.0 must also apply the Python/archive prerequisites below.
+
+## Earlier Stable 0.2.0
 
 Completed task files are retained as execution history. Standalone tasks are
 archived after closure; tasks in a plan stay in place with status `done` until
@@ -221,6 +249,12 @@ Analyze impact for changed files:
 ai-docs impact --changed
 ```
 
+Check optional saved review evidence:
+
+```bash
+ai-docs review-check review.yaml --format json
+```
+
 Prepare an agent context bundle for changed files:
 
 ```bash
@@ -267,7 +301,7 @@ Operators can give the prompt from that document to an AI agent when asking it t
 
 ## Development
 
-Version 0.2.0 and the development baseline require Python 3.14+. Earlier
+Versions 0.2.0 and later require Python 3.14+. Earlier
 published releases retain their original Python requirements. Recreate older
 environments with Python 3.14+ before upgrading.
 

{ai_docs_toolkit-0.2.0 → ai_docs_toolkit-0.3.0}/README.md

@@ -2,7 +2,7 @@
 
 AI Docs Toolkit is a documentation toolkit for AI-assisted software development.
 
-It treats documentation as an engineering interface between humans, AI agents, code, tests and change management. Version 0.2.0 retains completed task history and requires Python 3.14 or newer.
+It treats documentation as an engineering interface between humans, AI agents, code, tests and change management. Version 0.3.0 adds linked test cases to impact, changed-path coverage and optional review evidence checks. Python 3.14 or newer is required.
 
 ## Purpose
 
@@ -83,7 +83,10 @@ pipx install ai-docs-toolkit
 uvx --from ai-docs-toolkit ai-docs validate
 ```
 
-For upgrades from 0.1.0, follow the [consumer migration guide](src/ai_docs_toolkit/docs/agent-installation.md#migration-010-to-020).
+For upgrades to 0.3.0, follow the [consumer migration guide](src/ai_docs_toolkit/docs/agent-installation.md#migration-020-to-030).
+Install the exact version only after it is available on PyPI; a source preparation
+commit does not publish the package. Consumers on 0.1.0 must also apply the
+[0.2.0 prerequisites](src/ai_docs_toolkit/docs/agent-installation.md#migration-010-to-020).
 Use Python 3.14+, review managed-file changes and preserve existing project rules
 and task records before refreshing. Completed standalone tasks are archived;
 tasks in a plan remain in place until the whole plan is archived.
@@ -135,6 +138,21 @@ ai-docs impact --changed --base <git-ref> --format json
 
 Projects can opt in to code-to-document impact through `cascade.root_module` and `cascade.module_ownership` in `ai-docs.config.yaml`.
 
+Changed-mode output includes discovery coverage and unmapped paths with reasons.
+Impact follows explicit rule, scenario and acceptance links to test cases;
+returned test cases are review candidates and do not prove test execution.
+
+Check a saved review record without modifying the project:
+
+```bash
+ai-docs review-check review.yaml --format json
+```
+
+This optional command reports missing decisions, changed input hashes and changed
+impact candidates. It does not approve semantic correctness. See the
+[review record contract](.ai-docs/reference/documentation-change-review-skill.md#advisory-checker)
+for YAML/Markdown input, tool identity and exit codes.
+
 Prepare an agent context bundle for changed files:
 
 ```bash

{ai_docs_toolkit-0.2.0 → ai_docs_toolkit-0.3.0}/packaging/pypi/README.md

@@ -16,10 +16,12 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-The stable 0.2.0 package includes:
+Version 0.3.0 includes:
+
 - schema and structure validation for Markdown documents with YAML front matter;
 - document graph output;
-- impact analysis;
+- impact analysis with linked test cases and changed-path discovery coverage;
+- optional saved review evidence and the read-only `ai-docs review-check` command;
 - context bundle output;
 - an executable `ai-docs` CLI;
 - optional local MCP runtime entrypoint.
@@ -29,27 +31,53 @@ The stable 0.2.0 package includes:
 Install the stable release with Python 3.14 or newer:
 
 ```bash
-python -m pip install ai-docs-toolkit==0.2.0
+python -m pip install ai-docs-toolkit==0.3.0
 ai-docs --version
 ```
 
 For ephemeral execution with `uvx`:
 
 ```bash
-uvx --python 3.14 --from ai-docs-toolkit==0.2.0 ai-docs --version
+uvx --python 3.14 --from ai-docs-toolkit==0.3.0 ai-docs --version
 ```
 
 For the optional local MCP runtime:
 
 ```bash
-python -m pip install "ai-docs-toolkit[mcp]==0.2.0"
+python -m pip install "ai-docs-toolkit[mcp]==0.3.0"
 ai-docs-mcp --project-root .
 ```
 
 For the latest stable release, use `python -m pip install --upgrade ai-docs-toolkit`
 without an exact version pin.
 
-## Stable 0.2.0
+## Release 0.3.0
+
+Impact now reaches explicitly linked test cases from business rules, scenarios
+and acceptance criteria. Test cases end traversal. Changed-mode JSON adds a
+`coverage` object with path counts and unmapped reasons; strict JSON clients
+must accept that field. Explicit-id output keeps its shape. Coverage describes
+discovery and does not establish semantic completeness or successful tests.
+
+The optional `ai-docs review-check RECORD --format json` command compares a
+saved YAML review with current input hashes, tool identity, impact candidates
+and decisions. It supports YAML files and fenced YAML in Markdown. It is
+read-only; exit 0 means no mechanical discrepancy, not review approval.
+Git discovery preserves literal Unicode/whitespace paths and rename/deletion
+evidence. Existing CLI/MCP entrypoints and independent project gates remain.
+
+After upgrading from 0.2.0, review `ai-docs init --check` and `ai-docs init
+--dry-run`, reconcile local overrides, then refresh the existing managed review
+skill/reference with `ai-docs init`. Run project validation and representative
+impact checks. No schema, id, layout or mandatory review-record migration is
+required. Preserve historical review evidence; a new tool identity requires a
+new reviewed round instead of silently rewriting previous evidence.
+
+See the packaged `ai_docs_toolkit/docs/agent-installation.md`,
+“Migration 0.2.0 To 0.3.0”, for commands, preservation rules and rollback.
+Consumers on 0.1.0 must also apply the Python/archive prerequisites below.
+
+## Earlier Stable 0.2.0
 
 Completed task files are retained as execution history. Standalone tasks are
 archived after closure; tasks in a plan stay in place with status `done` until
@@ -207,6 +235,12 @@ Analyze impact for changed files:
 ai-docs impact --changed
 ```
 
+Check optional saved review evidence:
+
+```bash
+ai-docs review-check review.yaml --format json
+```
+
 Prepare an agent context bundle for changed files:
 
 ```bash
@@ -253,7 +287,7 @@ Operators can give the prompt from that document to an AI agent when asking it t
 
 ## Development
 
-Version 0.2.0 and the development baseline require Python 3.14+. Earlier
+Versions 0.2.0 and later require Python 3.14+. Earlier
 published releases retain their original Python requirements. Recreate older
 environments with Python 3.14+ before upgrading.
 

{ai_docs_toolkit-0.2.0 → ai_docs_toolkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-docs-toolkit"
-version = "0.2.0"
+version = "0.3.0"
 description = "AI-oriented documentation toolkit."
 readme = "packaging/pypi/README.md"
 requires-python = ">=3.14"

{ai_docs_toolkit-0.2.0 → ai_docs_toolkit-0.3.0}/src/ai_docs_toolkit/__init__.py

@@ -1,3 +1,3 @@
 """AI Docs Toolkit package baseline."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{ai_docs_toolkit-0.2.0 → ai_docs_toolkit-0.3.0}/src/ai_docs_toolkit/cli/__init__.py

@@ -91,6 +91,7 @@ def _help_text() -> str:
             "  ai-docs tasks push --provider azure-devops (--task TASK-ID | --stage STAGE-ID | --plan PLAN-ID) --organization ORG --project PROJECT [--dry-run] [--write-back] [--format json]",
             "  ai-docs graph --format json [--type TYPE] [--module MODULE] [--id ID]",
             "  ai-docs impact (--id ID | --changed [--base REF]) [--format json]",
+            "  ai-docs review-check RECORD [--record N] [--format json|--json]",
             "  ai-docs context (--id ID | --module MODULE | --feature FEATURE | --changed) [--format json] [--history exclude|include|legacy] [--body-budget-bytes N] [--depth N]",
             "  ai-docs mcp status [--project-root PATH] [--config FILE]",
             "  ai-docs mcp configure --client jetbrains --print-json [--project-root PATH] [--config FILE]",
@@ -116,6 +117,21 @@ def main(argv: list[str] | None = None) -> int:
         print(__version__)
         return 0
 
+    if args[0] == "review-check":
+        import json
+        import sys
+        from ai_docs_toolkit.review import check_review, format_review_human
+
+        review_args = _parse_review_args(args)
+        if review_args is None:
+            print("Usage: ai-docs review-check RECORD [--record N] [--format json|--json]", file=sys.stderr)
+            return 3
+        path, number, output_format = review_args
+        result = check_review(path, ".", record_number=number)
+        print(json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True)
+              if output_format == "json" else format_review_human(result))
+        return result["exit_code"]
+
     init_args = _parse_init_args(args)
     if init_args is not None:
         profile, force, dry_run, check = init_args
@@ -1151,3 +1167,30 @@ def _parse_planning_args(args: list[str]):
         parsed["--task-id"],
         plan_date,
     )
+
+
+def _parse_review_args(args):
+    if len(args) < 2 or args[1].startswith('-'):
+        return None
+    options = {}
+    index = 2
+    while index < len(args):
+        option = args[index]
+        if option not in {'--record', '--format', '--json'} or option in options:
+            return None
+        if option == '--json':
+            options[option] = True
+            index += 1
+        elif index + 1 < len(args):
+            options[option] = args[index + 1]
+            index += 2
+        else:
+            return None
+    if '--format' in options and ('--json' in options or options['--format'] != 'json'):
+        return None
+    number = options.get('--record')
+    if number is not None:
+        if not number.isascii() or not number.isdigit() or len(number) > 9 or int(number) < 1:
+            return None
+        number = int(number)
+    return args[1], number, 'json' if '--format' in options or '--json' in options else 'human'

{ai_docs_toolkit-0.2.0 → ai_docs_toolkit-0.3.0}/src/ai_docs_toolkit/core/changed_files.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import subprocess
 from dataclasses import dataclass
 from fnmatch import fnmatchcase
@@ -50,11 +51,12 @@ def read_git_changed_files(
     base_ref: str | None = None,
 ) -> GitChangedFilesResult:
     process = subprocess.run(
-        ["git", "status", "--porcelain", "--untracked-files=all"],
+        ["git", "status", "--porcelain", "-z", "--untracked-files=all"],
         cwd=root,
         capture_output=True,
         text=True,
         check=False,
+        env={**os.environ, "GIT_OPTIONAL_LOCKS": "0"},
     )
     if process.returncode != 0:
         return GitChangedFilesResult(
@@ -69,20 +71,23 @@ def read_git_changed_files(
             ),
         )
 
-    changed_files = set(parse_git_status_porcelain(process.stdout))
+    changed_files = set(_parse_git_status_z(process.stdout))
     if base_ref is not None:
         diff_process = subprocess.run(
             [
                 "git",
                 "diff",
                 "--name-only",
-                "--diff-filter=ACMRTUXB",
+                "-z",
+                "--no-renames",
+                "--diff-filter=ACDMRTUXB",
                 f"{base_ref}...HEAD",
             ],
             cwd=root,
             capture_output=True,
             text=True,
             check=False,
+            env={**os.environ, "GIT_OPTIONAL_LOCKS": "0"},
         )
         if diff_process.returncode != 0:
             return GitChangedFilesResult(
@@ -97,12 +102,26 @@ def read_git_changed_files(
                 ),
             )
         changed_files.update(
-            path for path in diff_process.stdout.splitlines() if path
+            path for path in diff_process.stdout.split("\0") if path
         )
 
     return GitChangedFilesResult(changed_files=tuple(sorted(changed_files)))
 
 
+def _parse_git_status_z(output: str) -> tuple[str, ...]:
+    fields = iter(output.split("\0"))
+    paths = []
+    for entry in fields:
+        if len(entry) < 4:
+            continue
+        paths.append(entry[3:])
+        if "R" in entry[:2] or "C" in entry[:2]:
+            original = next(fields, "")
+            if original:
+                paths.append(original)
+    return tuple(paths)
+
+
 def parse_git_status_porcelain(output: str) -> tuple[str, ...]:
     changed_files: list[str] = []
     for line in output.splitlines():

{ai_docs_toolkit-0.2.0 → ai_docs_toolkit-0.3.0}/src/ai_docs_toolkit/core/impact.py

@@ -15,6 +15,7 @@ IMPACT_TRANSITIONS: dict[str, frozenset[str]] = {
             "module",
             "scenario",
             "acceptance",
+            "test_case",
             "guide",
             "operation",
             "runbook",
@@ -37,8 +38,8 @@ IMPACT_TRANSITIONS: dict[str, frozenset[str]] = {
     "module": frozenset(
         {"contract", "scenario", "acceptance", "guide", "operation", "runbook"}
     ),
-    "scenario": frozenset({"acceptance", "guide", "operation", "runbook"}),
-    "acceptance": frozenset({"operation", "runbook"}),
+    "scenario": frozenset({"acceptance", "test_case", "guide", "operation", "runbook"}),
+    "acceptance": frozenset({"test_case", "operation", "runbook"}),
     "guide": frozenset({"operation", "runbook"}),
     "operation": frozenset(),
     "runbook": frozenset({"operation"}),

{ai_docs_toolkit-0.2.0 → ai_docs_toolkit-0.3.0}/src/ai_docs_toolkit/docs/agent-installation.md

@@ -31,7 +31,7 @@ Required behavior:
 
 Use Python 3.14 or newer.
 
-Version 0.2.0 and the development baseline require Python 3.14+.
+Versions 0.2.0 and later require Python 3.14+.
 Previously published versions retain their declared requirements. Before
 upgrading, recreate an older project environment with Python 3.14+, reinstall
 its dependencies and rerun its checks; updating documentation does not change
@@ -47,7 +47,7 @@ ai-docs --version
 Pinned install:
 
 ```bash
-python -m pip install "ai-docs-toolkit==0.2.0"
+python -m pip install "ai-docs-toolkit==0.3.0"
 ai-docs --version
 ```
 
@@ -156,6 +156,128 @@ reinstall the previously recorded package/environment, and preserve retained
 planning records. Package rollback does not reverse archive moves or external
 effects. Keep package versions and artifact hashes with the migration evidence.
 
+## Migration 0.2.0 To 0.3.0
+
+From: `0.2.0`. To: `0.3.0`. Consumers on `0.1.0` must first apply the Python
+3.14 and archive-retention prerequisites in “Migration 0.1.0 To 0.2.0”; they
+may install 0.3.0 directly after reviewing both sets of managed changes.
+Run the exact installation only once 0.3.0 is available on the selected index.
+
+Record `ai-docs --version`, `ai-docs doctor --format json`, `ai-docs init --check`
+and existing project validation findings. Preserve a Git diff or backup of
+`AGENTS.md`, config, `.ai-docs/local/`, `.ai-docs/managed-files.json`, managed
+instructions, planning records and saved review evidence before upgrading.
+
+Use the project's existing installer with Python 3.14+:
+
+```bash
+python --version
+python -m pip install --upgrade "ai-docs-toolkit==0.3.0"
+# MCP users install the complete extra instead:
+python -m pip install --upgrade "ai-docs-toolkit[mcp]==0.3.0"
+# Isolated CLI alternatives:
+pipx install --force --python python3.14 "ai-docs-toolkit==0.3.0"
+uvx --python 3.14 --from ai-docs-toolkit==0.3.0 ai-docs --version
+ai-docs --version
+ai-docs init --check
+ai-docs init --dry-run
+```
+
+Expect version 0.3.0. Reconnect long-lived MCP clients. The managed refresh
+updates `.ai-docs/skills/documentation-change-review/SKILL.md` and
+`.ai-docs/reference/documentation-change-review-skill.md`. No new bootstrap
+paths, schema, mandatory review records or task moves are introduced. Keep
+document/task ids, relationship links, registry paths, archives and project
+rules. Reconcile locally modified or provenance-missing managed files before
+applying `init`; preserve local overrides instead of using blanket `--force`.
+
+Review strict JSON consumers for the new changed-mode `coverage` field and
+integrations that assume fixed impacted-document types/counts. The following
+sections describe review-check, coverage and linked test-case behavior.
+Do not refresh a saved record's `tool` or hashes merely to clear findings:
+preserve historical rounds and create a new round after reviewing current
+inputs, candidates and decisions. Free-form old tool descriptions remain
+unverifiable. A version upgrade changes the checker identity even when project
+files are unchanged.
+
+After reviewing the refresh:
+
+```bash
+ai-docs init
+ai-docs validate --json
+ai-docs doctor --format json
+ai-docs init --check
+ai-docs impact --changed --format json
+```
+
+Expect successful validation, no unexpected doctor findings and no outstanding
+managed refresh. In a Git project, inspect coverage and preserve unmapped-path
+warnings. Also run `ai-docs impact --id <known-rule-or-acceptance-id> --format
+json` with a real project id and inspect its explicit TC links. If a saved
+review exists, run `ai-docs review-check <record-path> --format json`; findings
+about an older tool are expected and need review, not automatic evidence edits.
+Keep independent project tests/review gates. Stop for owner review on unmanaged
+rewrites, unresolved local-policy conflicts or new validation errors.
+
+For rollback, restore reviewed managed files and their manifest together,
+reinstall the recorded previous package/environment and reconnect MCP clients.
+Keep project ids, links, task history and review rounds. An executable downgrade
+does not reverse manual edits or external effects; consumers using the new CLI
+or JSON field must also revert that integration. Record package/artifact hashes
+and validation results with the upgrade evidence.
+
+### Optional Review Evidence (0.3.0)
+
+Version 0.3.0 adds an optional YAML review record and a separate read-only
+`ai-docs review-check RECORD [--format json]` command. Use a YAML file or a fenced
+YAML block in existing Markdown; select multiple rounds with `--record N`.
+The checker reports missing/open decisions, stale/missing input hashes and
+changed sources/candidates. Copy `current_tool` from its output when recording
+the verified tool state; older free-form tool descriptions are unverifiable.
+Changed review needs a pinned Git base. Git discovery now preserves literal
+Unicode/whitespace paths and deleted/renamed paths, with optional index writes
+disabled. Deleted owned implementation files can become impact sources.
+
+The selected standalone YAML record can be stored in Git without a self-hash
+or ignore rule. Other changed paths still need hashes. If a Markdown container
+is also a required input, `review.record_is_input` asks you to move the record
+to separate YAML and hash the complete Markdown there. Discovery warnings remain
+visible; moving evidence does not prove complete impact coverage.
+
+The command adds no required document or schema migration; `ai-docs validate`
+does not validate these records. Exit 0 means no mechanical discrepancy, 1 means
+findings/invalid record, and 2/3/4 mean config/usage/unavailable evidence. It does
+not approve semantic consistency or external state. Keep independent review gates.
+
+### Changed Impact Coverage (0.3.0)
+
+`ai-docs impact --changed` now summarizes changed paths, paths resolved as
+documents or through module ownership, unique source document IDs and unmapped
+paths with reasons. JSON adds a `coverage` object only for `--changed`; clients
+that require exact top-level keys should accept this addition. Human output adds
+a coverage section. Unavailable Git/config produces null counts rather than zero.
+Existing provenance, warnings/errors, exit codes and `--id` output are preserved.
+
+This summary measures discovery, not semantic completeness or test execution.
+Updating the executable enables it; no new metadata, managed template, bootstrap
+file-list change or `init` migration is required. Review records remain optional;
+a changed executable identity requires review before refreshing their tool state.
+
+### Test Case Impact (0.3.0)
+
+Version 0.3.0 includes linked `test_case` documents in impact results from
+`business_rule`, `scenario` and `acceptance`. On a test case, use the existing
+`related.business_rules`, `related.scenarios` or `related.acceptance` ids.
+No front matter migration, new relationship group or managed-file refresh is
+required for this behavior. Updating the toolkit executable enables it.
+
+Review integrations that assume a fixed impacted-document count or type list.
+The JSON shape stays the same; a rule linked to acceptance can now reach a test
+case referencing that acceptance. Test cases end impact traversal and do not
+serve as bridges to their other sources. A returned test case is a review
+candidate, not evidence that a test ran or passed. Existing links remain valid;
+missing links still require manual review.
+
 ## Scoped Authorization Update (0.1.0)
 
 This update preserves an existing session/task assignment across tools, skills