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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-docs-toolkit
-Version: 0.2.0
+Version: 0.3.1
 Summary: AI-oriented documentation toolkit.
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -30,40 +30,80 @@ 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.1 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.
 
 ## Installation
 
-Install the stable release with Python 3.14 or newer:
+Install this version with Python 3.14 or newer once it is available on PyPI:
 
 ```bash
-python -m pip install ai-docs-toolkit==0.2.0
+python -m pip install ai-docs-toolkit==0.3.1
 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.1 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.1"
 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.1
+
+The package installation guide now describes preserving review/evidence before
+revert and verifying the restored files and environment. See
+`ai_docs_toolkit/docs/agent-installation.md`, “Rollback Verification”.
+The patch requires no managed-file refresh, schema or project-data migration
+from 0.3.0. After installation, verify the version, run `ai-docs validate --json`,
+`ai-docs doctor --format json`, `ai-docs init --check`, and the project's checks.
+Preserve historical review rounds: the version change causes `tool_changed`
+findings even when project files are unchanged. See “Migration 0.3.0 To 0.3.1”
+in the packaged guide for installation and verification commands.
+
+## 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 +261,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 +313,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.1}/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.1 clarifies rollback verification, alongside the linked test cases, changed-path coverage and optional review evidence checks introduced in 0.3.0. Python 3.14 or newer is required.
 
 ## Purpose
 
@@ -83,11 +83,22 @@ 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 from 0.3.0 to 0.3.1, follow the [consumer migration guide](src/ai_docs_toolkit/docs/agent-installation.md#migration-030-to-031).
+Install the exact version only after it is available on PyPI; a source preparation
+commit does not publish the package. Consumers on 0.2.0 must also apply the
+[0.3.0 migration](src/ai_docs_toolkit/docs/agent-installation.md#migration-020-to-030);
+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.
 
+The 0.3.1 release preparation includes a clarification of
+[rollback verification](src/ai_docs_toolkit/docs/agent-installation.md#rollback-verification):
+preserve review/evidence before revert, then check restored files and the actual
+environment. No managed-file refresh or data migration is required for this
+clarification. Publication is pending; the published 0.3.0 package is unchanged.
+
 Docker, npm/npx and standalone binary distribution are deferred.
 See [Distribution Strategy](.ai-docs/reference/distribution-strategy.md) for supported and deferred channels.
 
@@ -135,6 +146,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.1}/packaging/pypi/README.md

@@ -16,40 +16,80 @@ 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.1 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.
 
 ## Installation
 
-Install the stable release with Python 3.14 or newer:
+Install this version with Python 3.14 or newer once it is available on PyPI:
 
 ```bash
-python -m pip install ai-docs-toolkit==0.2.0
+python -m pip install ai-docs-toolkit==0.3.1
 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.1 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.1"
 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.1
+
+The package installation guide now describes preserving review/evidence before
+revert and verifying the restored files and environment. See
+`ai_docs_toolkit/docs/agent-installation.md`, “Rollback Verification”.
+The patch requires no managed-file refresh, schema or project-data migration
+from 0.3.0. After installation, verify the version, run `ai-docs validate --json`,
+`ai-docs doctor --format json`, `ai-docs init --check`, and the project's checks.
+Preserve historical review rounds: the version change causes `tool_changed`
+findings even when project files are unchanged. See “Migration 0.3.0 To 0.3.1”
+in the packaged guide for installation and verification commands.
+
+## 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 +247,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 +299,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.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-docs-toolkit"
-version = "0.2.0"
+version = "0.3.1"
 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.1}/src/ai_docs_toolkit/__init__.py

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

{ai_docs_toolkit-0.2.0 → ai_docs_toolkit-0.3.1}/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.1}/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.1}/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"}),