ai-docs-toolkit 0.3.2__tar.gz → 0.4.0__tar.gz

{ai_docs_toolkit-0.3.2 → ai_docs_toolkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-docs-toolkit
-Version: 0.3.2
+Version: 0.4.0
 Summary: AI-oriented documentation toolkit.
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -30,13 +30,15 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.3.2 includes:
+Version 0.4.0 includes:
 
 - schema and structure validation for Markdown documents with YAML front matter;
 - document graph output;
 - impact analysis with linked test cases and changed-path discovery coverage;
 - optional saved review evidence and the read-only `ai-docs review-check` command;
 - an optional convention for documentation links beside key code;
+- the opt-in `ai-docs code-links-check` command for Python comment paths and primary IDs;
+- test-evidence review connecting requirements to assertions and proportionate sensitivity checks;
 - context bundle output;
 - an executable `ai-docs` CLI;
 - optional local MCP runtime entrypoint.
@@ -46,26 +48,59 @@ Version 0.3.2 includes:
 Install this version with Python 3.14 or newer once it is available on PyPI:
 
 ```bash
-python -m pip install ai-docs-toolkit==0.3.2
+python -m pip install ai-docs-toolkit==0.4.0
 ai-docs --version
 ```
 
 For ephemeral execution with `uvx`:
 
 ```bash
-uvx --python 3.14 --from ai-docs-toolkit==0.3.2 ai-docs --version
+uvx --python 3.14 --from ai-docs-toolkit==0.4.0 ai-docs --version
 ```
 
 For the optional local MCP runtime:
 
 ```bash
-python -m pip install "ai-docs-toolkit[mcp]==0.3.2"
+python -m pip install "ai-docs-toolkit[mcp]==0.4.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.
 
+## Release 0.4.0
+
+`ai-docs code-links-check FILE... --format json` checks documentation paths and
+primary IDs in real Python comments without importing code or changing files.
+Explicit files, repository boundaries and unverified inputs remain visible;
+strings/docstrings are ignored and links remain optional. Semantic agreement
+between documentation, comments, implementation and tests still requires review.
+The command does not add a gate to ordinary validation or new graph edges.
+
+After upgrading from 0.3.3, inspect `init --check` and `--dry-run`, then refresh the
+existing authoring reference with `init`. Preserve local rules, project documents
+and review history; no schema or bulk annotation migration is required. Minimal
+profile needs no reference refresh. See “Migration 0.3.3 To 0.4.0” in the packaged
+`ai_docs_toolkit/docs/agent-installation.md` for commands, checks and rollback.
+
+## Release 0.3.3
+
+Documentation change review now traces material requirements to test inputs and
+specific assertions. Review depth depends on impact and uncertainty; a concrete
+risk of masked violations calls for a focused check within existing authority.
+For a deliberate weakening, verify that the test fails for the intended reason
+against the altered code. Preserve limitations and historical evidence.
+The code-link convention points to this rule. No universal mutation-testing
+requirement, CLI/schema change or mandatory CI gate is introduced.
+
+After upgrading from 0.3.2, inspect `ai-docs init --check` and `--dry-run`, reconcile
+local policy and run `ai-docs init` to refresh two existing agent references:
+documentation change review and documentation cascade authoring. Existing project
+files and AGENTS.md are preserved. Minimal-profile consumers need no reference
+refresh; managed provenance records the new version. Verify validation, doctor,
+init state and project-specific checks. See “Migration 0.3.2 To 0.3.3” in the
+packaged `ai_docs_toolkit/docs/agent-installation.md` for commands and rollback.
+
 ## Release 0.3.2
 
 An optional comment convention links key operations and structures to their
@@ -286,6 +321,12 @@ Check optional saved review evidence:
 ai-docs review-check review.yaml --format json
 ```
 
+Check existing documentation links in selected Python files:
+
+```bash
+ai-docs code-links-check src/example.py --format json
+```
+
 Prepare an agent context bundle for changed files:
 
 ```bash

{ai_docs_toolkit-0.3.2 → ai_docs_toolkit-0.4.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.3.2 is prepared with an optional convention for links from key code to its documentation, alongside rollback guidance, linked test cases, changed-path coverage and optional review evidence checks. Python 3.14 or newer is required.
+It treats documentation as an engineering interface between humans, AI agents, code, tests and change management. Version 0.4.0 adds an optional checker for documentation IDs and paths in Python comments, alongside test-evidence review, rollback guidance, linked test cases, changed-path coverage and optional review evidence checks. Python 3.14 or newer is required.
 
 ## Purpose
 
@@ -83,9 +83,10 @@ pipx install ai-docs-toolkit
 uvx --from ai-docs-toolkit ai-docs validate
 ```
 
-For upgrades from 0.3.1 to 0.3.2, follow the [consumer migration guide](src/ai_docs_toolkit/docs/agent-installation.md#migration-031-to-032).
-Install the exact version only after it is available on PyPI; a source preparation
-commit does not publish the package. Consumers on 0.3.0 must also read the
+For upgrades from 0.3.3 to 0.4.0, follow the [consumer migration guide](src/ai_docs_toolkit/docs/agent-installation.md#migration-033-to-040).
+Consumers on 0.3.1 must also read the
+[0.3.2 migration](src/ai_docs_toolkit/docs/agent-installation.md#migration-031-to-032).
+Consumers on 0.3.0 must also read the
 [0.3.1 migration](src/ai_docs_toolkit/docs/agent-installation.md#migration-030-to-031).
 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);
@@ -95,13 +96,20 @@ Use Python 3.14+, review managed-file changes and preserve existing project rule
 and task records before refreshing. Completed standalone tasks are archived;
 tasks in a plan remain in place until the whole plan is archived.
 
+Version 0.4.0 is prepared for publication; [0.3.3 remains available on Public PyPI](https://pypi.org/project/ai-docs-toolkit/0.3.3/). The
+[test-evidence review rule](.ai-docs/reference/documentation-change-review-skill.md#test-evidence-review)
+connects material requirements to test setup and assertions. A concrete risk of
+masked violations calls for a proportionate check within existing authority.
+Agent-profile consumers refresh two managed references; the migration guide
+describes preservation, verification and rollback.
+
 Version 0.3.2 adds an optional short explanation, document ID and path from the
 Git repository root beside key operations and structures. The
 [canonical convention](.ai-docs/reference/documentation-cascade-authoring-skill.md#optional-code-documentation-links)
 preserves documentation as primary and requires semantic review of existing
 comments. Agent-profile consumers refresh two managed references and may manually
 merge the pointer into their existing AGENTS.md. No parser or mandatory gate is added.
-This version is prepared in source; publication is a separate step.
+[Version 0.3.2 is available on Public PyPI](https://pypi.org/project/ai-docs-toolkit/0.3.2/).
 
 Version 0.3.1 includes a clarification of
 [rollback verification](src/ai_docs_toolkit/docs/agent-installation.md#rollback-verification):
@@ -171,6 +179,15 @@ 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.
 
+Version 0.4.0 provides an optional check for existing Python code links:
+
+```bash
+ai-docs code-links-check src/example.py --format json
+```
+
+Run from the Git root with explicit files. This checks paths and primary IDs,
+without importing code or assessing semantic agreement. See the [code-link contract](.ai-docs/reference/documentation-cascade-authoring-skill.md#code-link-checker).
+
 Prepare an agent context bundle for changed files:
 
 ```bash

{ai_docs_toolkit-0.3.2 → ai_docs_toolkit-0.4.0}/packaging/pypi/README.md

@@ -16,13 +16,15 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.3.2 includes:
+Version 0.4.0 includes:
 
 - schema and structure validation for Markdown documents with YAML front matter;
 - document graph output;
 - impact analysis with linked test cases and changed-path discovery coverage;
 - optional saved review evidence and the read-only `ai-docs review-check` command;
 - an optional convention for documentation links beside key code;
+- the opt-in `ai-docs code-links-check` command for Python comment paths and primary IDs;
+- test-evidence review connecting requirements to assertions and proportionate sensitivity checks;
 - context bundle output;
 - an executable `ai-docs` CLI;
 - optional local MCP runtime entrypoint.
@@ -32,26 +34,59 @@ Version 0.3.2 includes:
 Install this version with Python 3.14 or newer once it is available on PyPI:
 
 ```bash
-python -m pip install ai-docs-toolkit==0.3.2
+python -m pip install ai-docs-toolkit==0.4.0
 ai-docs --version
 ```
 
 For ephemeral execution with `uvx`:
 
 ```bash
-uvx --python 3.14 --from ai-docs-toolkit==0.3.2 ai-docs --version
+uvx --python 3.14 --from ai-docs-toolkit==0.4.0 ai-docs --version
 ```
 
 For the optional local MCP runtime:
 
 ```bash
-python -m pip install "ai-docs-toolkit[mcp]==0.3.2"
+python -m pip install "ai-docs-toolkit[mcp]==0.4.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.
 
+## Release 0.4.0
+
+`ai-docs code-links-check FILE... --format json` checks documentation paths and
+primary IDs in real Python comments without importing code or changing files.
+Explicit files, repository boundaries and unverified inputs remain visible;
+strings/docstrings are ignored and links remain optional. Semantic agreement
+between documentation, comments, implementation and tests still requires review.
+The command does not add a gate to ordinary validation or new graph edges.
+
+After upgrading from 0.3.3, inspect `init --check` and `--dry-run`, then refresh the
+existing authoring reference with `init`. Preserve local rules, project documents
+and review history; no schema or bulk annotation migration is required. Minimal
+profile needs no reference refresh. See “Migration 0.3.3 To 0.4.0” in the packaged
+`ai_docs_toolkit/docs/agent-installation.md` for commands, checks and rollback.
+
+## Release 0.3.3
+
+Documentation change review now traces material requirements to test inputs and
+specific assertions. Review depth depends on impact and uncertainty; a concrete
+risk of masked violations calls for a focused check within existing authority.
+For a deliberate weakening, verify that the test fails for the intended reason
+against the altered code. Preserve limitations and historical evidence.
+The code-link convention points to this rule. No universal mutation-testing
+requirement, CLI/schema change or mandatory CI gate is introduced.
+
+After upgrading from 0.3.2, inspect `ai-docs init --check` and `--dry-run`, reconcile
+local policy and run `ai-docs init` to refresh two existing agent references:
+documentation change review and documentation cascade authoring. Existing project
+files and AGENTS.md are preserved. Minimal-profile consumers need no reference
+refresh; managed provenance records the new version. Verify validation, doctor,
+init state and project-specific checks. See “Migration 0.3.2 To 0.3.3” in the
+packaged `ai_docs_toolkit/docs/agent-installation.md` for commands and rollback.
+
 ## Release 0.3.2
 
 An optional comment convention links key operations and structures to their
@@ -272,6 +307,12 @@ Check optional saved review evidence:
 ai-docs review-check review.yaml --format json
 ```
 
+Check existing documentation links in selected Python files:
+
+```bash
+ai-docs code-links-check src/example.py --format json
+```
+
 Prepare an agent context bundle for changed files:
 
 ```bash

{ai_docs_toolkit-0.3.2 → ai_docs_toolkit-0.4.0}/pyproject.toml

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

{ai_docs_toolkit-0.3.2 → ai_docs_toolkit-0.4.0}/src/ai_docs_toolkit/__init__.py

@@ -1,3 +1,3 @@
 """AI Docs Toolkit package baseline."""
 
-__version__ = "0.3.2"
+__version__ = "0.4.0"

{ai_docs_toolkit-0.3.2 → ai_docs_toolkit-0.4.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 code-links-check FILE... [--format human|json|--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]",
@@ -117,6 +118,21 @@ def main(argv: list[str] | None = None) -> int:
         print(__version__)
         return 0
 
+    if args[0] == "code-links-check":
+        import json
+        import sys
+        from ai_docs_toolkit.core.code_links import check_code_links, format_code_links_human
+
+        parsed = _parse_code_links_args(args[1:])
+        if parsed is None:
+            print("Usage: ai-docs code-links-check FILE... [--format human|json|--json]", file=sys.stderr)
+            return 3
+        paths, output_format = parsed
+        result = check_code_links(paths, ".")
+        print(json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True)
+              if output_format == "json" else format_code_links_human(result))
+        return result["exit_code"]
+
     if args[0] == "review-check":
         import json
         import sys
@@ -1194,3 +1210,27 @@ def _parse_review_args(args):
             return None
         number = int(number)
     return args[1], number, 'json' if '--format' in options or '--json' in options else 'human'
+
+
+def _parse_code_links_args(args: list[str]) -> tuple[list[str], str] | None:
+    paths = []
+    output_format = None
+    index = 0
+    while index < len(args):
+        item = args[index]
+        if item in ("--json", "--format"):
+            if output_format is not None:
+                return None
+            if item == "--json":
+                output_format = "json"
+            else:
+                index += 1
+                if index >= len(args) or args[index] not in ("human", "json"):
+                    return None
+                output_format = args[index]
+        elif item.startswith("-"):
+            return None
+        else:
+            paths.append(item)
+        index += 1
+    return (paths, output_format or "human") if paths else None