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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-docs-toolkit
-Version: 0.3.1
+Version: 0.3.3
 Summary: AI-oriented documentation toolkit.
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -30,12 +30,14 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.3.1 includes:
+Version 0.3.3 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;
+- test-evidence review connecting requirements to assertions and proportionate sensitivity checks;
 - context bundle output;
 - an executable `ai-docs` CLI;
 - optional local MCP runtime entrypoint.
@@ -45,26 +47,62 @@ Version 0.3.1 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.1
+python -m pip install ai-docs-toolkit==0.3.3
 ai-docs --version
 ```
 
 For ephemeral execution with `uvx`:
 
 ```bash
-uvx --python 3.14 --from ai-docs-toolkit==0.3.1 ai-docs --version
+uvx --python 3.14 --from ai-docs-toolkit==0.3.3 ai-docs --version
 ```
 
 For the optional local MCP runtime:
 
 ```bash
-python -m pip install "ai-docs-toolkit[mcp]==0.3.1"
+python -m pip install "ai-docs-toolkit[mcp]==0.3.3"
 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.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
+documentation through a short explanation, document ID and a path from the Git
+repository root. Documentation remains primary; file/ID checks do not prove
+semantic consistency or full implementation of the linked document. Review the
+document, comment, implementation and applicable tests before committing changes.
+This adds no parser, mandatory annotation or CI gate.
+
+After upgrading from 0.3.1, inspect `ai-docs init --check` and `--dry-run`, reconcile
+local policy and refresh the agent profile with `ai-docs init`. Two managed
+references change: documentation cascade authoring and documentation change review.
+Existing AGENTS.md is preserved; manually merge its optional pointer if useful.
+Minimal-profile projects require no reference refresh. Preserve local rules,
+project documents and historical review rounds; verify the version, validation,
+doctor, init state and project checks. See “Migration 0.3.1 To 0.3.2” in the
+packaged `ai_docs_toolkit/docs/agent-installation.md` for exact commands and rollback.
+
 ## Release 0.3.1
 
 The package installation guide now describes preserving review/evidence before

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.3}/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.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.
+It treats documentation as an engineering interface between humans, AI agents, code, tests and change management. Source version 0.3.3 refines test-evidence review, alongside optional code documentation links, rollback guidance, linked test cases, changed-path coverage and optional review evidence checks. Python 3.14 or newer is required.
 
 ## Purpose
 
@@ -83,9 +83,13 @@ pipx install ai-docs-toolkit
 uvx --from ai-docs-toolkit ai-docs validate
 ```
 
-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).
+For upgrades from 0.3.2 to 0.3.3, follow the [consumer migration guide](src/ai_docs_toolkit/docs/agent-installation.md#migration-032-to-033).
 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
+commit does not publish the package. 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);
 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).
@@ -93,11 +97,27 @@ 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.
 
-The 0.3.1 release preparation includes a clarification of
+Version 0.3.3 is prepared in source and awaits publication approval; the latest
+published version remains 0.3.2. 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.
+[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):
 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.
+clarification. [Version 0.3.1 is available on Public PyPI](https://pypi.org/project/ai-docs-toolkit/0.3.1/).
 
 Docker, npm/npx and standalone binary distribution are deferred.
 See [Distribution Strategy](.ai-docs/reference/distribution-strategy.md) for supported and deferred channels.

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.3}/packaging/pypi/README.md

@@ -16,12 +16,14 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.3.1 includes:
+Version 0.3.3 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;
+- test-evidence review connecting requirements to assertions and proportionate sensitivity checks;
 - context bundle output;
 - an executable `ai-docs` CLI;
 - optional local MCP runtime entrypoint.
@@ -31,26 +33,62 @@ Version 0.3.1 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.1
+python -m pip install ai-docs-toolkit==0.3.3
 ai-docs --version
 ```
 
 For ephemeral execution with `uvx`:
 
 ```bash
-uvx --python 3.14 --from ai-docs-toolkit==0.3.1 ai-docs --version
+uvx --python 3.14 --from ai-docs-toolkit==0.3.3 ai-docs --version
 ```
 
 For the optional local MCP runtime:
 
 ```bash
-python -m pip install "ai-docs-toolkit[mcp]==0.3.1"
+python -m pip install "ai-docs-toolkit[mcp]==0.3.3"
 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.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
+documentation through a short explanation, document ID and a path from the Git
+repository root. Documentation remains primary; file/ID checks do not prove
+semantic consistency or full implementation of the linked document. Review the
+document, comment, implementation and applicable tests before committing changes.
+This adds no parser, mandatory annotation or CI gate.
+
+After upgrading from 0.3.1, inspect `ai-docs init --check` and `--dry-run`, reconcile
+local policy and refresh the agent profile with `ai-docs init`. Two managed
+references change: documentation cascade authoring and documentation change review.
+Existing AGENTS.md is preserved; manually merge its optional pointer if useful.
+Minimal-profile projects require no reference refresh. Preserve local rules,
+project documents and historical review rounds; verify the version, validation,
+doctor, init state and project checks. See “Migration 0.3.1 To 0.3.2” in the
+packaged `ai_docs_toolkit/docs/agent-installation.md` for exact commands and rollback.
+
 ## Release 0.3.1
 
 The package installation guide now describes preserving review/evidence before

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.3}/pyproject.toml

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

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.3}/src/ai_docs_toolkit/__init__.py

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

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.3}/src/ai_docs_toolkit/docs/agent-installation.md

@@ -47,7 +47,7 @@ ai-docs --version
 Pinned install:
 
 ```bash
