agent-wiki-cli 2.3.1__tar.gz → 2.4.0__tar.gz

{agent_wiki_cli-2.3.1/src/agent_wiki_cli.egg-info → agent_wiki_cli-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-wiki-cli
-Version: 2.3.1
+Version: 2.4.0
 Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
 Author-email: Denis Sivagin <denissvgn@gmail.com>
 License-Expression: MIT
@@ -37,6 +37,10 @@ Dynamic: license-file
 
 # LLM Wiki CLI
 
+[![CI](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
 Build and maintain an architectural wiki for your codebase. LLM Wiki scans
 source into Markdown pages, keeps generated structure in sync, and supplies
 coding agents with searchable, bounded context. Agents add the explanations
@@ -67,13 +71,17 @@ Run these commands from your project root. Choose `generic` for an `AGENTS.md`
 instruction file, or select one of the [supported agents](#agent-support).
 
 ```bash
-llm-wiki init --agent generic
+llm-wiki init --agent generic --prepare-extractors
 ```
 
-For TypeScript/JavaScript, Go, Rust, or Haskell, first prepare the required
-helpers with `llm-wiki prepare-extractors --src-dir .`.
-[Helper setup](docs/cli-reference.md#prepare-extractors) is explicit and may
-download dependencies or compile a bundled helper. Python needs no helper.
+`--prepare-extractors` automatically prepares missing or stale helpers for the
+selected TypeScript/JavaScript, Go, Rust, or Haskell source files and reuses
+current helpers. Install the relevant toolchain first: Node.js with npm, Go,
+Cargo, or GHC. Python needs no helper.
+[Helper setup](docs/cli-reference.md#prepare-extractors) may download dependencies
+or compile a bundled helper. Omit the flag to scaffold without preparation;
+read-only commands never prepare helpers. You can rerun the setup command after
+a package upgrade or use `llm-wiki prepare-extractors --src-dir .` separately.
 
 ```bash
 llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.4.0}/README.md

@@ -1,5 +1,9 @@
 # LLM Wiki CLI
 
+[![CI](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/Denissvgn/python-wiki-llm/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
 Build and maintain an architectural wiki for your codebase. LLM Wiki scans
 source into Markdown pages, keeps generated structure in sync, and supplies
 coding agents with searchable, bounded context. Agents add the explanations
@@ -30,13 +34,17 @@ Run these commands from your project root. Choose `generic` for an `AGENTS.md`
 instruction file, or select one of the [supported agents](#agent-support).
 
 ```bash
-llm-wiki init --agent generic
+llm-wiki init --agent generic --prepare-extractors
 ```
 
-For TypeScript/JavaScript, Go, Rust, or Haskell, first prepare the required
-helpers with `llm-wiki prepare-extractors --src-dir .`.
-[Helper setup](docs/cli-reference.md#prepare-extractors) is explicit and may
-download dependencies or compile a bundled helper. Python needs no helper.
+`--prepare-extractors` automatically prepares missing or stale helpers for the
+selected TypeScript/JavaScript, Go, Rust, or Haskell source files and reuses
+current helpers. Install the relevant toolchain first: Node.js with npm, Go,
+Cargo, or GHC. Python needs no helper.
+[Helper setup](docs/cli-reference.md#prepare-extractors) may download dependencies
+or compile a bundled helper. Omit the flag to scaffold without preparation;
+read-only commands never prepare helpers. You can rerun the setup command after
+a package upgrade or use `llm-wiki prepare-extractors --src-dir .` separately.
 
 ```bash
 llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.4.0}/docs/automation.md

@@ -121,6 +121,131 @@ that exact commit. Routine pull-request health remains advisory. The release
 workflow retains `evidence-rd-10` with original maintenance inputs and
 `knowledge-maintenance-verification` with the separate verification result.
 
+For TypeScript/JavaScript wiki refreshes, use the locked Node/npm toolchain for
+the active extraction process as well as helper preparation. A helper prepared
+with the lock can still be executed by a different `node` on `PATH`; that records
+a different runtime identity and can prevent portable release-health comparison.
+On a source checkout, prepare and activate the ignored local toolchain before
+refreshing:
+
+```bash
+bash .github/scripts/setup-llm-wiki-ci-toolchains.sh --mode routine \
+  --install-root .git/llm-wiki-ci-toolchains \
+  --environment-file .git/llm-wiki-ci-toolchains.env --python .venv/bin/python
+source .git/llm-wiki-ci-toolchains.env
+.venv/bin/python -m llm_wiki_cli.cli sync --jobs 1 --src-dir . --wiki-dir docs/llm_wiki
+.venv/bin/python -m llm_wiki_cli.cli doctor --strict --comparison-policy analysis-v1 \
+  --src-dir . --wiki-dir docs/llm_wiki
+```
+
+### Qualification after merging
+
+Repository release automation is disabled by default in
+[`release/automation.json`](../release/automation.json). When enabled, successful
+main CI starts the coordinator. A stale policy binding receives a bounded,
+nonpromoting evaluation of the committed repository and standalone doctor
+parity. This evaluation can run between releases, including when the current
+version is already published.
+
+The coordinator authenticates the original hosted artifacts and creates a bot
+pull request containing only the activation update and its audit receipt.
+Independent proof verification, complete CI, and up-to-date branch checks must
+pass before automatic squash merging. The merge starts fresh CI and normal
+qualification for that exact main commit. Normal qualification waits when the
+version, release tag, or changelog is not ready; unavailable remote checks are
+reported as blocked. Source, health, and integrity failures remain blocking.
+
+Configure the following before setting `enabled` to `true`:
+
+- Enable repository auto-merge and protect main through pull requests, with no
+  bypass actors and with force pushes and deletion prohibited.
+- Require `CI complete` and `Release activation proof`, with up-to-date checks.
+  Retain the existing integrity requirement.
+- Set `trusted_bot.login` and `trusted_bot.id` to the bot account, and
+  `trusted_bot.check_app_id` to its independent check publisher's GitHub App ID.
+- For GitHub App authentication, configure the repository variable
+  `RELEASE_AUTOMATION_APP_CLIENT_ID` and secret
+  `RELEASE_AUTOMATION_APP_PRIVATE_KEY`. The pinned adapter creates and revokes a
+  repository-scoped installation token for each coordinator run. Grant Actions,
+  Contents, Pull requests, and Checks write permissions, and Administration read
+  permission to inspect branch rules. Do not grant protection bypass.
+- Alternatively, provide a suitable bot credential through the
+  `RELEASE_AUTOMATION_TOKEN` secret. It must authenticate as the configured bot
+  and check publisher; the coordinator never substitutes the ordinary job token.
+
+Missing credentials or protections produce `blocked_setup` without dispatching
+qualification or changing the repository. Configure and enable automation
+through a normal pull request, then use **Release qualification automation** in
+Actions to resume the current main candidate. The optional retry input creates
+a new request only when explicitly selected; duplicate completion events reuse
+existing work.
+
+Pinned candidate branches and candidate/run/attempt identities prevent main
+advancing during dispatch from changing the qualified source. Changed policy
+inputs supersede older renewal evidence. Audit receipts remain committed under
+`release/policy-activations/` after hosted artifact retention expires.
+
+Automation finishes with verified qualified artifacts and their links. PyPI
+publication and release tag creation remain separate explicit operations.
+
+## Manual policy approval and main releases
+
+Use **Renew policy approval** in Actions when the required policy binding is
+stale. This workflow works independently of whether the recurring release
+coordinator is enabled. It runs from `main` and offers a choice instead of
+requiring callers to find the policy-shadow switch among qualification options.
+
+1. Select `evaluate`. The workflow captures current main and dispatches a
+   nonpromoting policy proof through **Release qualification**. Its summary
+   links to qualification runs. Wait for the proof run to complete successfully.
+2. Run **Renew policy approval** again with `prepare`, that proof's run ID, and
+   its successful attempt number. The trusted verifier authenticates the
+   hosted artifacts, replays the evidence, and checks that the proof source is
+   in main history with unchanged policy implementation and configuration.
+3. Review the generated approval PR. With the configured GitHub App or
+   `RELEASE_AUTOMATION_TOKEN`, the workflow creates an activation-only PR from
+   `codex/manual-policy-activation/<implementation-digest>`. The credential
+   must belong to a repository maintainer or the configured trusted bot and
+   must trigger ordinary PR checks. The default job token is used for proof
+   dispatch and reading evidence, not for creating the approval PR.
+4. Without a PR credential, download `policy-approval-proposal`. Its generated
+   `release/knowledge-maintenance.json` and
+   `release/policy-activations/<implementation-digest>.json` are the two files
+   for a maintainer approval PR. Create the named branch from current main
+   without upstream tracking, commit those files, and push with an explicit
+   same-name refspec. If main advances, rerun `prepare` instead of carrying
+   other changes into that approval PR.
+   Retry an interrupted approval request with the same proof. The helper reuses
+   an existing branch only when its commit, tree, and main parent match the
+   generated proposal, then returns its matching open PR or creates the missing
+   PR. Unrelated, stale, or concurrently changed state is rejected for review;
+   existing branch state is never overwritten.
+5. Merge only after the independent **Release activation proof** and normal
+   required checks succeed and the approval is reviewed. The renewal workflow
+   never merges the PR, creates release tags, or publishes distributions.
+
+New activation records use `proof_source_sha`: the historical commit on which
+the reviewed policy proof was produced. Existing `candidate_sha` records remain
+readable; providing both names is rejected. Existing coordinator proof runs
+retain their pinned branch and correlation checks. Manual proofs are accepted
+from main only through the explicit manual verification route.
+
+The coordinator identifies automatic proofs through authenticated dispatch
+receipts before considering manual approvals. Automatic approval PRs can be
+rebased after main advances even when their proposed audit is not yet on main.
+A committed manual audit must match the proof source, run, attempt, and
+implementation before its original hosted evidence is replayed.
+
+An activation-only merge changes main's commit SHA without changing the policy
+implementation digest or evaluated configuration. Keep `proof_source_sha`
+pointing to the proof commit; use the new main SHA as `candidate-sha` for normal
+**Release qualification**. Run qualification from main with policy shadow off.
+After it succeeds, dry-run **Promote qualified artifacts to PyPI** from main
+using that qualification run, `refs/heads/main`, and the bundle's distribution
+hashes. Create the release tag at the qualified SHA before requesting actual
+publication with the same bundle. Further release-source changes require a
+new full qualification.
+
 ## Git hook retirement
 
 Git hook installation has been removed. After updating the package, run the
@@ -214,8 +339,8 @@ wiki checks, trusted plugin validation, or team-owned review policy.
 Use `fail-on: unhealthy` to allow degraded-but-usable knowledge while blocking
 mixed snapshots, invalid governance, confirmed stale concepts, and invalid
 verification receipts. Use `fail-on: degraded` when any degraded result must
-block the job. `strict: "true"` also classifies indeterminate or nonsemantic
-source drift as unhealthy. Replace `<FULL_RELEASE_COMMIT_SHA>` with the full
+block the job. `strict: "true"` also classifies indeterminate or source-byte
+drift as unhealthy. Replace `<FULL_RELEASE_COMMIT_SHA>` with the full
 40-character SHA of an immutable released commit supporting v4; never use a
 branch or tag for a protected workflow.
 

{agent_wiki_cli-2.3.1 → agent_wiki_cli-2.4.0}/docs/cli-reference.md

@@ -12,8 +12,8 @@ task detector with Mermaid styling.
 | Task | Commands |
 |---|---|
 | Set up a wiki | [init](#init), [prepare-extractors](#prepare-extractors), [bootstrap](#bootstrap) |
-| Maintain and diagnose | [sync](#sync), [lint / ci-check](#lint-and-ci-check), [doctor](#doctor), [queue](#queue) |
-| Read and analyze | [extract](#extract), [context](#context), [source integration](#codebase-source-integration), [search](#search), [review](#review), [api-diff](#api-diff) |
+| Maintain and diagnose | [sync](#sync), [lint / ci-check](#lint-and-ci-check), [doctor](#doctor), [queue](#queue), [maintenance](#maintenance) |
+| Read and analyze | [extract](#extract), [context](#context), [task-context](#task-context), [source integration](#codebase-source-integration), [search](#search), [review](#review), [api-diff](#api-diff) |
 | Work with agents | [generate-prompt](#generate-prompt), [MCP](#mcp), [skills](#skills), [manual triggers](automation.md#manual-agent-triggers) |
 | Author and export docs | [docs](#docs), [site](#site), [Obsidian](#obsidian) |
 | Extend and collaborate | [install / plugins](#install-and-plugins), [team](#team), [knowledge](#knowledge) |
@@ -49,6 +49,8 @@ Scaffold the wiki structure and agent constraint file.
 
 ```bash
 llm-wiki init --agent claude
+llm-wiki init --agent claude --prepare-extractors
+llm-wiki init --prepare-extractors --helper-cache-dir .cache/llm-wiki-helpers
 llm-wiki init --agent copilot --wiki-dir .wiki
 llm-wiki init --agent cursor --no-quality-hints
 llm-wiki init --agent generic --issue-reporting
@@ -62,6 +64,29 @@ them when refreshing an existing initialization. On a refresh, omitting
 `--agent` reuses the stored agent; a project with no stored selection defaults
 to `generic`.
 
+Add `--prepare-extractors` to automatically prepare missing or stale extractor
+helpers before creating or refreshing the wiki scaffold. Setup detects helper
+languages from the selected source files, honoring `--source-selection` and
+the stored selection on subsequent runs. Current helpers are reused without
+requiring their build tools. Preparation may download dependencies or compile
+bundled helpers; the relevant Node.js/npm, Go, Cargo, or GHC toolchain must be
+available when a helper needs preparation. TypeScript/JavaScript analysis still
+requires Node.js to run its prepared helper.
+
+If preparation fails, setup exits unsuccessfully before changing the scaffold
+or agent configuration. Fix the reported problem and rerun the same command;
+helpers that were successfully prepared are reused. Repeat this setup after a
+package upgrade or a change in selected languages. The flag applies only to
+that invocation and does not enable preparation in read-only commands.
+
+`--helper-cache-dir PATH` requires `--prepare-extractors` and selects the same
+cache base as `prepare-extractors --cache-dir PATH`. Otherwise setup uses
+`LLM_WIKI_CACHE_DIR` or the repository's `.git/llm-wiki-extractors/`. Projects
+without Git need an explicit cache location only when selected languages need
+helpers. A custom cache location is not saved in the agent configuration:
+pass it to later commands with `--helper-cache-dir PATH`, or set
+`LLM_WIKI_CACHE_DIR` consistently for setup and analysis.
+
 ## `bootstrap`
 
 Generate the initial full wiki for an existing project.
@@ -372,8 +397,15 @@ description/example, `Annotated`, validator/config, enum-member, literal, and
 type-alias metadata without importing Pydantic or application modules.
 Python call targets follow lexical bindings. Builtins remain file-less calls;
 local declarations, aliases, and imports resolve only when their targets are
-justified. Uncertain rebinding and closures remain unresolved instead of linking
-to unrelated same-named functions. Optional `call_bindings` entries parallel a
+justified. Uniquely resolved local constructors, assigned constructor instances
+and explicit imported class aliases can identify method callers. Factories,
+shadowed or conflicting bindings, receiver/member mutations and uncertain
+control-flow paths remain located unresolved observations. Captured module, class
+and receiver namespace mutations can invalidate a target. Resolution uses lexical
+scope and captured evaluation order, including conditional and short-circuit
+expressions; it does not establish runtime execution. An absent edge never
+proves that no runtime caller exists. Uncertain closures do not link to unrelated
+same-named functions. Optional `call_bindings` entries parallel a
 callable's `calls` list, `python_bindings` describes module bindings, and
 `main_block_call_bindings` parallels guarded process-entry calls. Older
 inventories may omit these fields.
@@ -424,6 +456,11 @@ JSON payload includes top-level `warnings` only when such diagnostics exist.
 Prepare TypeScript/JavaScript dependencies and cached Go/Rust/Haskell helper
 binaries outside the lint/extract hot path.
 
+For automatic preparation during project setup, use
+`llm-wiki init --prepare-extractors`. This reuses valid helpers and prepares only
+missing or stale ones. `prepare-extractors` also checks the current build
+toolchain when explicitly rebuilding or refreshing the cache.
+
 ```bash
 llm-wiki prepare-extractors --src-dir .
 llm-wiki prepare-extractors --src-dir . --plan --format json
@@ -448,6 +485,18 @@ Commands that consume prepared Go/Rust/Haskell helpers accept
 This is separate from inventory-command `--cache-dir PATH`, which only controls
 where `llm-wiki-inventory-cache.json` is read and written.
 
+Missing-helper errors include a preparation command for the failing language,
+source root, and resolved helper cache. Run that command as an authorized setup
+step, then retry the original analysis with the same options. Keep
+`--source-selection` on the analysis command; a language-specific preparation
+command uses `--language` and cannot also take `--source-selection`. If no Git
+cache is available, the remedy proposes a cache under the source root's
+`.llm-wiki/`; select that base on later reads with `--helper-cache-dir` where
+supported, or `LLM_WIKI_CACHE_DIR`. Preparation failures include toolchain and
+retry guidance. `llm-wiki doctor --capabilities` provides read-only diagnosis.
+After updating the package, `llm-wiki upgrade` refreshes managed agent
+instructions so agents follow the helper recovery procedure.
+
 ## `lint` and `ci-check`
 
 Validate wiki links, orphan pages, entities, modules, workflows,
@@ -699,7 +748,7 @@ The v3 `health_details` object adds:
   and generation-option hashes. Comparison still uses exact producer versions;
   `analysis_contract: null` means no cross-version compatibility contract is available.
 - Disjoint `modeled` and `unmodeled` counts whose sum is `total`. Modeled outcomes
-  distinguish current, nonsemantic change, changed/missing source, incompatible
+  distinguish current, source-byte change with unchanged recorded structure, changed/missing source, incompatible
   basis and unknown evidence. Missing recorded evidence does not make a modeled
   concept unmodeled.
 - Separate evaluation, comparison-attempt and compatible-content counts.
@@ -724,11 +773,11 @@ resulting indeterminate drift as unhealthy.
 | Exit code | Status | Meaning |
 |---|---|---|
 | `0` | `healthy` | The committed snapshot is coherent and no health downgrade was found. |
-| `1` | `degraded` | Knowledge remains usable, but availability is degraded, freshness was not evaluated, a review expired, or drift is indeterminate/nonsemantic. |
+| `1` | `degraded` | Knowledge remains usable, but availability is degraded, freshness was not evaluated, a review expired, or drift is indeterminate or source bytes changed while recorded structure matched. |
 | `2` | `unhealthy` | A mixed snapshot, invalid governance or receipt, unsupported state, or confirmed stale concept was found. |
 | `3` | `absent` | Knowledge artifacts are absent or the wiki has not been initialized. |
 
-`--strict` promotes indeterminate and nonsemantic source drift from degraded to
+`--strict` promotes indeterminate and source-byte drift from degraded to
 unhealthy. It does not change the JSON shape. Shell automation should capture
 the JSON before applying its own threshold because codes `1` through `3` are
 health results, not serialization failures. The supported Python API exposes
@@ -941,6 +990,51 @@ counter. Python callers use `llm_wiki_cli.api.build_budgeted_context(...)` with
 a trusted counter implementing `identity`, `exact`, and `count(text)`; the
 result contains the emitted `rendered` text, `accounting`, and `ok` status.
 
+## `task-context`
+
+Gather evidence for explicit task requirements. Prefer task request v2 when
+supported; task v1 and legacy `context` calls retain their existing contracts.
+Save a request outside the source tree and use source-root-relative selectors.
+For example, with `src/app.py` defining `limit`, save `source-task.json`:
+
+```json
+{
+  "schema_version": "llm-wiki-task-request/v2",
+  "kind": "contract-change",
+  "requirements": [
+    {"id": "contract", "facet": "source-contract", "selector": "app.py:limit"}
+  ],
+  "options": {"knowledge_mode": "off", "budget_tokens": 32000}
+}
+```
+
+```bash
+llm-wiki task-context --request source-task.json --src-dir src --wiki-dir wiki
+llm-wiki task-context --request source-task.json --src-dir src --wiki-dir wiki --view compact-v1 --view-budget-tokens 32000 --canonical-output receipts/source-context.json
+```
+
+Canonical text is the default. Compact delivery is opt-in and needs a separate
+host-accessible canonical receipt outside both roots. Keep the request, profile,
+selection, tokenizer and output paths distinct. `--view-budget-tokens` chooses
+its separate presentation budget; no fixed token saving or small-budget fit is
+promised. Include the selected view once in the coding host.
+
+Choose `knowledge_mode: "off"` only when no native evidence is required; this
+route works without a wiki. Native v2 requirements need explicitly adopted
+sharded or packed knowledge. Keep `required` mode and the native requirements
+when a read fails; a failure never authorizes bootstrap or migration.
+`snapshot` reads committed native evidence, while `selected` captures declared
+source scope. `--allow-full-inventory` permits an explicitly requested broader
+scan; it does not expand an empty selection automatically.
+
+Request validation errors exit 2, workspace errors exit 1, and a minimum context
+that cannot fit exits 3 without partial context. A compact budget failure can
+retain a valid canonical receipt and leaves the view destination untouched.
+Facts, citations, gaps and static coverage remain qualified; a behavior
+requirement needs host verification. Session reuse is an optional Python/MCP
+interface with current input revalidation, not a general speedup guarantee.
+See [workflow recipes and limits](native-agent-workflow.md).
+
 ## Codebase source integration
 
 For research or indexing systems that need codebase evidence without adopting
@@ -1812,8 +1906,11 @@ llm-wiki search "KnowledgeModelError" --kind entities
 llm-wiki search "exact phrase" --mode substring
 ```
 
-Ranked mode combines exact page IDs, paths and defined symbols with lexical,
-title, path, and inbound-link relevance. Results include scores, reasons,
+Ranked mode keeps exact page IDs, paths and defined symbols ahead of fuzzy
+candidates, then weights informative lexical terms, section roles, titles,
+paths and bounded inbound-link relevance. The default `ranked` mode and explicit
+`ranked-v2` mode use `ranking_version: "llm-wiki-search/lexical-v2"`;
+`--mode ranked-v1` explicitly retains the earlier policy. Results include scores, reasons,
 snippets, content hashes, a corpus identity, and the ranking version. Stable
 path ordering resolves ties. `--mode substring` retains the earlier
 case-insensitive substring behavior and page ordering; MCP accepts the same
@@ -1829,10 +1926,26 @@ a larger value is requested. Blank queries and invalid limits exit `2`, leave
 stdout empty, and print argument diagnostics to stderr in both output formats.
 A valid query with no matches exits `0` with empty results.
 
-JSON responses from both the CLI and MCP disclose `mode` (`ranked` or
-`substring`), `total`, `returned`, and `bounds.results`, including truncation.
+JSON responses from both the CLI and MCP disclose `mode` (`ranked`,
+`ranked-v1`, `ranked-v2` or `substring`), `total`, `returned`, and
+`bounds.results`, including truncation.
 Ranked scores and provenance remain specific to ranked mode.
 
+Source augmentation and qualification are explicit read choices:
+
+```bash
+llm-wiki search "retry failure" --src-dir src --wiki-dir wiki --mode ranked-v2 --include-source
+llm-wiki search "retry failure" --src-dir src --wiki-dir wiki --discovery qualified-v1
+```
+
+Source indexing requires a valid committed manifest and only reads mapped
+module sources inside the selected boundary. Qualified discovery groups the
+returned candidates by validated owner and preserves section, omission and
+recorded review details. It does not establish live source freshness or approve
+prose. Both choices have additional capture/revalidation costs. Select an exact
+candidate, inspect its source and qualifiers, and retain missing or contradictory
+evidence. See [qualified discovery](native-agent-workflow.md#choose-an-interface).
+
 ## `queue`
 
 Select advisory maintenance work for a managed wiki:
@@ -1865,6 +1978,63 @@ identities even if every item fits. Reports from versions without this field
 have different identities. A valid advisory queue exits `0`, including when
 there is no recommended work.
 
+The JSON report's `qualification.ordinary_review_custody` describes captured
+ordinary-review authority. Its `availability` is `ready`, `partial`,
+`unadopted` or `unavailable`; `durable_owner_available` identifies whether
+an ordinary-review owner was captured, and `live_evaluation_performed` reports
+whether its status was evaluated against live inputs. Partial, unadopted or
+unavailable custody does not establish completed review. Even a ready status or
+an empty queue leaves `source_prose_correctness` as `not-established`.
+Inspect the affected source and semantic prose; use explicit
+[ordinary review tracking](maintenance.md) when durable review is needed.
+An empty queue does not establish ordinary-review completion.
+
+## `maintenance`
+
+Ordinary review tracking is optional and independent of human governance and
+knowledge storage format. Start from a coherent wiki, explicitly adopt, and
+retain the complete recovery snapshot outside the source and wiki roots:
+
+```bash
+llm-wiki maintenance adopt --src-dir src --wiki-dir wiki --recovery-dir maintenance-recovery
+llm-wiki maintenance status --src-dir src --wiki-dir wiki --format json
+llm-wiki maintenance status --src-dir src --wiki-dir wiki --snapshot --record-id RECORD_UUID
+```
+
+Adoption makes existing tracked prose unreviewed and preserves authored content.
+The marker, maintenance manifest owner and knowledge projections belong to one
+committed set. Flat maintenance manifests use v7; `--manifest-format indexed-v8`
+explicitly selects bounded manifest storage. Upgrade all readers and writers
+before adopting. This does not adopt sharded or packed knowledge automatically.
+
+Review the exact source and semantic section, then run the owning sync after
+the last prose edit. Capture current status for the selected record. Save its
+non-null `expected_basis` as `basis.json` outside both roots and substitute the
+actual record ID and captured state hash:
+
+```bash
+llm-wiki maintenance acknowledge --src-dir src --wiki-dir wiki --record-id RECORD_UUID --expected-state-hash STATE_HASH --basis-file basis.json --actor-kind agent --actor-id documentation-agent
+```
+
+Stale source, prose or state refuses acknowledgment. A repeated successful
+acknowledgment with the same actor/basis is idempotent. Later relevant changes
+reopen review, which survives sync and restarts. An agent or ordinary human
+actor records operational review; it neither grants human governance approval
+nor revives expired governance events. Snapshot status is historical, and
+read-only queue/context/MCP operations never acknowledge work.
+
+A missing or corrupt adopted owner needs its matching complete recovery bundle;
+sync cannot reconstruct history from projections:
+
+```bash
+llm-wiki maintenance recover --wiki-dir wiki --recovery-dir maintenance-recovery/committed --expected-adoption-id ADOPTION_UUID
+```
+
+Use the retained adoption ID. Recovery refuses unrelated edits or newer work;
+prepared-adoption and captured-preimage retries need their explicit options.
+See [ordinary review and recovery](maintenance.md) for exact eligibility and
+Python/MCP interfaces.
+
 ## `upgrade`
 
 Refresh framework-managed artifacts in place.