agent-wiki-cli 3.0.0__tar.gz → 3.1.0__tar.gz

{agent_wiki_cli-3.0.0 → agent_wiki_cli-3.1.0}/MANIFEST.in

@@ -2,6 +2,7 @@ prune examples
 recursive-include examples/plugins/documentation-hooks *.py *.json *.md
 include release_build_backend.py
 include src/llm_wiki_cli/py.typed
+include src/llm_wiki_cli/schemas/llm-wiki-normalization-diagnostic-v1.schema.json
 include src/llm_wiki_cli/schemas/llm-wiki-knowledge-v1.schema.json
 include src/llm_wiki_cli/schemas/llm-wiki-knowledge-v2.schema.json
 include src/llm_wiki_cli/schemas/llm-wiki-knowledge-v3.schema.json
@@ -18,5 +19,6 @@ include docs/security-model.md
 include docs/native-knowledge-provider.md
 include docs/native-agent-workflow.md
 prune reports
+recursive-include tests/fixtures/knowledge-evidence *.json
 include src/llm_wiki_cli/schemas/llm-wiki-manifest-v6.schema.json
 include src/llm_wiki_cli/schemas/llm-wiki-manifest-catalog-v1.schema.json

{agent_wiki_cli-3.0.0/src/agent_wiki_cli.egg-info → agent_wiki_cli-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 3.0.0
+Version: 3.1.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License-Expression: MIT

{agent_wiki_cli-3.0.0 → agent_wiki_cli-3.1.0}/docs/automation.md

@@ -138,6 +138,108 @@ source .git/llm-wiki-ci-toolchains.env
   --src-dir . --wiki-dir docs/llm_wiki
 ```
 
+### Local release preparation
+
+This repository provides `release/preflight.py` for explicit local preparation
+and release rehearsal. Run it from the source checkout with the project virtual
+environment. It keeps source, runtime, dependency and evidence identities bound
+to the selected commit, and reports native or hosted requirements that remain
+outstanding. It has no publication or promotion authority.
+
+Choose new output paths already covered by the project's ignore rules. The
+controller refuses unignored output and occupied, unowned work directories;
+existing owned work retains separate attempts. For example:
+
+```bash
+PREFLIGHT_DIR=reports/local-preflight
+RELEASE_CANDIDATE_SHA="$(git rev-parse HEAD)"
+git check-ignore -q -- "$PREFLIGHT_DIR/before-prepare.json"
+git check-ignore -q -- "$PREFLIGHT_DIR/work"
+.venv/bin/python -I release/preflight.py plan \
+  --candidate-sha "$RELEASE_CANDIDATE_SHA" --check-registry \
+  --output "$PREFLIGHT_DIR/before-prepare.json"
+.venv/bin/python -I release/preflight.py prepare \
+  --plan "$PREFLIGHT_DIR/before-prepare.json" --work "$PREFLIGHT_DIR/work"
+```
+
+`plan` inspects the checkout and available capabilities without installing
+anything. `--check-registry` additionally requests read-only remote tag and
+package-registry inspection. An unavailable service stays unavailable; it does
+not establish that a version is free. Already published versions, including
+3.0.0, and unfinished version or changelog preparation prevent complete release
+rehearsal. Version selection, migration review and issue disposition remain
+explicit maintainer decisions.
+
+`prepare` explicitly invokes the maintained locked toolchain and helper setup
+routes on supported hosts. Review its result, activate the prepared Node/npm
+environment as described above, finish authorized source and wiki maintenance,
+and commit the coherent result. Preparation may change the captured environment;
+a fresh plan is required after those changes. The controller refuses stale
+plans instead of silently selecting a different commit or environment.
+
+Preparation also screens an archive of the exact committed HEAD against the
+existing hosted source-archive limits before requesting repository health. Its
+`archive-budget/report.json` records compressed and expanded bytes, member count
+and the archive digest when an archive is created. This measures committed
+source scope. An archive above the 64 MiB compressed limit, or another existing
+archive bound, stays blocked for reviewed correction. Preparation never prunes
+storage automatically, and this local screen cannot authenticate the eventual
+hosted archive.
+
+For complete rehearsal, first save the actual issue snapshot, dispositions and
+version rationale in an ignored `$PREFLIGHT_DIR/release-review.json`. Its JSON
+object has exactly these fields:
+
+- `schema_version`: `agent-wiki-local-release-review/v1`.
+- `candidate_sha` and `version`: the final full commit SHA and its package version.
+- `observed_at`: a timezone-aware ISO 8601 observation time, no more than 24 hours old.
+- `issues`: the observed issue rows, each containing integer `number` and string `title`.
+- `dispositions`: one row for every observed issue, each containing its `number`,
+  a `decision` of `blocker`, `resolved`, `deferred`, or `not-a-bug`, and a specific
+  nonempty `reason`.
+- `semver`: `baseline` as the previous three-part release version, `target` matching
+  the candidate version, and a nonempty `reason` for the version choice.
+
+Record the review that was actually performed. This local record does not prove
+independent approval or a complete authenticated GitHub issue inventory. A
+recorded blocker prevents full rehearsal. Omitting `--review-file` leaves review
+pending and still permits the early diagnostic invocation described below.
+
+```bash
+RELEASE_CANDIDATE_SHA="$(git rev-parse HEAD)"
+git check-ignore -q -- "$PREFLIGHT_DIR/release-review.json"
+git check-ignore -q -- "$PREFLIGHT_DIR/final-plan.json"
+.venv/bin/python -I release/preflight.py plan \
+  --candidate-sha "$RELEASE_CANDIDATE_SHA" --check-registry \
+  --review-file "$PREFLIGHT_DIR/release-review.json" \
+  --output "$PREFLIGHT_DIR/final-plan.json"
+.venv/bin/python -I release/preflight.py run \
+  --plan "$PREFLIGHT_DIR/final-plan.json" --work "$PREFLIGHT_DIR/work"
+.venv/bin/python -I release/preflight.py status --work "$PREFLIGHT_DIR/work"
+```
+
+Use the returned `receipt_path` with
+`.venv/bin/python -I release/preflight.py verify --receipt RECEIPT_PATH`.
+Verification checks retained evidence and its current applicability without
+executing recorded commands or repairing anything. `status` shows recorded
+attempts; it does not establish their current applicability. Plans expire after
+24 hours and require a new inspection.
+
+For an early diagnostic check before version preparation is complete, append
+`--stage contracts` to `run`. A partial invocation remains `blocked` for release
+readiness even when its checks succeed. Full execution runs the maintained
+host-applicable checks, independent builds and installed-artifact verification
+serially. It reports `failed`, `blocked`, or
+`local-ready-hosted-required`; the last result still requires normal hosted
+qualification and all required target environments.
+
+Local macOS success cannot establish Windows or Linux semantics, an unsupported
+helper or OCI architecture, an authenticated policy proof, or publication
+attestations. A missing capability remains pending. Continue through reviewed
+main changes, current native CI and the existing qualification and publication
+procedure using its verified artifacts. Local rehearsal distributions and
+receipts cannot replace that evidence.
+
 ### Qualification after merging
 
 Repository release automation is disabled by default in

{agent_wiki_cli-3.0.0 → agent_wiki_cli-3.1.0}/docs/cli-reference.md

@@ -19,6 +19,53 @@ task detector with Mermaid styling.
 | Extend and collaborate | [install / plugins](#install-and-plugins), [team](#team), [knowledge](#knowledge) |
 | Manage an installation | [upgrade](#upgrade), [migrate](#migrate), [metrics](#metrics), [status / release / bump / uninstall](#status-release-bump-and-uninstall) |
 
+## Recover captured evidence
+
+Keep the failure's source, cause and qualifications. Use the same source/wiki
+roots, selection, helper cache and generation options through diagnosis and
+repair. For example, with source `src`, wiki `wiki`, selection
+`config/sources.json` and an existing helper cache `.cache/helpers`, save a
+permitted request file `evidence.json` containing:
+
+```json
+{"operation":"explain","source":"orders.py","limit":5}
+```
+
+```bash
+llm-wiki query --request evidence.json --src-dir src --wiki-dir wiki --source-selection config/sources.json --helper-cache-dir .cache/helpers
+llm-wiki extract --src-dir src --paths orders.py --deep --read-only --source-selection config/sources.json --helper-cache-dir .cache/helpers
+llm-wiki sync --dry-run --jobs 1 --src-dir src --wiki-dir wiki --source-selection config/sources.json --helper-cache-dir .cache/helpers
+```
+
+Replace these example bindings with the original command's actual values.
+Request `source` and extract `--paths` are canonical POSIX paths relative to
+`--src-dir`; filesystem and cache arguments use native paths. Explanation is
+snapshot-only by default; choose an exact locator from ambiguous results.
+`live:true` plus `allow_full_inventory:true` authorizes full current analysis.
+The [explanation route](#context) separates captured/current source and producer
+bases, helper identity and active runtime. Raw extraction prints JSON, installs
+no dependencies and cannot repair a stored manifest.
+
+For a missing/stale helper, use its exact [preparation remedy](#prepare-extractors)
+with setup authority, then retry the original read once with the same selection
+and cache. Preparation takes `--cache-dir`, reads take `--helper-cache-dir`.
+Do not combine explicit `--language` preparation with `--source-selection`.
+A current helper with a runtime mismatch needs the reported runtime selected on
+PATH; preparation does not change PATH. No hand-linked dependencies or internal
+helper-script invocation is required.
+
+Fix fresh normalization rejection before repair; invalid evidence stays blocking.
+If raw output is valid but captured evidence is unavailable, the authorized
+[owning sync](#sync) must commit the repair. Review the complete preview, including
+removals. Broad changes require explicit authority for the same invocation with
+`--force` replacing `--dry-run`; never force automatically. Review again after
+any input change. The bounded `--repair-evidence` writer retains its own adoption,
+stable-producer and scope conditions and still performs full analysis.
+Missing/corrupt authority needs its recovery route, not generated JSON edits or
+reinitialization. Review semantic prose, re-anchor edits through owning sync,
+then run strict lint and CI with the same bindings. Keep current defaults and
+strict gates. Storage upgrade and diagnostic reads alone do not establish repair.
+
 ## Resource-aware execution
 
 In an interactive IDE or whenever host capacity is unknown, run one heavy gate
@@ -260,6 +307,77 @@ or controlled CI runner with known capacity.
 Sync repairs
 manifests with invalid source hashes without touching pages, and stops unusually
 broad diffs unless `--force` is used.
+
+The affected-source count names inputs whose wiki projections may change;
+sync does not rewrite those source files. A generator-version transition can
+refresh every managed source even when source bytes are unchanged. A storage
+repack alone is separate from that generator refresh.
+When a broad update is refused, the message separates source-change reasons
+from additional generator-refresh inputs, identifies captured/current generator
+versions when available, and shows a bounded path sample with omitted counts.
+Reason counts can overlap; the total source-input count is deduplicated.
+Use the supplied `--dry-run` command with the same source/wiki roots, source
+selection and cache bindings to inspect the full page and artifact plan before
+authorizing a broad write. The preview lists complete affected input paths and
+their reasons, including paths omitted from the refusal sample.
+An oversized, control-containing or non-UTF-8 command is not
+printed; repeat the original invocation with `--dry-run` and omit `--force`.
+The path sample bounds the diagnostic output, not extraction or preview work.
+
+For a generator upgrade, review the complete dry-run page and artifact actions,
+including removals, before explicitly repeating the same invocation with
+`--force` in place of `--dry-run`. Keep the source/wiki roots, selection,
+helper/cache bindings and generation options unchanged. This is an owning
+refresh: it regenerates evidence with the current provider and commits matching
+projections and provenance. Already matching managed pages keep their bytes and
+are not rewritten. Changed generated content still appears as a page update;
+it is not classified as a source metadata edit merely because sources match.
+
+A preview is not a saved approval token. `--force` computes a new plan from
+current inputs; repeat preview and review if source, helper, selection, provider
+or wiki inputs change. It can authorize broad changes and stale generated
+surface removal, including authored Behavior on those retired surfaces. It does
+not waive ownership or integrity checks, adopt foreign state or recover missing
+authority. After the refresh and semantic review, re-anchor any prose edits with
+ordinary sync, then run strict lint and CI integrity validation using the same
+roots and selection. A subsequent sync with unchanged inputs should be a no-op.
+If publication is rejected, follow its explicit recovery diagnostic before
+retrying; do not delete authority files or reinitialize an established wiki.
+
+For a narrowly authorized repair of captured invalid evidence, use
+`--repair-evidence` with canonical POSIX source paths relative to `--src-dir`:
+
+```bash
+llm-wiki sync --src-dir src --wiki-dir wiki --no-plugins --repair-evidence package/module.py --dry-run
+llm-wiki sync --src-dir src --wiki-dir wiki --no-plugins --repair-evidence package/module.py
+```
+
+Keep the project's source selection, helper/cache bindings and other applicable
+options on both invocations. This mode requires an already adopted, coherent
+wiki, unchanged source and generation policy, and matching complete built-in
+producer/helper/runtime commitments. Run the authorized ordinary owning update
+first after a generator or producer transition. Missing or corrupt authority
+requires its explicit recovery route; scoped repair never adopts or migrates it.
+
+The writer repairs a selected source's existing module and entity evidence
+together, preserves unselected captured failures and review history, and does
+not acknowledge review. It refuses mixed source/prose edits, missing or renamed
+pages, new/retired identities, and any reconciliation that changes unselected
+facts or the global typed graph. `--force` can authorize a reviewed broad input
+count; it cannot override these scope conditions. A selected known basis must
+match the fresh observation; otherwise use ordinary owning sync for full review.
+
+This is scoped application after **full analysis**, not one-file extraction.
+Source verification, global graph/projection reconciliation, an isolated wiki
+copy, native objects, log/cache metadata and complete recovery preimages still
+require global work. The command checks its candidate before live application
+and again before publication. A changed source, helper, provider, selection or
+wiki invalidates the prepared operation. Existing publication recovery remains
+active; the isolated preflight does not replace a recoverable owning commit.
+Already matching selected evidence produces no scoped publication. Success
+does not certify the whole wiki: unselected unknown evidence remains unknown,
+so repeat strict lint and CI validation afterward.
+
 `--initialize-surfaces` enters a surface-only backfill mode for `flows`,
 `dependencies`, and/or `api-contracts`: ordinary entity/module source changes
 are reported but deferred. `--flow-category` is repeatable, `--exclude-tests`
@@ -576,6 +694,57 @@ Inspect the named source with the read-only
 single-file extraction command above, repair the underlying producer or source
 problem, then run owning sync before repeating strict validation. Editing a
 generated wiki table does not repair invalid extractor evidence.
+Diagnostics distinguish a captured failure with no fresh result, a captured
+failure whose fresh normalization succeeds, and a fresh observation that still
+fails normalization. Where captured source hashes exist, they distinguish
+unchanged bytes from changed or incomparable inputs. Producer metadata and
+version labels do not identify historical package bytes; unavailable provenance
+and rejected-record details remain explicit.
+
+Fresh normalization rejections can include `Fresh normalization diagnostic: `
+followed by a JSON object in the existing finding `message` or evidence freshness
+`description`. The object has its own
+[`llm-wiki-normalization-diagnostic/v1` schema](../src/llm_wiki_cli/schemas/llm-wiki-normalization-diagnostic-v1.schema.json).
+It identifies the source, scope and extractor, the entity's named occurrence
+when applicable, a record `pointer`, the failed `rule`, the `expected` shape,
+and redacted `actual` type/summary. For example, an import can identify
+`/imports/0/module` with rule `import-module`; a near-miss explicit dynamic
+import can instead identify its missing `/imports/0/reason`.
+
+Exact pointers use JSON Pointer with zero-based array indexes. Entity occurrence
+coordinates remain one-based among declarations with the same name. A missing
+occurrence points to the declaration collection, without inventing an index.
+An unknown recursion/encoding location uses a null pointer. When an arbitrary
+mapping key is redacted, the pointer identifies an ancestor and `pointer_exact`
+is false. Bounded coordinate prefixes are listed in `truncated_fields` and must
+not be treated as exact identities.
+
+The rendered diagnostic is limited to 4,096 UTF-8 bytes, including its prefix.
+Rejected string values, container contents and arbitrary mapping keys are redacted;
+actual summaries retain safe shape facts such as type, length, emptiness or
+non-finiteness. No arbitrary object representation is rendered. A surrounding
+query may impose a tighter response bound and disclose truncation separately.
+Missing detail does not establish valid evidence.
+
+This versioned object is carried as diagnostic text; existing outer report and
+evidence-basis fields are unchanged. Older decoders can retain that text without
+parsing it. A consumer interpreting the object must recognize its schema version;
+unknown versions are not an inferred current contract. Native comparison data
+still requires its compatible outer report schema. Raw `extract` output remains
+inventory, not an annotated normalization report. Historical reason-only snapshots
+do not acquire reconstructed record pointers: details describe only a rejection
+observed by the current normalization run. Valid observation hashes, reason codes
+and strict failure policy remain unchanged.
+
+Fresh extraction and evidence explanation are reads: a valid fresh observation
+does not make an unknown committed baseline current. Ordinary owning sync can
+refresh a captured invalid module/entity basis after current deep normalization
+succeeds, including when the generator version label is unchanged. Its preview
+labels this as `evidence-refresh-additional`, separately from source edits and
+generator transitions. Broad refreshes retain the normal review guards. If fresh
+normalization is still invalid, repair that cause; `--force` does not waive
+evidence validity. If fresh normalization succeeds but owning sync is refused by
+the broad-update guard, follow its complete preview and reviewed apply route.
 `lint --profile` and `ci-check --format json` additionally include this shape:
 
 ```json
@@ -909,6 +1078,40 @@ perform a full inventory only when `allow_full_inventory=true` is supplied.
 The context budget and focus bound emitted output after a full deep inventory;
 they do not make that scan computationally cheap.
 
+Explain one exact concept using the existing evidence service:
+
+```bash
+printf '%s\n' '{"operation":"explain","value":"llm-wiki://modules/orders"}' | llm-wiki query --request - --src-dir . --wiki-dir docs/llm_wiki
+printf '%s\n' '{"operation":"explain","source":"src/orders.py","limit":10}' | llm-wiki query --request - --src-dir . --wiki-dir docs/llm_wiki
+printf '%s\n' '{"operation":"explain","value":"llm-wiki://modules/orders","live":true,"allow_full_inventory":true}' | llm-wiki query --request - --src-dir . --wiki-dir docs/llm_wiki --helper-cache-dir .git
+```
+
+Supply exactly one `value` (exact concept locator, UID or canonical route) or
+canonical POSIX `source` path relative to `--src-dir`. A source with multiple
+concepts returns bounded choices; repeat with one exact locator to see evidence.
+The default reads the committed snapshot without extraction. Set `live:true`
+and explicitly authorize `allow_full_inventory:true` to compare against a full
+current source inventory. Existing evidence freshness includes recorded/live
+source bases, cause and bounded fresh normalization detail when available;
+snapshot reads never reconstruct historical rejected-record details.
+
+`provenance` separates stored/live producer records, the installed package
+fingerprint and version, the structural inventory contract, and active Python
+runtime. The fingerprint covers installed files and runtime/version inputs; it
+does not identify the original distribution archive or prove release authenticity.
+For a selected external extractor, existing preparation receipt source/artifact
+identities and preparation toolchain are reported separately from active runtime.
+TypeScript also checks the source copy in the prepared execution directory against
+the bundled source fingerprint; missing or changed copies require preparation again.
+Artifact fingerprints cover the receipt's recorded path. For TypeScript this is
+the `ts-morph` subtree, which does not identify sibling transitive dependencies.
+Missing or mismatched data stays explicit. Reads do not install dependencies or
+update source, wiki or helper state. Missing helpers include the existing exact
+preparation command for the selected cache; setup requires authorization, then
+retry with the same roots, source selection and cache. A runtime mismatch also
+requires selecting the matching runtime on PATH. Output limits and truncation
+disclosures apply to explanation and provenance together.
+
 External tools can use the `llm-wiki-context/v1` JSON request protocol:
 
 ```bash
@@ -2134,6 +2337,32 @@ prepared-adoption and captured-preimage retries need their explicit options.
 See [ordinary review and recovery](maintenance.md) for exact eligibility and
 Python/MCP interfaces.
 
+### Recover new pages from a rejected sync
+
+If sync emits `new_page_recovery`, retain its recovery directory and exact
+`expected_journal_hash`. Preview the pages before applying recovery:
+
+```bash
+llm-wiki maintenance recover-new-pages --wiki-dir wiki --recovery-dir RECOVERY_DIR --expected-journal-hash JOURNAL_SHA256 --dry-run
+```
+
+After reviewing the list, repeat without `--dry-run` to remove only unchanged
+Markdown pages created by that rejected operation. Their exact postimages remain
+in the recovery directory. Existing prose, source files and committed authority
+are not restored or overwritten. Edited/replaced pages, changed selection or
+authority, unsafe links, another wiki and altered journals are refused.
+
+Run the original sync again after recovery. This command does not make an
+interrupted generation current, repair missing maintenance authority, or replace
+the complete adopted recovery route above. Recovery is not atomic across pages:
+an I/O failure can leave a partially removed set, with all original postimages
+retained for explicit inspection and restoration. A missing or changed candidate
+is refused; do not blindly replay or manufacture another journal hash.
+Capture is bounded to 10,000 baseline/created-page entries, an 8 MiB journal
+and individual postimages, and 64 MiB of postimages per operation. Limits stop
+the new write rather than authorize unrecorded pages. Without an original
+rejection journal, this command cannot authorize removal of older stranded pages.
+
 ## `upgrade`
 
 Refresh framework-managed artifacts in place.

{agent_wiki_cli-3.0.0 → agent_wiki_cli-3.1.0}/pyproject.toml

@@ -5,7 +5,7 @@ backend-path = ["."]
 
 [project]
 name = "agent-wiki-cli"
-version = "3.0.0"
+version = "3.1.0"
 description = "CLI tool to maintain hybrid LLM Wikis for multi-language projects."
 readme = "README.md"
 license = "MIT"
@@ -67,6 +67,7 @@ where = ["src"]
 "llm_wiki_cli" = [
     "py.typed",
     "services/analysis_contracts.json",
+    "schemas/llm-wiki-normalization-diagnostic-v1.schema.json",
     "schemas/llm-wiki-knowledge-v1.schema.json",
     "schemas/llm-wiki-implementation-evidence-v1.schema.json",
     "schemas/llm-wiki-maintenance-adoption-v1.schema.json",

{agent_wiki_cli-3.0.0 → agent_wiki_cli-3.1.0/src/agent_wiki_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 3.0.0
+Version: 3.1.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License-Expression: MIT

{agent_wiki_cli-3.0.0 → agent_wiki_cli-3.1.0}/src/agent_wiki_cli.egg-info/SOURCES.txt

@@ -114,6 +114,7 @@ src/llm_wiki_cli/schemas/llm-wiki-manifest-catalog-v1.schema.json
 src/llm_wiki_cli/schemas/llm-wiki-manifest-v6.schema.json
 src/llm_wiki_cli/schemas/llm-wiki-manifest-v7.schema.json
 src/llm_wiki_cli/schemas/llm-wiki-manifest-v8.schema.json
+src/llm_wiki_cli/schemas/llm-wiki-normalization-diagnostic-v1.schema.json
 src/llm_wiki_cli/services/__init__.py
 src/llm_wiki_cli/services/analysis_capture.py
 src/llm_wiki_cli/services/analysis_compatibility.py
@@ -156,6 +157,8 @@ src/llm_wiki_cli/services/documentation_review.py
 src/llm_wiki_cli/services/documentation_wiki_input.py
 src/llm_wiki_cli/services/documentation_worklist.py
 src/llm_wiki_cli/services/entrypoints.py
+src/llm_wiki_cli/services/evidence_diagnostics.py
+src/llm_wiki_cli/services/evidence_explanation.py
 src/llm_wiki_cli/services/extraction_jobs.py
 src/llm_wiki_cli/services/extraction_service.py
 src/llm_wiki_cli/services/extractor_helpers.py
@@ -221,6 +224,7 @@ src/llm_wiki_cli/services/mcp_server.py
 src/llm_wiki_cli/services/metrics.py
 src/llm_wiki_cli/services/module_maps.py
 src/llm_wiki_cli/services/native_inspection.py
+src/llm_wiki_cli/services/normalization_diagnostics.py
 src/llm_wiki_cli/services/obsidian.py
 src/llm_wiki_cli/services/packages.py
 src/llm_wiki_cli/services/packet_field_policy.py
@@ -242,6 +246,7 @@ src/llm_wiki_cli/services/resource_diagnostics.py
 src/llm_wiki_cli/services/review_service.py
 src/llm_wiki_cli/services/runtime_output.py
 src/llm_wiki_cli/services/schema.py
+src/llm_wiki_cli/services/scoped_sync_repair.py
 src/llm_wiki_cli/services/search_discovery.py
 src/llm_wiki_cli/services/search_discovery_capture.py
 src/llm_wiki_cli/services/search_lexical.py
@@ -264,6 +269,7 @@ src/llm_wiki_cli/services/sync_analysis.py
 src/llm_wiki_cli/services/sync_analysis_cache.py
 src/llm_wiki_cli/services/sync_generated_sections.py
 src/llm_wiki_cli/services/sync_manifest.py
+src/llm_wiki_cli/services/sync_recovery.py
 src/llm_wiki_cli/services/sync_retained_links.py
 src/llm_wiki_cli/services/sync_transition_execution.py
 src/llm_wiki_cli/services/sync_transitions.py
@@ -372,6 +378,7 @@ tests/test_bump.py
 tests/test_calibration_cli.py
 tests/test_calibration_isolation.py
 tests/test_capability_diagnostics.py
+tests/test_captured_evidence_diagnostics.py
 tests/test_change_selection.py
 tests/test_ci_check.py
 tests/test_ci_runtime_output.py
@@ -380,6 +387,7 @@ tests/test_ci_workflow_wrapper.py
 tests/test_circuit_breaker.py
 tests/test_cli.py
 tests/test_cli_error_streams.py
+tests/test_committed_projection_recovery.py
 tests/test_compact_context_session.py
 tests/test_compact_delivery_interfaces.py
 tests/test_compact_delivery_policy.py
@@ -473,6 +481,8 @@ tests/test_entity_retirement.py
 tests/test_entity_retirement_evidence.py
 tests/test_entrypoints.py
 tests/test_eval_lite.py
+tests/test_evidence_explanation_query.py
+tests/test_evidence_recovery_guidance.py
 tests/test_examples.py
 tests/test_extract.py
 tests/test_extract_api_contracts.py
@@ -597,9 +607,11 @@ tests/test_native_workflow_oracles.py
 tests/test_native_workflow_scenarios.py
 tests/test_native_workflow_trace.py
 tests/test_navigation_layouts.py
+tests/test_normalization_diagnostics.py
 tests/test_obsidian.py
 tests/test_optimization_evidence.py
 tests/test_optimization_measurements.py
+tests/test_owned_packet_recovery.py
 tests/test_package_metadata.py
 tests/test_package_validation.py
 tests/test_packages.py
@@ -610,6 +622,9 @@ tests/test_plugins.py
 tests/test_policy_activation.py
 tests/test_policy_renewal.py
 tests/test_policy_source_freeze.py
+tests/test_preflight.py
+tests/test_preflight_contracts.py
+tests/test_preflight_runner.py
 tests/test_progress.py
 tests/test_protected_artifacts.py
 tests/test_protocol_registry.py
@@ -656,6 +671,7 @@ tests/test_runtime_output.py
 tests/test_rust_extract.py
 tests/test_schema.py
 tests/test_schema_context_baselines.py
+tests/test_scoped_sync_repair.py
 tests/test_search_discovery.py
 tests/test_search_discovery_capture.py
 tests/test_search_discovery_interfaces.py
@@ -682,6 +698,7 @@ tests/test_storage_locality.py
 tests/test_storage_lock_diagnostics.py
 tests/test_storage_performance.py
 tests/test_storage_retention_diagnostics.py
+tests/test_storage_review_pagination.py
 tests/test_surface_initialization.py
 tests/test_sync.py
 tests/test_sync_analysis.py
@@ -689,10 +706,12 @@ tests/test_sync_analysis_cache.py
 tests/test_sync_analysis_capture.py
 tests/test_sync_api_contracts.py
 tests/test_sync_generated_sections.py
+tests/test_sync_guard_diagnostics.py
 tests/test_sync_manifest.py
 tests/test_sync_missing_pages.py
 tests/test_sync_no_plugins.py
 tests/test_sync_page_transitions.py
+tests/test_sync_recovery.py
 tests/test_sync_retained_links.py
 tests/test_sync_runtime_regressions.py
 tests/test_sync_transition_execution.py
@@ -730,4 +749,9 @@ tests/test_wiki_sync_cleanup.py
 tests/test_workflow_contracts.py
 tests/test_workflow_interfaces.py
 tests/test_yaml_formats.py
-tests/test_yaml_syntax.py
+tests/test_yaml_syntax.py
+tests/fixtures/knowledge-evidence/concept-observation-inventories.json
+tests/fixtures/knowledge-evidence/producer-evidence-expectations.json
+tests/fixtures/knowledge-evidence/producer-evidence-inventories.json
+tests/fixtures/knowledge-evidence/released-2.5.0-large-files.json
+tests/fixtures/knowledge-evidence/released-2.5.0-large.json

{agent_wiki_cli-3.0.0 → agent_wiki_cli-3.1.0}/src/llm_wiki_cli/api.py

@@ -2540,6 +2540,7 @@ def explain_evidence(
 DOCUMENTATION_QUERY_SCHEMA_VERSION = "llm-wiki-documentation-query/v1"
 MAX_RAW_QUERY_EVIDENCE_BYTES = 64 * 1024
 _DOCUMENTATION_QUERY_FIELDS = {
+    "explain": frozenset({"operation", "value", "source", "limit", "live", "allow_full_inventory"}),
     "concept": frozenset({"operation", "value", "limit"}),
     "related": frozenset({"operation", "value", "limit", "direction", "kinds"}),
     "surface": frozenset({"operation", "value", "limit"}),
@@ -2706,7 +2707,18 @@ def _validate_documentation_query_request(
     limit = _normalize_query_limit(request.get("limit", 20))
     # Operation-specific transport fields are input validation, not part of
     # loading the query service. Reject them before any workspace access.
-    if operation == "impact":
+    if operation == "explain":
+        if type(request.get("live", False)) is not bool:
+            raise InvalidRequestError("live must be a boolean.", code="invalid-request", details={"field": "live"})
+        if type(request.get("allow_full_inventory", False)) is not bool:
+            raise InvalidRequestError("allow_full_inventory must be a boolean.", code="invalid-request", details={"field": "allow_full_inventory"})
+        if ("value" in request) == ("source" in request):
+            raise InvalidRequestError("Supply exactly one of value or source.", code="invalid-request", details={"field": "value"})
+        if request.get("live", False):
+            _require_full_inventory_opt_in(request)
+        elif request.get("allow_full_inventory", False):
+            raise InvalidRequestError("allow_full_inventory requires live=true.", code="invalid-request", details={"field": "allow_full_inventory"})
+    elif operation == "impact":
         _normalize_query_choice(request.get("source_policy", "explicit"), field="source_policy", allowed=("explicit", "discovery"))
     elif operation == "related":
         _normalize_query_choice(request.get("direction", "both"), field="direction", allowed=_KNOWLEDGE_QUERY_DIRECTIONS)
@@ -3050,11 +3062,43 @@ def query_documentation(
     wiki_dir: str = DEFAULT_WIKI_DIR,
     allow_external_src: bool = False,
     source_selection: str | Path | None = None,
+    helper_cache_dir: str | Path | None = None,
     comparison_policy: str | None = None,
 ) -> DocumentationQueryResult:
     """Dispatch one exact bounded read-only documentation query."""
 
     operation, limit = _validate_documentation_query_request(request)
+    if operation == "explain":
+        from .services.evidence_explanation import explain_source, explanation_provenance
+
+        if helper_cache_dir is not None and not isinstance(helper_cache_dir, (str, Path)):
+            raise InvalidRequestError("must be a path", code="invalid-request", details={"field": "helper_cache_dir"})
+        source = "source" in request
+        value = _normalize_query_input(
+            lambda: normalize_supplied_paths((request.get("source"),))[0]
+            if source else normalize_concept_coordinate(request.get("value")),
+            field="source" if source else "value",
+        )
+        source_root = validate_source_root(src_dir, "--src-dir", allow_external=allow_external_src)
+        if request.get("live", False):
+            service = build_documentation_query_service(
+                src_dir, wiki_dir=wiki_dir, limit=limit,
+                allow_external_src=allow_external_src, read_only=True,
+                source_selection=source_selection, helper_cache_dir=helper_cache_dir,
+            )
+            scope = "full-inventory"
+        else:
+            service = _snapshot_query_service(wiki_dir, limit=limit)
+            scope = "snapshot-index-only"
+        payload = explain_source(service, value) if source else service.explain_evidence(value)
+        payload["provenance"] = explanation_provenance(
+            service, payload, source_root=source_root, helper_cache_dir=helper_cache_dir,
+        )
+        payload["limitations"] = [
+            "Live explanation performs a full source inventory; snapshot explanation does not extract source or establish fresh normalization.",
+            "Helper inspection reads existing receipts/bytes and probes runtime versions; it never prepares dependencies.",
+        ]
+        return _with_query_envelope(operation, payload, scope=scope)
     if operation == "impact":
         return _impact_query(
             request,

{agent_wiki_cli-3.0.0 → agent_wiki_cli-3.1.0}/src/llm_wiki_cli/api_types.py

@@ -456,6 +456,8 @@ class DocumentationQueryResult(_DocumentationQueryRequired, total=False):
     """Common envelope returned by the shared bounded query dispatcher."""
 
     knowledge: KnowledgeStatus | dict[str, Any]
+    evidence: dict[str, Any] | None
+    provenance: dict[str, Any]
     concept: dict[str, Any] | None
     total: int
     returned: int