-python -m pip install "ai-docs-toolkit==0.3.1"
+python -m pip install "ai-docs-toolkit==0.3.3"
 ai-docs --version
 ```
 
@@ -89,6 +89,164 @@ bulk task deletion is required. Detailed migration and rollback guidance is in
 the installed `.ai-docs/reference/planning-document-model.md`, under
 “Consumer Migration: Proportionate Workflow”.
 
+## Migration 0.3.2 To 0.3.3
+
+From: `0.3.2`. To: `0.3.3`. Install the target version only once it is available
+on the selected index. Python 3.14+ remains required; consumers on older versions
+must also apply the relevant migration sections below.
+
+This patch refines review of executable test evidence: connect material
+requirements to test setup and assertions, and investigate a concrete risk of
+masked violations with a proportionate check. The canonical rule is in
+`.ai-docs/reference/documentation-change-review-skill.md`, under
+“Test Evidence Review”; the code-link convention points to it.
+
+Before installation, record the current version, validation/doctor findings and
+managed-file state. Preserve project files, ids, links, task registry/archive,
+saved review evidence, local rules and a Git diff or backup of managed policy,
+`.ai-docs/managed-files.json` and `AGENTS.md`.
+The commands below use the agent profile. Minimal-profile consumers add
+`--profile minimal` to each `ai-docs init` command; no reference refresh is needed,
+but applying init records the new version in managed-file provenance.
+
+```bash
+python --version
+ai-docs --version
+ai-docs validate --json
+ai-docs doctor --format json
+ai-docs init --check
+```
+
+Use the project's existing installer and update its version pin when applicable:
+
+```bash
+python -m pip install --upgrade "ai-docs-toolkit==0.3.3"
+# MCP users install the complete extra instead:
+python -m pip install --upgrade "ai-docs-toolkit[mcp]==0.3.3"
+# Isolated CLI alternatives:
+pipx install --force --python python3.14 "ai-docs-toolkit==0.3.3"
+uvx --python 3.14 --from ai-docs-toolkit==0.3.3 ai-docs --version
+```
+
+Reconnect long-lived MCP clients. Inspect `ai-docs init --check` and
+`ai-docs init --dry-run` with the upgraded runtime. Agent-profile refresh from
+unmodified 0.3.2 updates exactly two existing managed references:
+
+- `.ai-docs/reference/documentation-change-review-skill.md`;
+- `.ai-docs/reference/documentation-cascade-authoring-skill.md`.
+
+Reconcile local policy before `ai-docs init`; stop for owner review on unresolved
+policy conflicts, unexpected project rewrites or new validation errors. Do not
+use blanket `--force`. Existing AGENTS.md and `.ai-docs/local/**` are preserved;
+no new AGENTS pointer is needed when upgrading from 0.3.2.
+Refresh also updates `.ai-docs/managed-files.json`. After reconciliation:
+
+```bash
+ai-docs init
+ai-docs --version
+ai-docs validate --json
+ai-docs doctor --format json
+ai-docs init --check
+python -m pip check
+```
+
+Expect version 0.3.3, successful validation and no unexpected doctor or managed
+findings; retain and disposition pre-existing findings. Run project-specific
+tests and `pip check` in the environment that owns the installation.
+If a saved review exists, run `ai-docs review-check <record-path> --format json`.
+The version change alters checker identity; refreshed references can also change
+review inputs. Preserve historical rounds and review current inputs, candidates
+and decisions before recording a new round. Do not rewrite hashes or tool
+identity merely to clear findings.
+
+Existing code comments remain compatible. This patch adds no managed paths,
+CLI/schema or review-record changes, project-data migration or mandatory CI gate.
+For rollback, restore the preserved pre-refresh files/diff and manifest under
+[Rollback Verification](#rollback-verification); package downgrade alone does not
+restore refreshed policy. Retain evidence before reverting and verify the actual
+restored environment with the project's independent checks.
+
+## Migration 0.3.1 To 0.3.2
+
+From: `0.3.1`. To: `0.3.2`. Install the target version only once it is available
+on the selected index. Python 3.14+ remains required; consumers on older versions
+must also apply the relevant migration sections below.
+
+This patch adds an optional convention for comments beside key code:
+a short explanation, document ID and repository-root-relative path. The rule
+is in `.ai-docs/reference/documentation-cascade-authoring-skill.md`, under
+“Optional Code Documentation Links”; change-review guidance links to that owner.
+
+Before installation, record the current version, validation/doctor findings and
+managed-file state. Preserve project files, ids, links, task registry/archive,
+saved review evidence, local rules and a Git diff or backup of managed policy,
+`.ai-docs/managed-files.json` and `AGENTS.md`.
+The commands below use the agent profile. For a minimal-profile project, add
+`--profile minimal` to each `ai-docs init` command; no reference refresh is needed.
+
+```bash
+python --version
+ai-docs --version
+ai-docs validate --json
+ai-docs doctor --format json
+ai-docs init --check
+```
+
+Use the project's existing installer and update its version pin when applicable:
+
+```bash
+python -m pip install --upgrade "ai-docs-toolkit==0.3.2"
+# MCP users install the complete extra instead:
+python -m pip install --upgrade "ai-docs-toolkit[mcp]==0.3.2"
+# Isolated CLI alternatives:
+pipx install --force --python python3.14 "ai-docs-toolkit==0.3.2"
+uvx --python 3.14 --from ai-docs-toolkit==0.3.2 ai-docs --version
+```
+
+Reconnect long-lived MCP clients. Inspect `ai-docs init --check` and
+`ai-docs init --dry-run` with the upgraded runtime. Agent-profile refresh from
+unmodified 0.3.1 updates exactly two existing managed references:
+
+- `.ai-docs/reference/documentation-cascade-authoring-skill.md`;
+- `.ai-docs/reference/documentation-change-review-skill.md`.
+
+Reconcile local policy changes before `ai-docs init`; stop for owner review on
+unresolved policy conflicts, unexpected project rewrites or new validation errors.
+Do not use blanket `--force`. Refresh also updates managed-file provenance.
+Existing `AGENTS.md` is preserved by default; manually merge this pointer if the
+project adopts the convention:
+
+```markdown
+For optional links from key code to its documentation, use the
+[code-link convention](.ai-docs/reference/documentation-cascade-authoring-skill.md#optional-code-documentation-links).
+```
+
+Preserve `.ai-docs/local/**` and independent project gates. After reconciliation:
+
+```bash
+ai-docs init
+ai-docs --version
+ai-docs validate --json
+ai-docs doctor --format json
+ai-docs init --check
+python -m pip check
+```
+
+Expect version 0.3.2, successful validation and no unexpected doctor or managed
+findings; retain and disposition pre-existing findings. Run project-specific
+tests and `pip check` in the environment that owns the installation.
+If a saved review exists, run `ai-docs review-check <record-path> --format json`.
+The new version changes checker identity; refreshed references can also change
+review inputs. Preserve historical rounds and create a new round only after
+reviewing current inputs, candidates and decisions, rather than rewriting hashes
+or tool identity merely to clear findings.
+
+Existing `Docs:` comments remain compatible. No new managed paths, schema,
+project-data migration, mandatory code annotations or CI gate are added.
+For rollback, use the preserved pre-refresh files/diff and manifest under
+[Rollback Verification](#rollback-verification); package downgrade alone does not
+restore refreshed policy or a manually merged AGENTS pointer.
+
 ## Migration 0.3.0 To 0.3.1
 
 From: `0.3.0`. To: `0.3.1`. This patch clarifies rollback verification and

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.3}/src/ai_docs_toolkit/templates/project/.ai-docs/reference/documentation-cascade-authoring-skill.md

@@ -120,6 +120,41 @@ Update indexes, `related.*`, module hierarchy, parent requirements and owners.
 Retain stable ids when moving knowledge; generated artifacts preserve source
 identity and are not edited as canonical originals.
 
+## Optional Code Documentation Links
+
+Use this optional convention where a key operation or structure benefits from
+a direct link to its documented behavior, business scenario or constraint.
+Prefer one or two relevant documents; avoid annotating every helper or repeating
+whole requirements. Keep a short explanation beside the code, followed by its
+document ID and file path. Adapt the comment delimiter and language to the project.
+Example, substituting the project's actual document ID and path:
+
+```python
+# Validate manifest shape before checking semantic constraints.
+# Docs: CON-WORKSPACE-MANIFEST-001 | ai-docs/product/workspace-contract/manifest.md
+```
+
+Paths start at the root of the Git repository containing the source file, not
+at the source directory or a shared workspace containing several repositories.
+Use `/` separators and no leading `/`. A reader can open the file without Toolkit;
+clickable navigation depends on the editor. Moving code within that repository
+keeps the path valid. When moving documentation, retain its ID and update the
+path in affected comments; verify the ID against the destination's front matter.
+
+Documentation remains primary; comments are derived local explanations. Quick
+edits may start from code and comments within the existing assignment. Before
+committing or closing the change, review document → comment → implementation →
+applicable tests and synchronize affected parts. Resolve intent conflicts through
+the existing source-of-truth review; a comment cannot authorize a behavior change.
+
+Check file existence and ID agreement separately from semantic consistency.
+Compare the explanation and actual implementation boundary with the document and
+[test evidence](documentation-change-review-skill.md#test-evidence-review);
+a link does not assert complete implementation of its target.
+These comments are a navigation aid: current Toolkit graph/context/impact and
+validation do not parse them. This convention adds no mandatory annotation,
+parser, decorator or CI gate and does not replace module ownership or review.
+
 ## Conflicts And Validation
 
 Stop dependent writes for conflicting product intent, unknown canonical owners,

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.3}/src/ai_docs_toolkit/templates/project/.ai-docs/reference/documentation-change-review-skill.md

@@ -18,6 +18,7 @@ related:
     - REF-CONTEXT-BUNDLE-001
     - REF-IMPACT-ANALYSIS-001
     - REF-SOURCE-OF-TRUTH-MODEL-001
+    - REF-DOCUMENTATION-CASCADE-AUTHORING-SKILL-001
 ai:
   priority: high
   load_when:
@@ -70,6 +71,41 @@ when internal evidence is insufficient. External findings cannot silently replac
 accepted constraints; propose their canonical owner or task context before relying
 on them for implementation. Semantic judgment is not machine proof.
 
+When the scope includes code documentation comments or their targets, apply the
+[optional code-link convention](documentation-cascade-authoring-skill.md#optional-code-documentation-links)
+to their navigation and semantic review. Absence of these optional comments is
+not a finding by itself.
+
+## Test Evidence Review
+
+When executable tests support a behavioral claim, trace each material requirement
+in scope to the relevant test selector, setup and assertion. Check that the input
+reaches the intended boundary and the assertion distinguishes compliance from
+the claimed violation. A test name, passing run or coverage percentage alone
+does not establish that link. For example, a parser rejection test may still pass
+after duplicate-key detection is removed if an unrelated schema rule rejects
+the same input; inspect the parser result separately from request validation.
+
+Choose review depth by change impact and uncertainty. Inspect existing assertions
+first. When a concrete risk of masking remains, use the smallest relevant
+counterexample or deliberate weakening in an isolated copy, within existing
+execution authority. Read-only review can diagnose the gap and propose that check;
+it does not authorize edits to source or fixtures. If the check is unavailable
+or outside scope, record the evidence gap and its disposition under
+[Impact And Findings](#impact-and-findings).
+
+For a deliberate weakening, compare a passing baseline with failure for the
+intended reason after the violation. Confirm the test ran against the altered
+code; an import, setup or environment failure is not evidence of sensitivity.
+Keep deliberate violations out of deliverable code and verify the actual final
+code with applicable tests. A focused check supports only the selected violation;
+mutation testing is not required for every change and adds no universal CI gate.
+
+Keep the requirement-to-assertion link, checked revision or input snapshot,
+commands, observed results and limitations in the existing task or session.
+Use the existing dispositions for missing or misleading evidence; a new record
+format or document per test is not required.
+
 ## Impact And Findings
 
 Give each relevant impacted document a reviewed disposition:
@@ -275,8 +311,10 @@ Keep the entry skill compact, with conditional detail here. Maintain routing,
 active/source/packaged parity, managed-file/init coverage and migration guidance
 in the same change unit. Behavior validation checks appropriate routing,
 read-only requests without mutations, blocking source conflicts, preserved
-warnings, honest validation and complete impact dispositions. Match exact wording
-only when it is a public interface.
+warnings, honest validation and complete impact dispositions. Include sufficient
+assertions, masked violations and unavailable or unauthorized sensitivity checks
+when validating test-evidence review. Match exact wording only when it is a
+public interface.
 
 The skill does not alter public CLI contracts, prove semantic completeness,
 make external sources authoritative, or require subagents or a particular vendor.

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.3}/src/ai_docs_toolkit/templates/project/AGENTS.md

@@ -15,6 +15,9 @@ If implementation and documentation conflict:
 - update the source-of-truth document or the implementation in the same change unit;
 - do not let code silently become the only source of meaning.
 
+For optional links from key code to its documentation, use the
+[code-link convention](.ai-docs/reference/documentation-cascade-authoring-skill.md#optional-code-documentation-links).
+
 ## Documentation Structure
 
 For non-trivial modules or functional blocks, prefer grouping documents in a dedicated folder instead of adding many flat files to a domain root.

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.3}/src/ai_docs_toolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-docs-toolkit
-Version: 0.3.1
+Version: 0.3.3
 Summary: AI-oriented documentation toolkit.
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -30,12 +30,14 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.3.1 includes:
+Version 0.3.3 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;
+- test-evidence review connecting requirements to assertions and proportionate sensitivity checks;
 - context bundle output;
 - an executable `ai-docs` CLI;
 - optional local MCP runtime entrypoint.
@@ -45,26 +47,62 @@ Version 0.3.1 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.1
+python -m pip install ai-docs-toolkit==0.3.3
 ai-docs --version
 ```
 
 For ephemeral execution with `uvx`:
 
 ```bash
-uvx --python 3.14 --from ai-docs-toolkit==0.3.1 ai-docs --version
+uvx --python 3.14 --from ai-docs-toolkit==0.3.3 ai-docs --version
 ```
 
 For the optional local MCP runtime:
 
 ```bash
-python -m pip install "ai-docs-toolkit[mcp]==0.3.1"
+python -m pip install "ai-docs-toolkit[mcp]==0.3.3"
 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.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
+documentation through a short explanation, document ID and a path from the Git
+repository root. Documentation remains primary; file/ID checks do not prove
+semantic consistency or full implementation of the linked document. Review the
+document, comment, implementation and applicable tests before committing changes.
+This adds no parser, mandatory annotation or CI gate.
+
+After upgrading from 0.3.1, inspect `ai-docs init --check` and `--dry-run`, reconcile
+local policy and refresh the agent profile with `ai-docs init`. Two managed
+references change: documentation cascade authoring and documentation change review.
+Existing AGENTS.md is preserved; manually merge its optional pointer if useful.
+Minimal-profile projects require no reference refresh. Preserve local rules,
+project documents and historical review rounds; verify the version, validation,
+doctor, init state and project checks. See “Migration 0.3.1 To 0.3.2” in the
+packaged `ai_docs_toolkit/docs/agent-installation.md` for exact commands and rollback.
+
 ## Release 0.3.1
 
 The package installation guide now describes preserving review/evidence before

{ai_docs_toolkit-0.3.1 → ai_docs_toolkit-0.3.3}/tests/test_cli_baseline.py

@@ -10,7 +10,7 @@ def test_cli_help(capsys):
     assert main(["--help"]) == 0
 
     output = capsys.readouterr()
-    assert "ai-docs 0.3.1" in output.out
+    assert "ai-docs 0.3.3" in output.out
     assert "ai-docs doctor" in output.out
     assert "ai-docs validate" in output.out
     assert "ai-docs validate --json" in output.out
@@ -24,7 +24,7 @@ def test_cli_version(capsys):
     assert main(["--version"]) == 0
 
     output = capsys.readouterr()
-    assert output.out.strip() == "0.3.1"
+    assert output.out.strip() == "0.3.3"
     assert output.err == ""