@h1v35/hivex 0.2.0 → 0.2.2

package/README.md

@@ -1,39 +1,27 @@
 # Hivex
 
-Project decisions, dependencies and exceptions for the agent responsible for implementation and
-review. Markdown remains authority; Hivex supplies context so agents can act autonomously without
-reopening settled decisions.
+Project decisions, dependencies and exceptions for the agent responsible for implementation and review. Markdown remains authority; Hivex supplies context so agents can act autonomously without reopening settled decisions.
 
-Hivex is a TypeScript/Bun CLI. The current knowledge profile is Luna/max through native Codex and the
-user's ChatGPT subscription, without silent fallback. The implementing agent may use another model.
-Model invocation is localized for future configuration; multiple providers are not yet validated.
+Hivex is a TypeScript/Bun CLI. The current knowledge profile is Luna/max through native Codex and the user's ChatGPT subscription, without silent fallback. The implementing agent may use another model. Model invocation is localized for future configuration; multiple providers are not yet validated.
 
 ## Current delivery
 
-This release-in-development supplies initial updates and task consultation (#47), plus automatic
-incremental maintenance and interpretation repair (#48), and task/diff review assistance (#19).
-Publication (#21) prepares early use; introduction in Compi is a separate step. It is not complete Compi adoption or legacy retirement.
+This release-in-development supplies initial updates and task consultation (#47), plus automatic incremental maintenance and interpretation repair (#48), and task/diff review assistance (#19). Release preparation remains separate from this CLI contract.
 
-No installed command approves an implementation. The principal reviewer verifies findings, tests and
-the actual source evidence. See the [approved product decision](docs/adr/0010-practical-knowledge-assistance.md).
+No installed command approves an implementation. The principal reviewer verifies findings, tests and the actual source evidence. See the [approved product decision](docs/adr/0010-practical-knowledge-assistance.md).
 
 ## Install the CLI and skill
 
 Requires Bun 1.4.2. Once the release is available from npm:
 
 ```sh
-bun add --dev --exact @h1v35/hivex@0.1.0
+bun add --dev --exact @h1v35/hivex
 bun hivex --help
 ```
 
-Copy `node_modules/@h1v35/hivex/skills/hivex` into the skill directory used by your agent. For an
-agent that discovers project skills in `.agents/skills`, use `.agents/skills/hivex`. Keep the CLI and
-skill at the same release; upgrade the copied skill when upgrading the package. The skill and its
-Markdown guide are portable and do not require Compi's private tools or other installed skills.
+Copy `node_modules/@h1v35/hivex/skills/hivex` into the skill directory used by your agent. For an agent that discovers project skills in `.agents/skills`, use `.agents/skills/hivex`. Keep the CLI and skill at the same release; upgrade the copied skill when upgrading the package. The skill and its Markdown guide are portable and do not require private tools or other installed skills.
 
-The current knowledge profile needs an authenticated Codex CLI session with the selected Luna/max
-model available. Native invocation checks that profile and stops rather than silently falling back.
-Document discovery and version checks work without a model. See the CLI help for bounded model work.
+The current knowledge profile needs an authenticated Codex CLI session with the selected Luna/max model available. Native invocation checks that profile and stops rather than silently falling back. Document discovery and version checks work without a model. See the CLI help for bounded model work.
 
 ## Run
 
@@ -46,11 +34,9 @@ bun hivex sources --root /path/to/project
 bun hivex update --root /path/to/project --max-calls 0
 ```
 
-The scoped package name is `@h1v35/hivex`, with command `hivex` and MIT license. Publication and registry
-installation are tracked separately; do not fetch the unrelated unscoped npm package.
+The scoped package name is `@h1v35/hivex`, with command `hivex` and MIT license. Publication and registry installation are tracked separately; do not fetch the unrelated unscoped npm package.
 
-Documents need no Git repository or commit. They can live at monorepo, package or module level and
-use their project's own Markdown format. An optional `hivex.json` selects relative globs:
+Documents need no Git repository or commit. They can live at monorepo, package or module level and use their project's own Markdown format. An optional `hivex.json` selects relative globs:
 
 ```json
 {
@@ -60,16 +46,7 @@ use their project's own Markdown format. An optional `hivex.json` selects relati
 }
 ```
 
-Without configuration, Hivex selects Markdown files under the project. It skips dependencies,
-its own cache, Git metadata and private dot directories; explicitly named documentation directories
-can be selected. `history` declares additional Markdown that remains readable evidence while staying
-out of ordinary update and consultation ingestion. Use `--source <document>` with `ask` or `review`
-to select it, or let a known relationship bring back the bounded ranges it requires. Historical
-metadata and evidence carry `historical: true`; an extracted decision from that source remains
-`historical`, even when the transport suggests another status. An `exclude` glob wins over `history`.
-Symlinks are not followed and protected directories and scope escapes remain rejected. The previous
-experimental `collections` configuration is rejected with a migration message rather than silently
-reinterpreted.
+Without configuration, Hivex selects Markdown files under the project. It skips dependencies, its own cache, Git metadata and private dot directories; explicitly named documentation directories can be selected. `history` declares additional Markdown that remains readable evidence while staying out of ordinary update and consultation ingestion. Use `--source <document>` with `ask` or `review` to select it, or let a known relationship bring back the bounded ranges it requires. Historical metadata and evidence carry `historical: true`; an extracted decision from that source remains `historical`, even when the transport suggests another status. An `exclude` glob wins over `history`. Symlinks are not followed and protected directories and scope escapes remain rejected. The previous experimental `collections` configuration is rejected with a migration message rather than silently reinterpreted.
 
 ## Recover context
 
@@ -83,42 +60,17 @@ bun hivex ask "What did the old cache policy require?" --source docs/archive/old
 bun hivex ask "How should private cached data behave when access is revoked?" --root /path/to/project
 ```
 
-`sources` returns document metadata without their full text and a snapshot-bound continuation when
-more records remain. Resume with `--cursor`. `read` returns original text, its version and line ranges;
-use `--from`, `--to` and `--max-bytes` for a bounded passage. Continuation and omitted content remain
-explicit. A working version is not evidence of approval.
-
-Search covers both extracted decisions and original Markdown, so terminology omitted from a summary
-remains discoverable. When needed, select a known document with `--source` in a consultation rather
-than reopening a settled question with the owner. Historical sources are not searched into an ordinary
-consultation merely because they are available; a focused source or a known dependency is required.
-If a necessary historical source is excluded or unavailable, the result names the missing evidence.
-An unconsulted historical or unavailable local Markdown link is reported for the responsible agent
-to assess with `read` or `--source`; merely linking to an archive does not ingest it automatically.
-
-Search and neighbor traversal are deterministic and make no model calls. Neighbor traversal includes
-indirect connections within `--limit` and lists decisions it could not expand. Stale knowledge is not
-presented as current evidence. `status` reports available knowledge and documents requiring attention.
-
-`ask` first detects added, changed and removed Markdown. It updates at most one bounded batch,
-prioritizing matching fragments, relevant documents and their known dependencies, then asks Luna/max over
-the available decisions and original Markdown. Its default budget is three calls for the complete
-update/check/answer operation. If the budget ends before the answer, repeat the same task with an
-authorized higher total: the work, progress and consumption are retained. An unchanged task reuses
-its answer. Use explicit `update` to advance remaining corpus batches; pending coverage stays visible.
-
-Changed sources bring their known incoming and outgoing neighbors into comparison, including
-relationships supported by a third document. Deleted sources are removed from pending ingestion;
-`unavailableDocuments` identifies dependencies that can no longer be verified. Source-local check
-findings remain scoped, so unrelated consultations can use their valid knowledge.
-It explains applicability and uncertainty. The evidence text in the result is read from the cited
-source ranges, not copied from a model-generated quotation. Large sources are supplied as relevant units within the context limit; `omittedUnits` reports
-unread portions so a partial answer is not mistaken for complete coverage. Identical retained consultations are
-reused. A partial result remains useful within its declared limits.
-
-Hivex does not compact, move or rewrite Markdown. Authors preserve the original historical text,
-dates, links and anchors; Hivex exposes the selected source version and line ranges while keeping
-historical applicability and conditions visible.
+`sources` returns document metadata without their full text and a snapshot-bound continuation when more records remain. Resume with `--cursor`. `read` returns original text, its version and line ranges; use `--from`, `--to` and `--max-bytes` for a bounded passage. Continuation and omitted content remain explicit. A working version is not evidence of approval.
+
+Search covers both extracted decisions and original Markdown, so terminology omitted from a summary remains discoverable. When needed, select a known document with `--source` in a consultation rather than reopening a settled question with the owner. Historical sources are not searched into an ordinary consultation merely because they are available; a focused source or a known dependency is required. If a necessary historical source is excluded or unavailable, the result names the missing evidence. An unconsulted historical or unavailable local Markdown link is reported for the responsible agent to assess with `read` or `--source`; merely linking to an archive does not ingest it automatically.
+
+Search and neighbor traversal are deterministic and make no model calls. Neighbor traversal includes indirect connections within `--limit` and lists decisions it could not expand. Stale knowledge is not presented as current evidence. `status` reports available knowledge and documents requiring attention.
+
+`ask` first detects added, changed and removed Markdown. It updates at most one bounded batch, prioritizing matching fragments, relevant documents and their known dependencies, then asks Luna/max over the available decisions and original Markdown. Its default budget is three calls for the complete update/check/answer operation. If the budget ends before the answer, repeat the same task with an authorized higher total: the work, progress and consumption are retained. An unchanged task reuses its answer. Use explicit `update` to advance remaining corpus batches; pending coverage stays visible.
+
+Changed sources bring their known incoming and outgoing neighbors into comparison, including relationships supported by a third document. Deleted sources are removed from pending ingestion; `unavailableDocuments` identifies dependencies that can no longer be verified. Source-local check findings remain scoped, so unrelated consultations can use their valid knowledge. It explains applicability and uncertainty. The evidence text in the result is read from the cited source ranges, not copied from a model-generated quotation. Large sources are supplied as relevant units within the context limit; `omittedUnits` reports unread portions so a partial answer is not mistaken for complete coverage. Identical retained consultations are reused. A partial result remains useful within its declared limits.
+
+Hivex does not compact, move or rewrite Markdown. Authors preserve the original historical text, dates, links and anchors; Hivex exposes the selected source version and line ranges while keeping historical applicability and conditions visible.
 
 ## Update and repair knowledge
 
@@ -126,26 +78,11 @@ historical applicability and conditions visible.
 bun hivex update --root /path/to/project --max-calls 2
 ```
 
-An update splits large Markdown into line-preserving units of at most 8 KiB, preferring Markdown
-boundaries. Each round selects at most four units and 16 KiB of target text, with up to 8 KiB of
-relevant existing evidence, then performs one additional check. Original document IDs and line
-numbers survive splitting. Earlier rounds remain queryable while `pendingUnits` and `pendingDocuments`
-show unfinished coverage. Sources up to 32 MiB can be split, within a 64 MiB loaded-corpus limit;
-narrow the selected paths if that limit is reached. A line too large to fit is explicitly reported as unread, never silently cut.
-
-Sources declared by `history` are not part of an ordinary update. A focused `ask` or `review` adds
-only its selected bounded units to the same resumable work; a known dependency can add the ranges
-needed to verify it. The work budget, graph knowledge and cache survive resumption.
-Changing an unrelated historical document does not start a fresh consultation budget. Current
-documents take priority when the loaded-corpus limit is reached; narrow the configured scope to
-access sources outside the reported coverage.
-
-Each extraction and check is checkpointed. Resuming continues the same work and never repeats its
-completed rounds. Successful structured model results are cached in the same store by the complete
-request, schema and model profile; an identical request can be reused without a call, even when
-reconstructing earlier knowledge. Changed context invalidates that cache entry. Context discovery considers authored links, lexical
-matches and recent decisions; `relationshipCoverage` states that this is bounded, not exhaustive. Cache hits are
-reported separately from calls and tokens; this is an optimization, not documentary authority.
+An update splits large Markdown into line-preserving units of at most 8 KiB, preferring Markdown boundaries. Each round selects at most four units and 16 KiB of target text, with up to 8 KiB of relevant existing evidence, then performs one additional check. Original document IDs and line numbers survive splitting. Earlier rounds remain queryable while `pendingUnits` and `pendingDocuments` show unfinished coverage. Sources up to 32 MiB can be split, within a 64 MiB loaded-corpus limit; narrow the selected paths if that limit is reached. A line too large to fit is explicitly reported as unread, never silently cut.
+
+Sources declared by `history` are not part of an ordinary update. A focused `ask` or `review` adds only its selected bounded units to the same resumable work; a known dependency can add the ranges needed to verify it. The work budget, graph knowledge and cache survive resumption. Changing an unrelated historical document does not start a fresh consultation budget. Current documents take priority when the loaded-corpus limit is reached; narrow the configured scope to access sources outside the reported coverage.
+
+Each extraction and check is checkpointed. Resuming continues the same work and never repeats its completed rounds. Successful structured model results are cached in the same store by the complete request, schema and model profile; an identical request can be reused without a call, even when reconstructing earlier knowledge. Changed context invalidates that cache entry. Context discovery considers authored links, lexical matches and recent decisions; `relationshipCoverage` states that this is bounded, not exhaustive. Cache hits are reported separately from calls and tokens; this is an optimization, not documentary authority.
 
 To correct derived knowledge against unchanged Markdown, use:
 
@@ -153,41 +90,17 @@ To correct derived knowledge against unchanged Markdown, use:
 bun hivex update --root /path/to/project --repair docs/cache.md --reason "The source specifies seven days, not indefinite retention."
 ```
 
-Repair replaces the affected unit's interpretations and revisits its relationships without editing
-Markdown. Its reason guides comparison with the source; it does not create new authority. Repeating
-the same completed repair reuses its work. A genuine unresolved documentary conflict still needs a
-decision by the responsible person.
-
-The default explicit-update work budget is two invocation attempts and 131,072 input bytes. `--max-calls` and
-`--max-input-bytes` set totals for the complete work, including extraction, check and resumption.
-A zero-call update reports pending documents without invoking the model. An exhausted work item
-retains its progress; repeating the command does not reset its counter. An authorized larger total
-can complete the remaining stage without repeating completed extraction.
-
-A failed or unfinished invocation is not retried automatically by increasing the budget. Inspect its
-reported outcome and usage first. `--retry-failed` can explicitly resume a safely ended failure within
-the same work budget; uncertain invocations remain blocked. A completed adverse check is not an
-invocation failure and is never retried by this flag. Uncertain or pending knowledge does not become a blanket pass.
-The project-local `.hivex/knowledge.sqlite` stores working knowledge and execution accounting;
-no source Markdown is rewritten. Preserve it when work evidence is needed. Storage is bounded at
-64 MiB; do not delete an active store to hide unfinished calls or reset a work budget.
-
-`recover` inspects abandoned work without invoking the model or killing processes. Live owners or
-native processes remain protected. If local processes ended but remote delivery is uncertain,
-`recover --acknowledge-uncertain` records an explicit acknowledgement; original reports and unknown
-usage remain visible. Recovery itself never retries: a subsequent `--retry-failed` uses the retained
-work budget. Do not treat acknowledgement as proof that the earlier remote turn completed.
-
-`prune` releases space occupied by old completed work and cached results, retaining the graph and all
-unfinished work, attempts and budgets. It keeps the newest eight completed works and 64 cached
-results by default; `--keep-completed` and `--keep-caches` change those counts. Pruned answers can
-require a new model call when requested again. Export evidence before pruning if historical reports
-are needed; pruning is explicit, never an automatic budget reset.
-
-Native operations accept `--codex` and `--deadline-ms`; the default deadline is 30 minutes. Consultation
-context defaults to 65,536 bytes and can be bounded with `--max-context-bytes`. Limits are reported,
-not met by silently cutting a rule or pretending omitted evidence was reviewed. Input-byte and call
-budgets limit work; reported token usage is actual consumption, including known failed attempts.
+Repair replaces the affected unit's interpretations and revisits its relationships without editing Markdown. Its reason guides comparison with the source; it does not create new authority. Repeating the same completed repair reuses its work. A genuine unresolved documentary conflict still needs a decision by the responsible person.
+
+The default explicit-update work budget is two invocation attempts and 131,072 input bytes. `--max-calls` and `--max-input-bytes` set totals for the complete work, including extraction, check and resumption. A zero-call update reports pending documents without invoking the model. An exhausted work item retains its progress; repeating the command does not reset its counter. An authorized larger total can complete the remaining stage without repeating completed extraction.
+
+A failed or unfinished invocation is not retried automatically by increasing the budget. Inspect its reported outcome and usage first. `--retry-failed` can explicitly resume a safely ended failure within the same work budget; uncertain invocations remain blocked. A completed adverse check is not an invocation failure and is never retried by this flag. Uncertain or pending knowledge does not become a blanket pass. The project-local `.hivex/knowledge.sqlite` stores working knowledge and execution accounting; no source Markdown is rewritten. Preserve it when work evidence is needed. Storage is bounded at 64 MiB; do not delete an active store to hide unfinished calls or reset a work budget.
+
+`recover` inspects abandoned work without invoking the model or killing processes. Live owners or native processes remain protected. If local processes ended but remote delivery is uncertain, `recover --acknowledge-uncertain` records an explicit acknowledgement; original reports and unknown usage remain visible. Recovery itself never retries: a subsequent `--retry-failed` uses the retained work budget. Do not treat acknowledgement as proof that the earlier remote turn completed.
+
+`prune` releases space occupied by old completed work and cached results, retaining the graph and all unfinished work, attempts and budgets. It keeps the newest eight completed works and 64 cached results by default; `--keep-completed` and `--keep-caches` change those counts. Pruned answers can require a new model call when requested again. Export evidence before pruning if historical reports are needed; pruning is explicit, never an automatic budget reset.
+
+Native operations accept `--codex` and `--deadline-ms`; the default deadline is 30 minutes. Consultation context defaults to 65,536 bytes and can be bounded with `--max-context-bytes`. Limits are reported, not met by silently cutting a rule or pretending omitted evidence was reviewed. Input-byte and call budgets limit work; reported token usage is actual consumption, including known failed attempts.
 
 ## Share knowledge through Git
 
@@ -196,21 +109,19 @@ bun hivex snapshot export --root /path/to/project
 bun hivex snapshot import --root /path/to/project
 ```
 
-`snapshot export` writes `.hivex/graph.json` atomically as stable, readable JSON. Commit that file
-alongside the Markdown it describes to share decisions, relationships, source versions, evidence,
-available provenance and coverage. It exports the graph, not work records, process identities,
-budgets or cached model answers. Both snapshot operations make zero model calls.
+`snapshot export` writes `.hivex/graph.json` atomically as stable, readable JSON. Commit that file alongside the Markdown it describes to share decisions, relationships, source versions, evidence, available provenance and coverage. It exports the graph, not work records, process identities, budgets or cached model answers. Snapshot operations make zero model calls.
+
+A fresh clone can use `search`, `neighbors` and `status` directly from the shared snapshot without creating a local database. Its first update reuses matching ingestion units and starts local work accounting. If a local graph already exists, it takes precedence: use `snapshot import` to adopt a new shared version. Import refuses while local work is unfinished and never resets attempts or budgets. Complete or recover that work through its normal lifecycle first.
+
+When Markdown moves, explicitly relocate its knowledge before the next update:
+
+```sh
+bun hivex snapshot relocate docs/old-guide.md docs/guidelines/guide.md --root /path/to/project
+```
 
-A fresh clone can use `search`, `neighbors` and `status` directly from the shared snapshot without
-creating a local database. Its first update reuses matching ingestion units and starts local work
-accounting. If a local graph already exists, it takes precedence: use `snapshot import` to adopt a
-new shared version. Import refuses while local work is unfinished and never resets attempts or
-budgets. Complete or recover that work through its normal lifecycle first.
+The old source must no longer be selected, and the destination must be selected current Markdown. Relocation preserves IDs, relationships, source versions and uncertainty, leaving existing work, cached answers and budgets intact. It makes zero model calls and refuses unfinished local work. An identical move to a destination without prior knowledge reuses ingestion coverage when all retained source evidence has matching, known versions. If content changed, source versions are mixed or missing, or the destination already had knowledge, its coverage becomes pending so the usual update/check can validate the result. Mismatched evidence remains stale until then. Keep the relocation report with the change and export the final graph; do not use relocation to hide unrelated missing evidence.
 
-The snapshot response identifies current, stale and unavailable source versions, pending units and
-warnings. A changed or absent source is not silently current; matching sources remain reusable.
-Partial and uncertain knowledge can be shared with those states retained. Freshness is not proof
-that a model interpretation is correct: the cited Markdown remains authority.
+The snapshot response identifies current, stale and unavailable source versions, pending units and warnings. A changed or absent source is not silently current; matching sources remain reusable. Partial and uncertain knowledge can be shared with those states retained. Freshness is not proof that a model interpretation is correct: the cited Markdown remains authority.
 
 Keep only the shared graph under version control, for example:
 
@@ -219,19 +130,13 @@ Keep only the shared graph under version control, for example:
 !/.hivex/graph.json
 ```
 
-Read-only queries do not rewrite the snapshot. Export intentionally when reusable knowledge changes,
-not on every consultation. Invalid snapshots or symbolic-link paths fail without replacing local
-knowledge. Existing local stores continue to work without a shared file.
+Read-only queries do not rewrite the snapshot. Export intentionally when reusable knowledge changes, not on every consultation. Invalid snapshots or symbolic-link paths fail without replacing local knowledge. Existing local stores continue to work without a shared file.
 
 ## Agent skill and Markdown practice
 
-The [portable Hivex skill](skills/hivex/SKILL.md) teaches consultation before implementation, support to
-the principal reviewer, documentation maintenance, uncertainty and budget handling. It uses the
-installed CLI's actual interface and does not require Compi's private tools or other skills.
+The [portable Hivex skill](skills/hivex/SKILL.md) teaches consultation before implementation, support to the principal reviewer, documentation maintenance, uncertainty and budget handling. It uses the installed CLI's actual interface and does not require private tools or other skills.
 
-The [optional Markdown convention](skills/hivex/references/markdown.md) describes authority maps,
-glossaries, ADRs, guidelines, process and procedures. Recommend it when useful; existing layouts,
-metadata conventions and writing styles remain valid. Create only the documents a project needs.
+The [optional Markdown convention](skills/hivex/references/markdown.md) describes authority maps, glossaries, ADRs, guidelines, process and procedures. Recommend it when useful; existing layouts, metadata conventions and writing styles remain valid. Create only the documents a project needs.
 
 ## Development
 
@@ -242,30 +147,17 @@ bun run format:check
 bun run test
 ```
 
-Tests use the public CLI and a simulated native transport. Real Luna evaluations are bounded and
-reported separately; simulated token usage is not a consumption measurement. Development is
-issue-first, with coherent PRs, independent Standards/Spec review and CI on the final commit.
-See the [engineering workflow](docs/engineering.md).
+Tests use the public CLI and a simulated native transport. Real Luna evaluations are bounded and reported separately; simulated token usage is not a consumption measurement. Development is issue-first, with coherent PRs, independent Standards/Spec review and CI on the final commit. See the [engineering workflow](docs/guidelines/engineering.md).
 
-Earlier candidate/fidelity/comparison/admission protocols and their tests are retired from the active
-CLI. Their code remains in Git history and historical evidence keeps its original results. They do
-not impose a requirement to reproduce an Opus graph or exhaustively replay an old gold suite.
+Earlier candidate/fidelity/comparison/admission protocols and their tests are retired from the active CLI. Their code remains in Git history and historical evidence keeps its original results. They do not impose a requirement to reproduce an Opus graph or exhaustively replay an old gold suite.
 
 ## Support an implementation review
 
-From the Git project root, supply the task and the base revision. Hivex captures the working change,
-including untracked files, and provides findings tied to code and Markdown versions:
+From the Git project root, supply the task and the base revision. Hivex captures the working change, including untracked files, and provides findings tied to code and Markdown versions:
 
 ```sh
 hivex review "Change cache behavior" --base main --max-calls 3 > /tmp/hivex-review.json
 hivex review --check /tmp/hivex-review.json
 ```
 
-Use the same task and base to resume or reuse retained work. Update, knowledge check and review share
-one budget, including expansion of a partial report. Context is bounded; large changes must be narrowed or split into coherent reviews. Larger existing
-text files contribute diff excerpts with original line numbers and explicit omissions; their full-file
-versions still detect later changes.
-The principal reviewer verifies conflicts and exceptions and resolves supported contradictions before
-closing the change. A `ready` result means assistance is available, never that the implementation is
-approved. A saved report can be checked without a model; changed code or documents make it stale.
-Keep reports outside the project or in an ignored path so they do not become part of the change.
+Use the same task and base to resume or reuse retained work. Update, knowledge check and review share one budget, including expansion of a partial report. Context is bounded; large changes must be narrowed or split into coherent reviews. Larger existing text files contribute diff excerpts with original line numbers and explicit omissions; their full-file versions still detect later changes. The principal reviewer verifies conflicts and exceptions and resolves supported contradictions before closing the change. A `ready` result means assistance is available, never that the implementation is approved. A saved report can be checked without a model; changed code or documents make it stale. Keep reports outside the project or in an ignored path so they do not become part of the change.

package/docs/CONTEXT.md

@@ -1,65 +1,49 @@
 # Hivex domain language
 
-Hivex supplies project knowledge to the agents responsible for implementation and review. Markdown
-records that knowledge; the graph helps locate and interpret it without becoming authority itself.
+Hivex supplies project knowledge to the agents responsible for implementation and review. Markdown records that knowledge; the graph helps locate and interpret it without becoming authority itself.
 
 ## Language
 
 **Document**: A selected Markdown file, wherever its project, package or module keeps it.
 
-**Archived document**: Historical Markdown preserved as evidence of replaced decisions and their
-reasons. It remains available for focused retrieval without being presumed current authority.
+**Archived document**: Historical Markdown preserved as evidence of replaced decisions and their reasons. It remains available for focused retrieval without being presumed current authority.
 
-**Ingestion unit**: A bounded fragment of a document with its original line range. It permits
-processing and resumption in rounds without becoming a separate documentary authority.
+**Ingestion unit**: A bounded fragment of a document with its original line range. It permits processing and resumption in rounds without becoming a separate documentary authority.
 
-**Document version**: The exact contents of a document at a point in the work. A working copy is a
-version even when it has not been committed; its existence does not establish approval.
+**Document version**: The exact contents of a document at a point in the work. A working copy is a version even when it has not been committed; its existence does not establish approval.
 
 **Snapshot**: The selected document versions considered together for a particular work item.
 
-**Decision**: A meaningful project choice or constraint together with its scope, conditions,
-exceptions and reasons. Proposals and historical decisions retain their declared state.
+**Decision**: A meaningful project choice or constraint together with its scope, conditions, exceptions and reasons. Proposals and historical decisions retain their declared state.
 
-**Relationship**: An evidenced connection between decisions, such as a dependency, exception or
-replacement. It may cross documents that have no authored link; its interpretation can be uncertain.
+**Relationship**: An evidenced connection between decisions, such as a dependency, exception or replacement. It may cross documents that have no authored link; its interpretation can be uncertain.
 
-**Evidence**: An identifiable passage of a particular document or implementation version that a
-reader can inspect. A model's paraphrase is not the passage itself.
+**Evidence**: An identifiable passage of a particular document or implementation version that a reader can inspect. A model's paraphrase is not the passage itself.
 
-**Knowledge graph**: Derived decisions and relationships, with supporting definitions and lessons, that help an agent recover project context.
-It may be incomplete or uncertain without making every usable part unavailable.
+**Knowledge graph**: Derived decisions and relationships, with supporting definitions and lessons, that help an agent recover project context. It may be incomplete or uncertain without making every usable part unavailable.
 
-**Knowledge snapshot**: A portable representation of reusable graph knowledge, its source versions,
-evidence, provenance and coverage. It is distinct from a document snapshot and from execution state.
+**Knowledge snapshot**: A portable representation of reusable graph knowledge, its source versions, evidence, provenance and coverage. It is distinct from a document snapshot and from execution state.
 
-**Applicability**: Whether a decision governs the case being considered after its conditions,
-exceptions and replacements have been taken into account.
+**Applicability**: Whether a decision governs the case being considered after its conditions, exceptions and replacements have been taken into account.
 
-**Freshness**: Whether derived knowledge still corresponds to the selected document versions.
-Freshness does not establish applicability or correctness by itself.
+**Freshness**: Whether derived knowledge still corresponds to the selected document versions. Freshness does not establish applicability or correctness by itself.
 
-**Knowledge update**: Processing a selected set of document versions into decisions and relationships,
-followed by one bounded check of that set and its affected relationships.
+**Knowledge update**: Processing a selected set of document versions into decisions and relationships, followed by one bounded check of that set and its affected relationships.
 
-**Knowledge check**: Examination of an update against its sources to identify omissions or incorrect
-interpretations. It reports issues and uncertainty, not a certificate of global completeness.
+**Knowledge check**: Examination of an update against its sources to identify omissions or incorrect interpretations. It reports issues and uncertainty, not a certificate of global completeness.
 
-**Interpretation repair**: Replacing a wrong derived interpretation by comparing it with unchanged
-Markdown. It preserves source authority and does not resolve a genuine policy conflict by itself.
+**Interpretation repair**: Replacing a wrong derived interpretation by comparing it with unchanged Markdown. It preserves source authority and does not resolve a genuine policy conflict by itself.
+
+**Source relocation**: Moving existing knowledge to a document's new location, retaining its decisions and relationships while distinguishing reusable evidence from content that needs a new check.
 
 **Context**: The decisions, related evidence and remaining uncertainties relevant to a particular task.
 
-**Implementation version**: The captured change against a particular base together with the exact
-contents of the affected files. Later code changes are outside that review.
+**Implementation version**: The captured change against a particular base together with the exact contents of the affected files. Later code changes are outside that review.
 
-**Finding**: A possible conflict between an implementation and project knowledge. The principal
-reviewer verifies it and retains responsibility for the implementation review.
+**Finding**: A possible conflict between an implementation and project knowledge. The principal reviewer verifies it and retains responsibility for the implementation review.
 
 **Work**: One requested update, consultation or review, including its phases and any resumed work.
 
-**Work budget**: The limits shared by every phase and attempt of one work item. Resuming does not
-reset its consumption, and unknown consumption remains visible.
+**Work budget**: The limits shared by every phase and attempt of one work item. Resuming does not reset its consumption, and unknown consumption remains visible.
 
-**Recovery**: Incorporating useful historical decisions, reasons and lessons into their appropriate
-Markdown authorities while identifying obsolete, duplicate or purely operational material.
+**Recovery**: Incorporating useful historical decisions, reasons and lessons into their appropriate Markdown authorities while identifying obsolete, duplicate or purely operational material.

package/docs/README.md

@@ -1,17 +1,11 @@
 # Documentation map
 
 - [Domain language](CONTEXT.md): documents, decisions, relationships, evidence and bounded work.
-- [Engineering workflow](engineering.md): development, verification and knowledge maintenance.
-- [Practical knowledge assistance](adr/0010-practical-knowledge-assistance.md): the current approved
-  contract, staged delivery, autonomy, semantic relationships, uncertainty and cost.
-- [Shared knowledge and selective history](adr/0011-shared-knowledge-and-selective-history.md): accepted
-  extension for compact ADRs, bounded historical retrieval and a Git-versioned knowledge snapshot;
-  implementation is pending.
-- [Recommended Markdown convention](../skills/hivex/references/markdown.md): optional organization
-  and writing practices for any adopting project.
+- [Engineering guidelines](guidelines/engineering.md): development, verification and knowledge maintenance.
+- [Runner procedure](procedures/self-hosted-runner.md): install and move the repository's CI runner.
+- [Practical knowledge assistance](adr/0010-practical-knowledge-assistance.md): the current approved contract, staged delivery, autonomy, semantic relationships, uncertainty and cost.
+- [Shared knowledge and selective history](adr/0011-shared-knowledge-and-selective-history.md): accepted extension for compact ADRs, bounded historical retrieval and a Git-versioned knowledge snapshot.
+- [Recommended Markdown convention](../skills/hivex/references/markdown.md): optional organization and writing practices for any adopting project.
 - [CLI guide](../README.md) and [agent skill](../skills/hivex/SKILL.md): the interface actually available.
 
-Earlier decisions remain in `adr/` as history. ADRs 0004–0009 describe the replaced experimental
-cohort/admission workflow; ADR 0010 supersedes its mandatory ceremony. Historical evidence is scoped
-to its original revision and is not a current acceptance result. An adopting project retains its own
-Markdown at monorepo, package or module level; Hivex does not own that source tree.
+Earlier decisions remain in `adr/` as history. ADRs 0004–0009 describe the replaced experimental cohort/admission workflow; ADR 0010 supersedes its mandatory ceremony. Historical evidence is scoped to its original revision and is not a current acceptance result. An adopting project retains its own Markdown at monorepo, package or module level; Hivex does not own that source tree.

package/docs/adr/0003-independent-bun-installation.md

@@ -8,30 +8,16 @@ date: 2026-09-07
 
 ## Context
 
-The owner selected Bun 1.4.2 as Hivex's runtime and package manager. The first independent version
-added a custom installer, registry verifier and generated bootstrap to reproduce Compi's dependency
-policy. The owner explicitly rejected that extra machinery: installation should work as in a project
-that started with Bun. This amendment replaces the initial decision; its original implementation and
-evidence remain in Git history and the bounded historical evidence directory.
+The owner selected Bun 1.4.2 as Hivex's runtime and package manager. The first independent version added a custom installer, registry verifier and generated bootstrap to reproduce a prior dependency policy. The owner explicitly rejected that extra machinery: installation should work as in a project that started with Bun. This amendment replaces the initial decision; its original implementation and evidence remain in Git history, while the current tree keeps only reusable decisions.
 
 ## Decision
 
-Use `bun install` for development and commit `bun.lock`. Use `bun ci` for frozen installation in CI
-and fresh checkouts. Pin Bun 1.4.2 in the package manifest and CI. Keep Bun's isolated dependency
-layout, seven-day minimum release age and explicit `trustedDependencies` allowlist, currently empty.
-Review required lifecycle-script additions with the dependency change.
+Use `bun install` for development and commit `bun.lock`. Use `bun ci` for frozen installation in CI and fresh checkouts. Pin Bun 1.4.2 in the package manifest and CI. Keep Bun's isolated dependency layout, seven-day minimum release age and explicit `trustedDependencies` allowlist, currently empty. Review required lifecycle-script additions with the dependency change.
 
-Do not maintain a parallel installer, publishing-trust verifier, registry metadata cache or generated
-bootstrap. Bun owns installation behavior; its native controls are not a claim of parity with every
-former pnpm policy. Remove code, dependencies and tests that served only the retired installer.
+Do not maintain a parallel installer, publishing-trust verifier, registry metadata cache or generated bootstrap. Bun owns installation behavior; its native controls are not a claim of parity with every former pnpm policy. Remove code, dependencies and tests that served only the retired installer.
 
 ## Consequences
 
-Hivex installs and runs independently of Compi and pnpm. It owns its compiler, formatter and lint
-configuration. The native TypeScript 7 compiler uses the unscoped `typescript-native` alias so Bun
-installs its native optional package. The separate TypeScript 6 package provides the compatibility
-API needed by typed ESLint.
+Hivex installs and runs independently of caller package managers. It owns its compiler, formatter and lint configuration. The native TypeScript 7 compiler uses the unscoped `typescript-native` alias so Bun installs its native optional package. The separate TypeScript 6 package provides the compatibility API needed by typed ESLint.
 
-Typechecking, lint, formatting and relevant product tests validate dependency changes. They do not
-require a second installation framework. Compi's Bun conversion and Expo/native compatibility remain
-separate work under [#1162](https://github.com/H1V35/compi/issues/1162).
+Typechecking, lint, formatting and relevant product tests validate dependency changes. They do not require a second installation framework.

package/docs/adr/0010-practical-knowledge-assistance.md

@@ -6,87 +6,34 @@ date: 2026-09-09
 
 # Practical knowledge assistance with bounded work
 
-The owner approved a new contract after a grill in [Hivex #17](https://github.com/H1V35/hivex/issues/17).
-The previous implementation spent disproportionate effort certifying intermediate model output.
-Hivex must provide a portable second brain that helps agents act autonomously, reduce hallucinations
-and contradictions, and recover settled decisions before asking the owner again.
-
-Markdown remains documentary authority. Documents can live at monorepo, package or module level and
-use the adopting project's own organization and format. Recommend clear domain language, decisions
-with their reasons, explicit conditions and replacements, and one authoritative home per fact.
-Compi's documentation convention is useful guidance, not an admission requirement.
-
-Keep a semantic graph of meaningful decisions and relationships, including implicit cross-document
-connections. A document-summary index alone does not satisfy the contract. Recover the relevant
-transitive dependencies within an explicit context budget. Explain applicability when the sources
-support it; otherwise identify uncertainty and the remaining evidence needed.
-
-The implementing agent consults Hivex before a coherent feature or behavior change. The principal
-reviewer consults it with the task and diff during review, checks its findings and keeps responsibility
-for accepting the implementation. A demonstrated contradiction must be corrected or resolved by an
-approved decision change. Hivex neither conducts every aspect of code review nor rewrites Markdown
-on its own. Genuine unanswered decisions go to the owner with sources, impact and a recommendation.
-
-An update splits oversized Markdown into source-bound units with original line provenance, processes
-bounded rounds, and checkpoints progress so resumption never discards completed ingestion. Reuse
-retained extraction results when their source and processing context still match; do not require the
-whole corpus or a large document to fit in one invocation. Caches optimize work and carry no authority.
-
-An update processes a bounded batch and makes one additional knowledge check against its documents
-and affected relationships. Do not review every node separately or every possible source pair.
-Do not automatically revise and retry until the model produces green output. Usable knowledge remains
-available when another part is pending or uncertain, with those limits visible to the caller.
-A wrong derived interpretation can be corrected against its source without changing doctrine.
-
-Consultations and reviews detect added, changed and removed Markdown and update affected knowledge
-within their work budget. Reuse unchanged knowledge. Working documents need no commit to be readable,
-but their working state and exact contents must be identifiable. Results refer to the document and
-implementation versions actually considered; subsequent changes are not silently covered.
-
-A work budget spans the entire requested operation, its phases and any resumption or attempts.
-Expose actual consumption and unknown usage, preserve progress at a limit and distinguish initial
-indexing, maintenance, consultation and review. Small empirical checks establish useful defaults;
-a cheap model does not justify unnecessary invocations or context.
-
-Luna/max is the owner's selected knowledge model and the profile validated for this release, without
-silent fallback. Keep model selection and invocation localized so another user can configure a
-supported model later. Do not build a provider framework speculatively. The principal agent may use
-a different model without moving project knowledge into its vendor's private memory.
-
-Use TypeScript/Bun and practical domain-driven modules with small interfaces. There is no obligation
-to retain the old code, Opus graph, gold suite or machinery as the architecture or acceptance target.
-Historical evidence keeps its actual result and limits. This decision supersedes the mandatory
-candidate/fidelity/pair-comparison/admission ceremony in ADRs 0004–0009 for the replacement workflow;
-those ADRs describe the earlier implementation and remain historical records.
-
-The portable skill is part of each functional delivery. It teaches the actual CLI, the agreed
-workflow, good documentation practice and cost/uncertainty handling without requiring Compi's
-private tools or skills. The first slice in #47 supplies explicit initial updates and task context;
-#48 adds automatic incremental maintenance and interpretation repair; #19 supplies diff-review assistance. These are
-implementation stages, not claims that the entire new contract is already shipped.
-
-Validate with bounded real Compi cases covering a conflict, a valid exception, indirect dependency,
-insufficient evidence and a document change, with explicit expected outcomes and measured cost.
-Also use a differently organized Markdown project and an agent exercising the skill. Tests exercise
-the public CLI and native protocol seam, not incidental representations.
-
-Early use in Compi is desirable. Complete closure additionally requires recovering useful historical
-knowledge and retiring the old active machinery and consumers after replacement is verified.
-Keep Git history and necessary external evidence; a legacy evidence document can suffice. Do not
-rebuild another fleet inside that archive or treat a successful package build as completed adoption.
+The owner approved a new contract after a grill in [Hivex #17](https://github.com/H1V35/hivex/issues/17). The previous implementation spent disproportionate effort certifying intermediate model output. Hivex must provide a portable second brain that helps agents act autonomously, reduce hallucinations and contradictions, and recover settled decisions before asking the owner again.
+
+Markdown remains documentary authority. Documents can live at monorepo, package or module level and use the project's own organization and format. Recommend clear domain language, decisions with their reasons, explicit conditions and replacements, and one authoritative home per fact. The [recommended Markdown convention](../../skills/hivex/references/markdown.md) is guidance, not an admission requirement.
+
+Keep a semantic graph of meaningful decisions and relationships, including implicit cross-document connections. A document-summary index alone does not satisfy the contract. Recover the relevant transitive dependencies within an explicit context budget. Explain applicability when the sources support it; otherwise identify uncertainty and the remaining evidence needed.
+
+The implementing agent consults Hivex before a coherent feature or behavior change. The principal reviewer consults it with the task and diff during review, checks its findings and keeps responsibility for accepting the implementation. A demonstrated contradiction must be corrected or resolved by an approved decision change. Hivex neither conducts every aspect of code review nor rewrites Markdown on its own. Genuine unanswered decisions go to the owner with sources, impact and a recommendation.
+
+An update splits oversized Markdown into source-bound units with original line provenance, processes bounded rounds, and checkpoints progress so resumption never discards completed ingestion. Reuse retained extraction results when their source and processing context still match; do not require the whole corpus or a large document to fit in one invocation. Caches optimize work and carry no authority.
+
+An update processes a bounded batch and makes one additional knowledge check against its documents and affected relationships. Do not review every node separately or every possible source pair. Do not automatically revise and retry until the model produces green output. Usable knowledge remains available when another part is pending or uncertain, with those limits visible to the caller. A wrong derived interpretation can be corrected against its source without changing doctrine.
+
+Consultations and reviews detect added, changed and removed Markdown and update affected knowledge within their work budget. Reuse unchanged knowledge. Working documents need no commit to be readable, but their working state and exact contents must be identifiable. Results refer to the document and implementation versions actually considered; subsequent changes are not silently covered.
+
+A work budget spans the entire requested operation, its phases and any resumption or attempts. Expose actual consumption and unknown usage, preserve progress at a limit and distinguish initial indexing, maintenance, consultation and review. Small empirical checks establish useful defaults; a cheap model does not justify unnecessary invocations or context.
+
+Luna/max is the owner's selected knowledge model and the profile validated for this release, without silent fallback. Keep model selection and invocation localized so another user can configure a supported model later. Do not build a provider framework speculatively. The principal agent may use a different model without moving project knowledge into its vendor's private memory.
+
+Use TypeScript/Bun and practical domain-driven modules with small interfaces. There is no obligation to retain the old code, Opus graph, gold suite or machinery as the architecture or acceptance target. Historical evidence keeps its actual result and limits. This decision supersedes the mandatory candidate/fidelity/pair-comparison/admission ceremony in ADRs 0004–0009 for the replacement workflow; those ADRs describe the earlier implementation and remain historical records.
+
+The portable skill is part of each functional delivery. It teaches the actual CLI, the agreed workflow, good documentation practice and cost/uncertainty handling without requiring private tools or unrelated skills. The first slice in #47 supplies explicit initial updates and task context; #48 adds automatic incremental maintenance and interpretation repair; #19 supplies diff-review assistance. These are implementation stages, not claims that the entire new contract is already shipped.
+
+Validate with bounded real cases covering a conflict, a valid exception, indirect dependency, insufficient evidence and a document change, with explicit expected outcomes and measured cost. Also use a differently organized Markdown project and an agent exercising the skill. Tests exercise the public CLI and native protocol seam, not incidental representations.
+
+Early use can precede complete legacy recovery. Complete closure additionally requires recovering useful historical knowledge and retiring old active machinery after replacement is verified. Keep Git history and necessary external evidence; a legacy evidence document can suffice. Do not rebuild another fleet inside that archive or treat a successful package build as proof that the workflow is fully validated.
 
 ## Incremental consultation delivery (#48)
 
-A consultation maintains at most one bounded pending batch before answering, prioritizing matching
-fragments and known affected neighbors. Update, check and answer share one work budget; context-limit
-increases do not reset an unfinished work item. Remaining corpus coverage is reported, and explicit
-updates can advance further rounds. Repeating a completed consultation reuses its result while its
-supplied context remains unchanged.
-
-Repair revisits selected source units with an explicit correction reason, without editing Markdown.
-It replaces their derived decisions and relationships and preserves prior attempts. Check findings
-carry source/version/range scope so an unrelated consultation does not inherit a local uncertainty.
-Removed sources remain identifiable when a dependency can no longer be verified. A changed known
-supporting source takes priority over unrelated pending documents. Endpoint updates include the
-source passages supporting their previous relationships; if that evidence is missing or cannot fit
-the context limit, retain pending work and report the limitation before spending a model call.
+A consultation maintains at most one bounded pending batch before answering, prioritizing matching fragments and known affected neighbors. Update, check and answer share one work budget; context-limit increases do not reset an unfinished work item. Remaining corpus coverage is reported, and explicit updates can advance further rounds. Repeating a completed consultation reuses its result while its supplied context remains unchanged.
+
+Repair revisits selected source units with an explicit correction reason, without editing Markdown. It replaces their derived decisions and relationships and preserves prior attempts. Check findings carry source/version/range scope so an unrelated consultation does not inherit a local uncertainty. Removed sources remain identifiable when a dependency can no longer be verified. A changed known supporting source takes priority over unrelated pending documents. Endpoint updates include the source passages supporting their previous relationships; if that evidence is missing or cannot fit the context limit, retain pending work and report the limitation before spending a model call.