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

{agent_wiki_cli-2.3.2/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.2
+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

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

@@ -339,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.2 → 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) |
@@ -397,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.
@@ -741,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.
@@ -766,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
@@ -983,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
@@ -1854,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
@@ -1871,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:
@@ -1907,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.

agent_wiki_cli-2.4.0/docs/native-agent-workflow.md

@@ -0,0 +1,406 @@
+# Native coding workflow
+
+Use a provider whose CLI and Python API expose the task request, storage and
+optional delivery interfaces you select. Check `llm-wiki task-context --help`
+and `llm-wiki knowledge migrate --help` in each environment; a version number
+alone does not establish support for every format.
+
+For large native snapshots, [knowledge storage](knowledge-storage.md) describes
+explicit sharded or packed storage adoption and task request v2 with selected validation.
+Task request v1 retains its existing full-validation behavior.
+
+Prefer task request v2 for compatible integrations. Canonical delivery stays
+the default; compact views, sessions and source-augmented discovery are explicit
+choices with their own limits and costs.
+
+An explicit task request gathers qualified source and wiki evidence. The provider
+reads and reports; your coding host decides what to include, edit, execute and
+publish. Existing context calls retain their defaults.
+
+## Choose an interface
+
+| Operation | Python API | CLI | MCP |
+|---|---|---|---|
+| Ranked discovery | `search_wiki` | `search` | `search_wiki` |
+| Advisory maintenance | `build_maintenance_queue` | `queue` | `get_maintenance_queue` |
+| Exact query | `query_documentation` | `query --request FILE` | `query_documentation` |
+| Complete output budget | `build_budgeted_context` | `context --request FILE` | `build_budgeted_context` |
+| Task evidence | `build_task_context` | `task-context --request FILE` | `build_task_context` |
+| Validated reuse | `open_context_session` | — | `open_context_session`, `read_context_session`, `hint_context_session`, `close_context_session` |
+
+Search discovery preserves ranking reasons and corpus bounds. Exact queries use
+the existing [native query contract](native-knowledge-provider.md). A maintenance
+queue is advisory and never applies recommendations. Read its
+`qualification.ordinary_review_custody` availability, owner and live-evaluation
+fields before relying on ordinary-review history. Partial, unadopted or
+unavailable custody remains a gap. Even a ready status or an empty queue does
+not establish source/prose correctness or review completion; inspect the exact
+source and prose and follow [ordinary review tracking](maintenance.md) when needed.
+
+Ranked search weights informative terms and semantic sections, keeps exact page
+and declaration matches before fuzzy candidates, and labels relaxed matches for
+longer queries. The default `ranked` mode and explicit `ranked-v2` mode use
+`ranking_version: "llm-wiki-search/lexical-v2"`. `--mode ranked-v1` retains
+the earlier ranking policy;
+`--mode substring` performs literal text matching. All results remain discovery
+candidates and require exact inspection before a coding decision.
+
+Source text indexing is an explicit read and cost choice:
+
+```bash
+llm-wiki search "retry failure" --src-dir src --wiki-dir wiki --mode ranked-v2 --include-source
+```
+
+It requires a valid committed manifest and indexes only its mapped module sources
+inside the captured selection. Source snapshot validation and source-byte
+rechecks have separate costs; snippets can include static code or error-message text without proving
+runtime behavior. Narrow the selection when the declared indexing bounds cannot
+fit. Reads never execute the application, install helpers or migrate storage.
+
+To connect a symptom query to exact inspection, request qualified discovery:
+
+```bash
+llm-wiki search "retry failure" --src-dir src --wiki-dir wiki --discovery qualified-v1
+```
+
+The additional `discovery` response groups the returned candidates by validated
+owner and retains each page and distinct narrative section. Groups cover only
+the returned results; section omissions and limits remain explicit. Recorded
+source and review information describes the captured state. It does not establish
+live freshness, runtime behavior, semantic correctness or current approval.
+Pending and contradictory prose remain visible as separate evidence.
+
+Select a candidate explicitly, then pass its exact `path` to
+`api.inspect_concept(path, src_dir="src", wiki_dir="wiki", live=False)`.
+Continue with the resolved locator only when that response identifies one
+concept. Missing, ambiguous or unavailable outcomes require investigation;
+another fuzzy result cannot replace the selected identity automatically.
+Use the resolved exact source, concept and section anchors in the native task
+request below. Its compact view preserves unresolved requirements and bounds.
+
+Qualified discovery uses bounded selected native reads where supported.
+A wiki without committed native storage, or a valid unsupported layout within
+the capture bounds, leaves
+an explicit unavailable qualification and does not authorize adoption or
+migration. Exceeding capture or output bounds aborts the read, as does missing
+or inconsistent committed authority. Plain Markdown
+pages can still be read by exact path. Discovery's recorded pending review is a
+separate capture: selected task context reports its own maintenance scope and
+may leave current review state unavailable. When review status is decisive,
+re-read the corresponding record with `api.get_maintenance_status(...,
+record_id=record_id, live=False)`; request a live status separately when an
+actual current comparison is needed.
+
+## Source-only task without a wiki
+
+Choose this route when the task needs source evidence. It requires neither
+bootstrap nor a wiki. In a new example workspace, create `src/app.py`:
+
+```python
+def limit(value: int = 3) -> int:
+    return value
+```
+
+Save this request as `source-task.json` outside `src`:
+
+```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
+```
+
+Here `wiki` is an explicit in-project path that may be absent. `off` disables
+native selection; `auto` is not the same no-wiki recipe. Selectors are relative
+to `src`, so the declaration is `app.py:limit`, not `src/app.py:limit`.
+The Python route produces and validates the same canonical evidence:
+
+```python
+import json
+from pathlib import Path
+from llm_wiki_cli import api
+
+request = json.loads(Path("source-task.json").read_text(encoding="utf-8"))
+result = api.build_task_context(request, src_dir="src", wiki_dir="wiki")
+if result.ok:
+    payload = api.validate_task_context(result.rendered, request)
+    print(payload["coverage"])
+```
+
+Use your actual source root, configured selection and exact declaration instead
+of the example paths. Reads do not create the source file, install helpers or
+run the target project. One direct source read can be simpler for a tiny task.
+
+## Native task with explicit storage adoption
+
+Choose this route when a requirement needs committed concepts, semantic
+sections or typed relationships. For a new wiki, explicitly select bounded
+storage during authorized bootstrap:
+
+```bash
+llm-wiki bootstrap --src-dir src --wiki-dir wiki --knowledge-format sharded-v2
+```
+
+For an existing flat wiki, keep its current pages and complete snapshot. A task
+v2 native read requires sharded or packed knowledge storage; a flat rejection
+does not authorize migration.
+
+For a captured valid flat model, the task CLI returns exit 2 with
+`error.details.reason: "flat-native-adoption-required"` and an authorized
+migration-preview next action. This identifies the storage prerequisite; it
+does not audit the complete snapshot. Unknown or damaged roots receive no
+adoption hint. Migration validates companion authority before applying.
+
+With migration authorized, preview and apply it using an empty recovery directory
+outside both `src` and `wiki`:
+
+```bash
+llm-wiki knowledge migrate --wiki-dir wiki --to sharded-v2 --dry-run --recovery-dir storage-recovery
+llm-wiki knowledge migrate --wiki-dir wiki --to sharded-v2 --recovery-dir storage-recovery
+llm-wiki knowledge storage-check --wiki-dir wiki --full
+llm-wiki knowledge inspect-storage --wiki-dir wiki --selector page:modules/app.md --limit 10
+llm-wiki doctor --capabilities --src-dir src --wiki-dir wiki --format json
+```
+
+Dry-run does not write a recovery snapshot. Apply retains the prior snapshot;
+`storage-check --full` audits the result. Capability output can identify helper
+or producer prerequisites; resolve those only with setup authorization. Upgrade
+all readers and writers to support the selected schema before adoption.
+
+Save this native snapshot request as `native-task.json`:
+
+```json
+{
+  "schema_version": "llm-wiki-task-request/v2",
+  "requirements": [
+    {"id": "concept", "facet": "concept", "selector": "llm-wiki://modules/app"}
+  ],
+  "options": {"knowledge_mode": "required", "read_scope": "snapshot", "budget_tokens": 32000}
+}
+```
+
+```bash
+llm-wiki task-context --request native-task.json --src-dir src --wiki-dir wiki
+```
+
+This is committed snapshot evidence. It does not establish live source
+currentness, prose approval or runtime behavior. Use `read_scope: "selected"`
+and explicit source requirements when live source evidence is needed. Keep
+native requirements and `required` mode when a native read fails; never turn
+them into an `off` success. Missing, corrupt or unsupported roots require a
+qualified failure and an authorized complete recovery, not hidden bootstrap.
+For a failed storage migration, restore its retained complete snapshot:
+
+```bash
+llm-wiki knowledge recover-storage --wiki-dir wiki --recovery-dir storage-recovery --dry-run
+llm-wiki knowledge recover-storage --wiki-dir wiki --recovery-dir storage-recovery
+```
+
+Storage recovery is bound to the original or target migration generation. It
+refuses unrelated root edits, changed Markdown authority or newer committed
+work. Restore an authorized matching complete snapshot when that eligibility
+check fails; do not force a replacement.
+
+Storage adoption is separate from optional
+[ordinary review tracking](maintenance.md). A
+`.llm-wiki-maintenance-adoption.json` marker requires its matching maintenance
+owner. Restore missing or corrupt adopted authority through the complete
+[maintenance recovery route](maintenance.md#recover-complete-authority) before
+sync; manifestless seeding cannot reconstruct its history. `indexed-v8`
+requires that adopted owner and changes manifest storage, not flat knowledge
+storage. Neither kind of adoption happens during a read.
+
+For an owner adopted with a retained `maintenance-recovery` directory, use its
+actual adoption ID and complete committed snapshot:
+
+```bash
+llm-wiki maintenance recover --wiki-dir wiki --recovery-dir maintenance-recovery/committed --expected-adoption-id ADOPTION_UUID
+```
+
+Replace `ADOPTION_UUID` with the retained marker's actual ID. A storage-migration
+recovery copy is not a substitute for this matching complete maintenance bundle.
+
+## Interpret evidence requirements
+
+Task kinds are `orientation`, `bug-diagnosis`, `contract-change` and `refactor`.
+Anchors have a `kind` (`source`, `symbol`, `wiki` or `concept`) and a `value`.
+Source selectors are portable relative paths. Declaration coordinates may include
+an exact owner and occurrence, such as `retry.py:Client.retry#2`. An unqualified
+name can remain ambiguous. An optional `task_ref` is a host label, separate from
+the provider's content identity.
+
+Requirements declare `id`, `facet`, `selector` and optionally `criterion`
+(`present` or `complete`). Supported facets are `source-contract`, `callers`,
+`callees`, `concept`, `semantic-section`, `typed-relationships`, `entrypoint` and
+`dependency`. A `behavior` requirement reports that host verification is needed.
+Static observations cannot establish complete runtime behavior or prove the
+absence of callers. Coverage concerns emitted evidence; it does not mean the task
+is solved or that prose is correct.
+
+Python method callers can resolve through uniquely justified local constructors,
+assigned constructor instances and explicit imported class aliases. Factories,
+shadowed/conflicting bindings, receiver mutations and uncertain loop or exception
+paths stay located unresolved evidence. 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.
+Inspect exact source before relying on
+a candidate; neither a missing edge nor a non-truncated response proves runtime
+completeness.
+
+Source bytes, recorded declaration structure and captured Python executable
+syntax are separate observations. A body or default edit can change executable
+syntax while an unrelated declaration remains unchanged. Matching syntax does
+not prove behavior, dependency stability or authored prose correctness. Other
+languages and legacy artifacts may lack executable comparison evidence. The
+legacy `nonsemantic-source-change` value means “Source changed; recorded
+structure unchanged; behavior not evaluated.” Review tracking requires its own
+explicit adoption; an untracked review state does not mean approval.
+
+Results preserve a captured basis, citations, qualifiers and every requirement's
+gap. Follow-ups contain bounded selectors and reasons for the host to consider.
+JSON serialization keeps unclosed source Markdown fences inside their data fields.
+
+## Explicit profiles and work limits
+
+Use `api.load_workflow_profile(FILE)` or pass a `WorkflowProfile`/profile mapping.
+The profile schema is `llm-wiki-workflow-profile/v1` with a `settings` object.
+Profiles are never discovered automatically. The bundled `native-coding` skill
+includes a starting profile; adopt it explicitly with the existing skills lifecycle.
+
+Defaults use native `auto` mode, freshness preference, selected source reads,
+estimated counting, 32,000 output tokens, 64 captured inputs, 8 MiB each of source
+and wiki inputs, four read rounds and four follow-up proposals. A trusted
+`WorkflowPolicy` constrains scopes and limits. Request `options` can choose
+per-call settings within those ceilings. Neither profiles nor task text can
+change roots, load tokenizer paths, prepare helpers, enable plugins or execute
+commands. Source selection and helper configuration remain host arguments.
+
+`snapshot` reads wiki evidence without extracting source. `selected` captures
+explicit source coordinates and relevant selection/package/infrastructure inputs.
+`full-inventory` requires permission from the host policy and an explicit request.
+An empty selection never expands into a full scan. Questions outside the permitted
+scope return a gap and a proposed next read.
+
+Request text is limited to 16 KiB, coordinates to 4 KiB, and anchors/requirements
+to 100 each. CLI JSON input is limited to 1 MiB and rejects duplicate keys,
+unknown fields, unsupported versions and coerced values. CLI input errors exit 2;
+workspace errors exit 1; a minimum context that cannot fit exits 3 with no partial
+context. Input byte limits apply per capture; validation rereads and parser work
+are separate costs.
+
+Source directory discovery is capped at `max(4096, 128 × max_files)` entries,
+up to 100,000; wiki discovery is capped at 10,000 entries. Excessive discovery returns an explicit work-limit gap before
+source extraction. A narrower source root or an allowed higher limit can help.
+
+Native `required` mode requires availability. It does not require a positive
+currentness verdict. Freshness preference does not enable native mode or approve
+semantic content.
+
+## Optional compact delivery
+
+Canonical output remains the default. Compact delivery is an explicit
+presentation of the same validated facts, gaps, citations and qualifiers.
+Save the full canonical receipt outside the source and wiki trees and away
+from the request, profile, tokenizer and selection files:
+
+```bash
+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
+```
+
+The compact view goes to stdout. Add `--output views/source-context.json` for a
+separate view file. A source root of `.` requires both artifacts outside that
+entire root; choose destinations accordingly. Redirected paths and overlaps
+are rejected. A canonical receipt is host custody, not permission to include
+both representations in the model prompt.
+
+```python
+view_options = {"schema_version": "llm-wiki-task-view-request/v1", "budget_tokens": 32000}
+view = api.build_compact_task_context(
+    request, view_options=view_options, src_dir="src", wiki_dir="wiki"
+)
+if view.ok:
+    api.validate_compact_task_context(view.rendered, view.canonical_text, request, view_options=view_options)
+    facts = api.expand_compact_task_context(view.rendered, view.canonical_text, request, view_options=view_options)
+```
+
+Compact output may still exceed a small budget; there is no promised 1,000-token
+fit or fixed percentage saving. If the compact minimum cannot fit, CLI exits 3
+with its counted diagnostic, writes the valid canonical receipt when available,
+and leaves the view output untouched. If canonical evidence cannot fit, no
+receipt is fabricated. Estimated counts remain estimates.
+
+Sessions support explicit `read_compact(..., view_options=...)` and exact
+`canonical_receipt(request_id, result_id)` lookup. Configured MCP sessions expose
+`read_compact_context_session` and `get_task_context_receipt`. The compact tool
+returns view text plus bounded metadata; receipt lookup returns canonical text
+separately. Lost, expired or closed custody needs a fresh read. Historical
+receipts bind captured bytes; `current=True` requires current revalidation.
+Metadata visibility depends on the host. Fetching a receipt and including it
+with the compact view can cost more than canonical output alone.
+
+## Counting and MCP delivery
+
+The v3 MCP tool requires `protocol: "llm-wiki-context/v3"` and `changes`, which
+accepts explicit paths, a base/head range, or staged changes. Use
+`{"mode": "paths", "paths": []}` for no supplied changes. Old MCP context tools and
+resource URIs retain their response shapes.
+
+Canonical v3 and task tools return one canonical text block without a structured copy of
+the context. Include that text once. Exact counting requires a trusted Python
+counter or an explicitly configured server `--tokenizer FILE`; tool input cannot
+choose the tokenizer file. Estimated counts remain labeled estimates. Accounting
+covers canonical context text, including its accounting fields. MCP and host
+framing, session metadata and model-side framing are separate costs.
+
+## Optional sessions and resume
+
+```python
+with api.open_context_session(src_dir="src", wiki_dir="wiki") as session:
+    first = session.read(request)
+    again = session.read(request, if_result_id=first.result_id)
+    # Unchanged requires current input validation.
+```
+
+Sessions default to eight entries, 16 MiB retained state and a five-minute expiry.
+They serialize calls within one instance, return detached data, and bind to their
+creating workspace. Changed roots or working directories require a new session.
+Close sessions at disconnect or cancellation. Set `reuse=False`, use zero entries,
+or use `build_task_context` for cold reads with the same feature coverage.
+
+Source membership and bytes, ignore/selection inputs, wiki artifacts, producer
+configuration and Git metadata are rechecked. Events only invalidate state;
+lost events cannot authorize reuse. Unsaved buffers require save/defer handling.
+Helper-backed captures use cold reads when a complete bounded producer check is
+unavailable. No continuous freshness or general speedup is promised.
+
+Session metadata reports reuse, validation work, elapsed time and retained memory
+outside the portable task identity. Embedded task work describes its originating
+read. Optional deltas require an exact retained base; use
+`api.apply_task_delta(base_text, delta, request)` to reconstruct and validate the
+full canonical context. Missing bases fall back to a full result. Wrong and
+out-of-order bases are rejected. Whole-value array replacement preserves deletions
+and changed qualifiers.
+
+MCP sessions require `--enable-sessions`. Handles belong to that server and its
+configured workspace. Full responses carry canonical context in text and separate
+session metadata in structured content. Delta text is a delta envelope; embedded
+accounting describes reconstructed context. Session delivery counters describe
+the transmitted context or delta. Reconnect with a fresh session and validate
+saved context before reuse.
+
+For a persisted handoff, `api.reconcile_task_context(saved_text, request, ...)`
+returns one fresh scoped context together with the input-basis comparison and
+the existing packet reconciliation facets. A matching basis and semantic approval
+are separate results. Legacy packet reconciliation keeps its existing read scope.
+
+See the [downstream coding example](../examples/native-workflow/README.md) for a
+host-owned edit, behavior check, durable explanation and resumed handoff. This
+workflow remains opt-in; comparative model benefit has not been established.

{agent_wiki_cli-2.3.2 → agent_wiki_cli-2.4.0}/docs/wiki-guide.md

@@ -43,7 +43,10 @@ dependency-page presence, and internal wiki links; and the experimental
 `.llm-wiki-knowledge.json`, a deterministic evidence-aware projection of those
 canonical pages. Manifest v5 is the current writer format. All three JSON
 artifacts are CLI-owned generated state and must not be edited by hand; the
-manifest commits the surface and knowledge projections as one snapshot. The
+manifest commits the surface and knowledge projections as one snapshot. Explicit
+[ordinary review adoption](maintenance.md) adds durable pending/acknowledged
+section records and an immutable marker, using flat manifest v7 or indexed v8;
+the default unadopted writer remains v5. The
 experimental knowledge projection is evidence, not an editable authority. Its
 observation-versus-freshness model,
 availability states, strict-lint policy, context filters, API/MCP envelopes,