@h1v35/hivex 0.2.0 → 0.2.2

package/docs/adr/0011-shared-knowledge-and-selective-history.md

@@ -6,53 +6,26 @@ date: 2026-09-11
 
 # Shared knowledge snapshots and selective documentary history
 
-The owner accepted two changes while reviewing Compi's adoption under Hivex #17. Long ADRs mix
-current rules with replaced text, increasing ingestion cost and ambiguity. Keeping the derived graph
-only in a local store also makes each clone pay to rebuild knowledge and leaves no shared history of
-the interpretations used. Markdown remains authoritative; versioning a graph does not make its
-interpretations correct or its sources current.
+The owner accepted two changes while reviewing the project under [Hivex #17](https://github.com/H1V35/hivex/issues/17). Long ADRs mix current rules with replaced text, increasing ingestion cost and ambiguity. Keeping the derived graph only in a local store also makes each clone pay to rebuild knowledge and leaves no shared history of the interpretations used. Markdown remains authoritative; versioning a graph does not make its interpretations correct or its sources current.
 
 ## Compact current decisions, preserve accessible history
 
-An author may move replaced decision text into a clearly historical Markdown archive, preserving the
-original text, dates and provenance. The current ADR retains the applicable decision, reasons,
-dependencies and exceptions, with links to its history and replacements. A completely superseded ADR
-may become a short pointer at its original path. Preserve referenced anchors or update their callers;
-age alone never makes a still-applicable condition obsolete.
+An author may move replaced decision text into a clearly historical Markdown archive, preserving the original text, dates and provenance. The current ADR retains the applicable decision, reasons, dependencies and exceptions, with links to its history and replacements. A completely superseded ADR may become a short pointer at its original path. Preserve referenced anchors or update their callers; age alone never makes a still-applicable condition obsolete.
 
-`docs/archive/adr/` is Compi's chosen convention, not a required layout for every adopter. Historical
-sources remain explicitly available for bounded retrieval when needed. They do not become the normal
-ingestion backlog or enter every consultation simply because they are accessible. Hivex must respect
-the project's declared source scope and report unavailable necessary evidence rather than silently
-omitting a dependency or treating an old rule as current. The author performs documentary compaction;
-Hivex does not rewrite project decisions automatically.
+`docs/archive/adr/` is one valid convention, not a required layout for every project. Historical sources remain explicitly available for bounded retrieval when needed. They do not become the normal ingestion backlog or enter every consultation simply because they are accessible. Hivex must respect the project's declared source scope and report unavailable necessary evidence rather than silently omitting a dependency or treating an old rule as current. The author performs documentary compaction; Hivex does not rewrite project decisions automatically.
 
 ## Share derived knowledge, keep execution state local
 
-The shared artifact is `.hivex/graph.json`: a portable knowledge snapshot suitable for Git, containing
-the reusable graph, source versions, evidence, provenance and coverage/uncertainty information. It
-allows inspection of what changed and reuse in another clone without regenerating an identical
-model output. Preserve known provenance and identify unavailable legacy metadata; do not invent it.
-
-`.hivex/knowledge.sqlite` remains the local working store for queries, incremental work, attempts,
-budgets and caches. `.hivex/knowledge.lock` remains local. The shared artifact does not carry process
-identities, locks, pending invocations or the model-response cache. Loading it must not overwrite
-unfinished work, erase failed attempts or reset an existing work budget.
-
-Use deterministic structural and source-version checks to distinguish reusable knowledge from stale
-or unavailable parts. A fresh clone should reuse matching knowledge; changed sources require only
-the necessary update. A snapshot may retain explicit partial or uncertain coverage. Serializing the
-same graph should produce a stable diff; normal read-only queries should not dirty the shared file.
-Snapshot operations must not trigger hidden model calls or source edits.
-
-This extends ADR 0010's portable second-brain contract and supersedes a blanket recommendation to
-ignore every artifact under `.hivex/`. The CLI supports explicit snapshot export/import and reuses
-the snapshot in a fresh clone. Configurable `history` globs keep historical sources available for
-focused retrieval while excluding them from ordinary ingestion.
-A saved snapshot alone does not complete Compi adoption; publication and process retirement follow
-the project's normal workflow.
-
-Delivery is tracked by [#53](https://github.com/H1V35/hivex/issues/53) (shared graph snapshot) and
-[#54](https://github.com/H1V35/hivex/issues/54) (selective historical sources), under
-[the approved extension to #17](https://github.com/H1V35/hivex/issues/17#issuecomment-5631587186).
-The CLI remains the existing behavioral test boundary for both independent deliveries.
+The shared artifact is `.hivex/graph.json`: a portable knowledge snapshot suitable for Git, containing the reusable graph, source versions, evidence, provenance and coverage/uncertainty information. It allows inspection of what changed and reuse in another clone without regenerating an identical model output. Preserve known provenance and identify unavailable legacy metadata; do not invent it.
+
+`.hivex/knowledge.sqlite` remains the local working store for queries, incremental work, attempts, budgets and caches. `.hivex/knowledge.lock` remains local. The shared artifact does not carry process identities, locks, pending invocations or the model-response cache. Loading it must not overwrite unfinished work, erase failed attempts or reset an existing work budget.
+
+Use deterministic structural and source-version checks to distinguish reusable knowledge from stale or unavailable parts. A fresh clone should reuse matching knowledge; changed sources require only the necessary update. A snapshot may retain explicit partial or uncertain coverage. Serializing the same graph should produce a stable diff; normal read-only queries should not dirty the shared file. Snapshot operations must not trigger hidden model calls or source edits.
+
+This extends ADR 0010's portable second-brain contract and supersedes a blanket recommendation to ignore every artifact under `.hivex/`. The CLI supports explicit snapshot export/import and reuses the snapshot in a fresh clone. Configurable `history` globs keep historical sources available for focused retrieval while excluding them from ordinary ingestion. A saved snapshot alone does not complete a project's rollout; publication and process retirement follow the project's normal workflow.
+
+Delivery is tracked by [#53](https://github.com/H1V35/hivex/issues/53) (shared graph snapshot) and [#54](https://github.com/H1V35/hivex/issues/54) (selective historical sources), under [the approved extension to #17](https://github.com/H1V35/hivex/issues/17#issuecomment-5631587186). The CLI remains the existing behavioral test boundary for both independent deliveries.
+
+## Source relocation — 2026-09-13 (#64)
+
+An explicit source relocation keeps knowledge usable when documentation changes location. It preserves decision and relationship identities, source versions, uncertainty and existing work history. An identical move can reuse ingestion coverage without a model call. Changed content or consolidation requires the normal update/check at the destination; relocation does not approve that interpretation or make mismatched evidence current. Refuse relocation while local work is unfinished, preserve original work and model answers, and record the source/destination and versions in the operation report. Commit the exported graph with the corresponding source changes so their history remains auditable.

package/docs/guidelines/engineering.md

@@ -0,0 +1,74 @@
+---
+title: Engineering workflow
+status: accepted
+---
+
+# Engineering workflow
+
+Hivex is a TypeScript/Bun product. Modules group behavior by domain responsibility and hide internal details behind small interfaces. Do not add a second development-session orchestrator or require an adopting project's layout, tracker or product packages. Codex, Git/GitHub and CI coordinate work.
+
+## Development and verification
+
+Work is issue-first in `H1V35/hivex`. New vertical work follows discovery where decisions remain open, then an agreed spec, verifiable execution tickets, implementation and code review. Reuse settled scope instead of reopening an interview. The owning repository carries the execution ticket; a cross-repository parent supplies context and coordination, not a substitute for native tracking.
+
+Resolve the existing spec/ticket before changing code and link the PR and verification to it. Absorb review findings into the appropriate existing ticket whenever its scope permits. Open a separate issue only when strictly necessary to preserve independently actionable work, and record why it cannot be absorbed. Read-only retrieval does not need a new ticket. Specs and tickets track work and acceptance; resulting durable decisions also enter their repository authority.
+
+Use an existing issue for an already tracked requirement. Create a branch from the current remote main, keep each PR to one coherent change and preserve commit history when merging. Never push directly to main or force-push a shared branch. Apply review findings before acceptance; an invalid review can be rerun, while an adverse finding must be resolved on its merits. Current explicit owner authorization governs whether the agent may merge.
+
+Independent code reviewers use the coordinating agent's current model and reasoning effort. Pass that profile explicitly when the subagent default differs, and verify the effective configuration after dispatch. Do not substitute the cheaper knowledge model for code review. Routine implementation subtasks may use an explicitly authorized cheaper model; Hivex's internal knowledge extraction/checking uses the user's knowledge-model configuration independently of the development and code-review model.
+
+Choose verification for the affected surfaces. Code changes require typechecking, lint, formatting and relevant behavior tests; documentation-only changes need formatting and checks of affected references or declared sources. Record the exact revision and the checks actually completed. A later change invalidates the affected results. Do not claim an omitted, interrupted or truncated check passed.
+
+GitHub Actions runs the quality workflow on the owner's Mac through an official self-hosted runner, using `[self-hosted, macOS, ARM64, hivex]`. GitHub retains secrets, logs and PR checks; no hosted runner fallback is configured. No speed benchmark is required. A queued, skipped or interrupted run is not a pass. Local verification remains required when the runner is unavailable. Installation and host migration follow the [runner procedure](../procedures/self-hosted-runner.md).
+
+Use `bun install` for development and `bun ci` for frozen installation. Bun owns dependency installation through its native configuration and lockfile; Hivex has no custom installer or registry verifier. See the [installation decision](../adr/0003-independent-bun-installation.md).
+
+Lint uses the published Ultracite ESLint/Prettier core presets with the owner's selected preferences: maximum cyclomatic complexity 20, cognitive complexity 15, nesting depth 3 and four parameters per function; print width 100 and single quotes; unused variables, arguments and caught errors may have a leading `_`, and loose equality is allowed when comparing with `null`. Keep the rest of the presets unchanged. Naming and unused-variable checks allow the leading `_` for unused bindings. The overlapping SonarJS unused-variable rule, `no-eq-null` and optional-catch-binding preference are disabled because they cannot express those exceptions; the configured unused-variable and equality rules still check ordinary names and comparisons. Use `eslint-plugin-boundaries` to enforce actual module responsibilities and keep additional policy minimal and tied to domain behavior. Configuration and dependency versions belong in the executable project configuration. Refactor around meaningful responsibilities instead of adding wrappers to satisfy arbitrary thresholds.
+
+The dependency policy follows the current modules: document discovery and Markdown parsing do not import knowledge, review or model execution; knowledge storage and ingestion may use documents; review may use documents and knowledge. Model execution is self-contained, retrieval may use shared errors, and CLI commands compose these responsibilities. Tests may use production modules; production cannot import tests. New source files must be classified before they can participate in these dependencies.
+
+Runtime settings identify Bun globals and Bun executables while keeping the preset rules enabled. The browser compatibility target is the server-side JavaScript environment, not a browser application. Runtime APIs used by the code must also be verified on the supported Bun version.
+
+## Tests protect behavior
+
+TDD guides development through meaningful failing examples; it does not require a test for every function, component, wrapper or line. A test must identify a supported behavior, meaningful invariant or regression it protects. Prefer the caller's observable interface and results that survive an internal refactor.
+
+For UI, test visible content, accessibility, interactions and loading/error/empty-state behavior. Do not freeze arbitrary child arrays, wrapper counts or class/style arrangements. A visual dimension needs a test only when it is an intentional requirement worth maintaining. For example, displaying "2 of 4" is a behavior; representing it as exactly three React children is not.
+
+Mocks, call counts, ordering and exact bytes are not automatically wrong. They can protect an external protocol, idempotency, a query budget or faithful source reproduction. Their justification must be the contract, not the current arrangement of internal helpers. Expected results must be independent examples, not the implementation's own calculation repeated in the test.
+
+Review existing tests as retain, rewrite, consolidate or remove. Remove tests for retired behavior with that behavior; preserve still-needed guarantees at the replacement's actual interface. Do not port a legacy battery mechanically, chase a test-count target or retain duplicate suites indefinitely.
+
+## Files and runtime data have a lifecycle
+
+Create a source file for a meaningful responsibility and a document for a distinct authoritative purpose. Do not create files for every helper, task, turn, attempt or handoff merely to satisfy a layout convention or a lint threshold.
+
+Before introducing persistent state, define its purpose, location, owner and retention. Prefer a small project-local data store to an unbounded tree of per-event files. A per-unit atomic checkpoint can be a database transaction; it does not require a separate file. Fewer filenames alone do not bound data growth: cached data, run history and diagnostics also need size/count/age limits and cleanup behavior.
+
+Normal read-only queries should leave no per-query artifacts. Clean up owned temporary resources on ordinary completion and handled failures. Interrupted work must remain recoverable without being silently retried or discarded. Export diagnostic bundles when needed rather than automatically writing a new report for every successful step. Retention must preserve the accepted state and the evidence needed by supported historical/recovery operations; it must not invent a successful cleanup.
+
+## Documentation is maintained authority
+
+Code must be self-explanatory through clear names, structure and behavior. Repository Markdown is the source of truth for intent, constraints, decisions and reasons that code cannot explain. Do not write a parallel implementation manual or use documentation to compensate for unclear code. Accepted source history and Markdown retain authority; caches, model output and search hits do not. An accepted status alone does not settle amendments, exceptions or contradictions. Keep unresolved evidence explicit. Never promote a historical agent's description of an owner ruling without checking its provenance and applicability.
+
+Capture every decision worth preserving in its appropriate repository document as part of the work. Do not leave accepted knowledge only in a conversation, issue comment or runtime log. Update the existing canonical document when it already owns the topic and scope; create a new one only when it has a distinct purpose. An issue can track the work and preserve discussion, but it is not a substitute for incorporating the resulting doctrine into the documentation.
+
+Keep docs with the monorepo, workspace or module they describe. Link to common rules instead of copying them. Recommended new Markdown should state purpose/scope, use stable headings and suitable metadata, keep a rule with its conditions/exceptions, and link its sources and replacements. Accept compatible existing Markdown without forcing those authors to adopt our template. Do not generate empty documentation for every module or add non-Markdown readers to the current scope.
+
+Use repository decisions and review evidence for durable knowledge, not private agent memory. Checkpoints identify the exact commit, verified work and remaining work. Choose a context handoff when the task needs it; Hivex does not impose the retired machinery's fixed token thresholds. Knowledge-model operations use the admitted Luna/max profile and record actual usage, including failed or interrupted attempts. Deterministic retrieval and maintenance do not require a model.
+
+The replacement workflow follows [ADR 0010](../adr/0010-practical-knowledge-assistance.md). It processes bounded document batches with one additional knowledge check, keeps partial knowledge usable and preserves a work budget across phases and resumption. A consultation maintains one pending batch before answering, and a source-based repair replaces interpretations without changing doctrine. Keep check warnings scoped and public evidence limited to source coordinates, version and text. Avoid a new abstraction or protocol unless it protects a concrete requirement. The owner-authorized implementation can replace the earlier cohort/admission pipeline; its historical evidence remains unchanged.
+
+Hivex assists the principal reviewer with decisions, dependencies, exceptions and possible conflicts. The reviewer verifies its findings. Missing context or uncertainty limits the conclusions it affects; a definitive finding must refer to the actual document and implementation versions reviewed.
+
+## Retire mechanisms without losing knowledge
+
+After knowledge recovery and replacement validation, remove obsolete orchestration code, scripts, hooks, configuration, tests, dependencies and active instructions. Do not carry an unused legacy framework into Hivex under another name. Preserve useful decisions in their canonical docs and retain necessary historical evidence in Git or a bounded private archive outside the active worktree. Do not rewrite Git history or destroy the accepted Opus graph before its replacement is admitted.
+
+A replacement workflow can be used before every historical artifact is retired when the remaining work is explicit. Complete closure requires useful historical knowledge in Markdown and obsolete active machinery retired wherever it is no longer needed. Validate the workflow against bounded real cases, not identity with an old model's graph or an exhaustive replay prerequisite. Release packages exclude private project evidence and retired runtime.
+
+## Distribution
+
+The owner selected `@h1v35/hivex` for the npm package on 2026-09-08, retaining `hivex` as the installed command, and approved the MIT license. The scoped name avoids the unrelated existing unscoped npm package. Use an authenticated account authorized for that scope; do not infer npm ownership from a matching GitHub name. Release preparation must verify the packed contents and exclude private project evidence and runtime stores. Project integration follows the normal release process after the complete cycle is validated; this decision alone does not mean a package has been published.
+
+Before publication, inspect and scan the exact package archive for secrets and unintended private content. Record its hash and the completed scan result; a repack requires a fresh check. Publish the same verified artifact, not an unchecked reconstruction from a changed working tree.

package/docs/procedures/self-hosted-runner.md

@@ -0,0 +1,7 @@
+# Self-hosted GitHub Actions runner
+
+Follow the [engineering guidelines](../guidelines/engineering.md#development-and-verification) for runner labels, execution boundaries and verification requirements.
+
+Runner installation is repository administration, outside Hivex's product. Register the admitted macOS ARM64 release from GitHub's runner settings in its own directory, verify the official checksum, and use the generated `svc.sh install/start/status/stop` commands. Keep automatic updates enabled, a stable Homebrew/system PATH and the Mac awake and connected under the logged-in user. The runner work directory must be separate from the developer checkout and other repository runners. Only trusted code may run on this persistent host; review that boundary before public contributions. See [GitHub's runner reference](https://docs.github.com/en/actions/reference/runners/self-hosted-runners).
+
+During a host migration, disable Actions, register and confirm the runner is online, and merge all workflow routes before re-enabling Actions. Then dispatch Quality on that exact revision and check the assigned runner and completed result. The route change alone is not functional verification.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@h1v35/hivex",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "Versioned project knowledge for people and agents.",
   "scripts": {
     "hivex": "bun src/cli.ts",
     "test": "bun test --timeout 15000 ./src",
     "typecheck": "node_modules/typescript-native/bin/tsc --noEmit",
-    "lint": "eslint src test tooling eslint.config.js eslint.base.config.js",
+    "lint": "eslint src test eslint.config.js prettier.config.js",
     "format:check": "prettier --check ."
   },
   "dependencies": {
@@ -23,14 +23,31 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "typescript-native": "npm:typescript@7.0.2",
-    "@types/bun": "1.3.14",
-    "eslint": "10.7.0",
-    "eslint-plugin-sonarjs": "1.0.4",
-    "globals": "16.5.0",
+    "@types/bun": "1.4.0",
+    "@typescript-eslint/eslint-plugin": "8.69.0",
+    "@typescript-eslint/parser": "8.69.0",
+    "eslint": "10.9.1",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-boundaries": "7.2.0",
+    "eslint-plugin-compat": "7.0.2",
+    "eslint-plugin-cypress": "7.0.1",
+    "eslint-plugin-github": "6.1.2",
+    "eslint-plugin-html": "8.2.0",
+    "eslint-plugin-import-x": "4.17.1",
+    "eslint-plugin-jsdoc": "64.3.5",
+    "eslint-plugin-n": "18.3.0",
+    "eslint-plugin-prettier": "5.5.6",
+    "eslint-plugin-promise": "7.3.0",
+    "eslint-plugin-sonarjs": "4.2.0",
+    "eslint-plugin-storybook": "10.6.0",
+    "eslint-plugin-unicorn": "74.0.0",
+    "eslint-plugin-unused-imports": "4.4.1",
+    "globals": "17.12.0",
+    "prettier": "3.8.4",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.64.0",
-    "prettier": "3.8.4"
+    "typescript-native": "npm:typescript@7.0.2",
+    "ultracite": "7.10.8"
   },
   "trustedDependencies": [],
   "packageManager": "bun@1.4.2",
@@ -46,7 +63,8 @@
     "!src/**/*.test.ts",
     "docs/README.md",
     "docs/CONTEXT.md",
-    "docs/engineering.md",
+    "docs/guidelines/engineering.md",
+    "docs/procedures/self-hosted-runner.md",
     "docs/adr/0003-independent-bun-installation.md",
     "docs/adr/0010-practical-knowledge-assistance.md",
     "docs/adr/0011-shared-knowledge-and-selective-history.md",
@@ -61,5 +79,8 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
-  }
+  },
+  "browserslist": [
+    "node 25"
+  ]
 }

package/skills/hivex/SKILL.md

@@ -5,130 +5,66 @@ description: Retrieve project decisions and their dependencies and exceptions wi
 
 # Hivex
 
-Hivex gives the implementing and reviewing agents project context. Markdown is documentary
-authority; the graph is derived assistance. The principal agent remains responsible for the work.
-Recover settled decisions before asking the owner to decide them again.
+Hivex gives the implementing and reviewing agents project context. Markdown is documentary authority; the graph is derived assistance. The principal agent remains responsible for the work. Recover settled decisions before asking the owner to decide them again.
 
 ## Start with the installed interface
 
-Read the project's agent instructions and source configuration. Run `hivex --help` when the installed
-interface is unfamiliar. In a Bun project, `bun hivex` resolves the installed CLI. The package is
-`@h1v35/hivex`; do not fetch the unrelated unscoped package.
+Read the project's agent instructions and source configuration. Run `hivex --help` when the installed interface is unfamiliar. In a Bun project, `bun hivex` resolves the installed CLI. The package is `@h1v35/hivex`; do not fetch the unrelated unscoped package.
 
-Use the capabilities advertised by that version. Do not invent commands, silently switch models or
-pretend a planned capability exists. Hivex's current validated knowledge profile is Luna/max through
-native Codex; the principal agent's model is independent of that choice.
+Use the capabilities advertised by that version. Do not invent commands, silently switch models or pretend a planned capability exists. Hivex's current validated knowledge profile is Luna/max through native Codex; the principal agent's model is independent of that choice.
 
-Projects may declare additional historical Markdown with `history` globs in `hivex.json`. Those
-sources are available to `sources` and `read`, but remain outside ordinary update and consultation
-selection. Use `--source <document>` with `ask` or `review` for a focused retrieval; a known graph
-relationship may bring back only the bounded evidence it needs. Explicit `exclude` globs still win,
-and the CLI continues to reject symlinks, protected directories and paths outside the project.
+Projects may declare additional historical Markdown with `history` globs in `hivex.json`. Those sources are available to `sources` and `read`, but remain outside ordinary update and consultation selection. Use `--source <document>` with `ask` or `review` for a focused retrieval; a known graph relationship may bring back only the bounded evidence it needs. Explicit `exclude` globs still win, and the CLI continues to reject symlinks, protected directories and paths outside the project.
 
-Native Codex must be able to write its own local state. When the host sandbox prevents that,
-use its normal execution-approval mechanism within the existing authorized scope. Keep a failed
-launch in the same work history when resuming; an initialization failure is not a model verdict.
+Native Codex must be able to write its own local state. When the host sandbox prevents that, use its normal execution-approval mechanism within the existing authorized scope. Keep a failed launch in the same work history when resuming; an initialization failure is not a model verdict.
 
 ## Before implementation
 
-For a coherent feature or behavior change, ask about the intended task and recover the relevant
-decisions. Read their evidence and follow relevant dependencies, exceptions and replacements,
-including indirect relationships. A search preview or accepted label alone does not settle scope.
+For a coherent feature or behavior change, ask about the intended task and recover the relevant decisions. Read their evidence and follow relevant dependencies, exceptions and replacements, including indirect relationships. A search preview or accepted label alone does not settle scope.
 
-Use Hivex's source/version references. Keep conditions with their rules; a partial exception does
-not revoke an entire document. If the evidence answers the question, apply it without asking the
-owner again. Ask only when information is missing, sources cannot resolve a real ambiguity or a
-new decision requires the owner's involvement. Present the sources, impact and your recommendation.
+Use Hivex's source/version references. Keep conditions with their rules; a partial exception does not revoke an entire document. If the evidence answers the question, apply it without asking the owner again. Ask only when information is missing, sources cannot resolve a real ambiguity or a new decision requires the owner's involvement. Present the sources, impact and your recommendation.
 
-Queries should be focused. Reuse context that remains current rather than asking again per file or
-implementation step. Respect declared incomplete exploration and unavailable evidence.
+Queries should be focused. Reuse context that remains current rather than asking again per file or implementation step. Respect declared incomplete exploration and unavailable evidence.
 
 ## During review
 
-The principal reviewer directs the review. Run `hivex review "<task>" --base <git-ref>` from the
-Git project root. It examines tracked and untracked working changes, recovers relevant documentary
-context and makes one review call after at most one update/check batch. The default total budget is
-three calls; resume the same task/base with the intended total limit to continue retained work.
-Expanding a partial report keeps its work identity and consumed budget; a larger context does not
-create another allowance.
+The principal reviewer directs the review. Run `hivex review "<task>" --base <git-ref>` from the Git project root. It examines tracked and untracked working changes, recovers relevant documentary context and makes one review call after at most one update/check batch. The default total budget is three calls; resume the same task/base with the intended total limit to continue retained work. Expanding a partial report keeps its work identity and consumed budget; a larger context does not create another allowance.
 
-Check each finding against its cited before/after code and Markdown versions, including dependencies,
-conditions and exceptions. Resolve a demonstrated contradiction before closing the change, by
-correcting the implementation or recording an approved decision change. Uncertainty calls for focused
-investigation; absence of a finding is not implementation approval. Missing context may be addressed
-with a focused task, explicit `--source` or an appropriate context limit, not automatic semantic retries.
+Check each finding against its cited before/after code and Markdown versions, including dependencies, conditions and exceptions. Resolve a demonstrated contradiction before closing the change, by correcting the implementation or recording an approved decision change. Uncertainty calls for focused investigation; absence of a finding is not implementation approval. Missing context may be addressed with a focused task, explicit `--source` or an appropriate context limit, not automatic semantic retries.
 
-Save a report outside the reviewed project or in an ignored path when it must survive the session.
-`hivex review --check <saved-report.json> --root <project>` checks documentary and implementation
-freshness without a model. A current report is not proof of correct code; a stale report does not
-cover subsequent changes. Review output never replaces general code review, lint or tests.
+Save a report outside the reviewed project or in an ignored path when it must survive the session. `hivex review --check <saved-report.json> --root <project>` checks documentary and implementation freshness without a model. A current report is not proof of correct code; a stale report does not cover subsequent changes. Review output never replaces general code review, lint or tests.
 
 ## Maintain knowledge
 
-The implementing agent maintains the documents as part of the change. Hivex may identify affected
-documents or suggest a correction, but does not rewrite project decisions on its own. Correct an
-incorrect graph interpretation against its source; do not alter doctrine to satisfy the model.
+The implementing agent maintains the documents as part of the change. Hivex may identify affected documents or suggest a correction, but does not rewrite project decisions on its own. Correct an incorrect graph interpretation against its source; do not alter doctrine to satisfy the model.
 
-Keep documents at their monorepo, package or module authority. Follow the project's existing layout
-and format. When establishing or improving documentation, use the optional
-[Markdown convention](references/markdown.md); it is guidance, not an installation prerequisite.
+Keep documents at their monorepo, package or module authority. Follow the project's existing layout and format. When establishing or improving documentation, use the optional [Markdown convention](references/markdown.md); it is guidance, not an installation prerequisite.
 
-Detect new, changed or removed documents before relying on the graph. Use the installed update
-workflow within the same work budget. Working documents may be queried without a commit, but that
-state is not approval; preserve the exact versions used by a review. Pending or uncertain knowledge
-limits the conclusions that depend on it, without making unrelated context unusable.
+Detect new, changed or removed documents before relying on the graph. Use the installed update workflow within the same work budget. Working documents may be queried without a commit, but that state is not approval; preserve the exact versions used by a review. Pending or uncertain knowledge limits the conclusions that depend on it, without making unrelated context unusable.
 
-`ask` updates at most one relevant pending batch before answering, under the same total call/input
-budget. Its default is three calls. Omitted limits preserve a resumed work item's budget. Repeat the same task to resume; changing its budget changes the
-total ceiling, never the consumed count. Pending corpus coverage is explicit; use `update` when more
-rounds are needed, rather than issuing repeated identical questions to force indexing.
+`ask` updates at most one relevant pending batch before answering, under the same total call/input budget. Its default is three calls. Omitted limits preserve a resumed work item's budget. Repeat the same task to resume; changing its budget changes the total ceiling, never the consumed count. Pending corpus coverage is explicit; use `update` when more rounds are needed, rather than issuing repeated identical questions to force indexing.
 
-An ordinary consultation does not ingest every declared historical source. A focused source is marked
-as historical in supplied packets, decisions and evidence, and its extracted decisions retain
-historical status with their conditions, exceptions, warnings and source ranges. If a required
-historical dependency is outside the declared scope, inspect `unavailableDocuments` and the reported
-coverage instead of treating the answer as complete.
+An ordinary consultation does not ingest every declared historical source. A focused source is marked as historical in supplied packets, decisions and evidence, and its extracted decisions retain historical status with their conditions, exceptions, warnings and source ranges. If a required historical dependency is outside the declared scope, inspect `unavailableDocuments` and the reported coverage instead of treating the answer as complete.
 
-Repair a demonstrably wrong interpretation with `update --repair <document> --reason <correction>`.
-Check the Markdown first. This revises derived knowledge and its relationships without changing the
-document or authorizing new policy. Do not use it to suppress a genuine contradiction. Review source-local
-warnings in their stated scope and inspect `unavailableDocuments` for changed or removed dependencies.
+Repair a demonstrably wrong interpretation with `update --repair <document> --reason <correction>`. Check the Markdown first. This revises derived knowledge and its relationships without changing the document or authorizing new policy. Do not use it to suppress a genuine contradiction. Review source-local warnings in their stated scope and inspect `unavailableDocuments` for changed or removed dependencies.
 
 ## Share reusable knowledge
 
-`hivex snapshot export` saves the current graph to `.hivex/graph.json`, suitable for Git alongside its
-Markdown sources. It retains source versions, evidence, available provenance and partial/uncertain
-coverage; it does not export local attempts, budgets, process locks or model caches. Snapshot commands
-make no model calls. Keep the SQLite store and locks ignored while allowing the shared JSON file.
+`hivex snapshot export` saves the current graph to `.hivex/graph.json`, suitable for Git alongside its Markdown sources. It retains source versions, evidence, available provenance and partial/uncertain coverage; it does not export local attempts, budgets, process locks or model caches. Snapshot commands make no model calls. Keep the SQLite store and locks ignored while allowing the shared JSON file.
 
-A clone without local knowledge can read the snapshot directly and reuse its matching units on the
-first update. Existing local knowledge takes precedence; `hivex snapshot import` explicitly adopts
-the shared graph and refuses if work is unfinished. Preserve that work and its accounting rather than
-deleting the store to force import. Stale or unavailable source versions remain explicit, and source
-freshness is not semantic approval. Export when knowledge changes; ordinary reads do not dirty the
-shared artifact.
+A clone without local knowledge can read the snapshot directly and reuse its matching units on the first update. Existing local knowledge takes precedence; `hivex snapshot import` explicitly adopts the shared graph and refuses if work is unfinished. Preserve that work and its accounting rather than deleting the store to force import. Stale or unavailable source versions remain explicit, and source freshness is not semantic approval. Export when knowledge changes; ordinary reads do not dirty the shared artifact.
+
+When Markdown moves, use `hivex snapshot relocate <old-document> <new-document>` before updating knowledge. The old source must no longer be selected, and the destination must be selected current Markdown. This explicit operation preserves decision and relationship IDs and does not call the model or rewrite earlier work, answers, attempts or budgets. Unfinished work must be resolved through its normal lifecycle first.
+
+An identical document at a previously unknown destination reuses its knowledge and ingestion coverage when retained evidence has matching, known source versions. Changed content, mixed or missing source versions, or consolidation into an existing destination leaves that destination pending for the normal update/check; it does not certify the old interpretation against new text. Retain the relocation report with the change and export the resulting graph alongside its Markdown. Do not relocate unrelated knowledge merely to hide unavailable evidence.
 
 ## Control consumption
 
-Large Markdown is ingested in bounded rounds. Inspect pending units and coverage, and resume the
-same work; do not wipe the store or resend the whole corpus when only a later round remains.
+Large Markdown is ingested in bounded rounds. Inspect pending units and coverage, and resume the same work; do not wipe the store or resend the whole corpus when only a later round remains.
 
-A budget covers the complete work item, its phases and attempts. Resume retained progress with its
-original accounting; do not start a fresh counter to bypass an exhausted limit. Separate initial
-indexing, maintenance, consultation and review costs and report actual usage and unknown consumption.
-Deterministic reads do not require another model call, although the caller consumes context tokens.
+A budget covers the complete work item, its phases and attempts. Resume retained progress with its original accounting; do not start a fresh counter to bypass an exhausted limit. Separate initial indexing, maintenance, consultation and review costs and report actual usage and unknown consumption. Deterministic reads do not require another model call, although the caller consumes context tokens.
 
-Do not automatically retry semantic disagreements or keep correcting until the model says green.
-After a crash, use `recover` to inspect retained work. It must not alter live owners or processes.
-An explicit `--acknowledge-uncertain` preserves uncertainty and cost; it does not certify a remote
-outcome or authorize an automatic retry. Resume only the intended work with its existing budget.
-Use `prune` for obsolete completed work and cached responses when needed; keep unfinished work and
-export evidence that must outlive cache retention.
+Do not automatically retry semantic disagreements or keep correcting until the model says green. After a crash, use `recover` to inspect retained work. It must not alter live owners or processes. An explicit `--acknowledge-uncertain` preserves uncertainty and cost; it does not certify a remote outcome or authorize an automatic retry. Resume only the intended work with its existing budget. Use `prune` for obsolete completed work and cached responses when needed; keep unfinished work and export evidence that must outlive cache retention.
 
-Preserve useful results and their limits. At a budget boundary, explain what remains and obtain an
-authorized extension before spending more. Existing user authorization remains valid; the skill does
-not require another permission question for already authorized work.
+Preserve useful results and their limits. At a budget boundary, explain what remains and obtain an authorized extension before spending more. Existing user authorization remains valid; the skill does not require another permission question for already authorized work.
 
-If maintenance reports `context-limit`, inspect `work.contextLimit` for required documents and bytes.
-Restore missing evidence or adjust the context bound, then resume the same task. No extraction call
-is spent while its known relationship evidence is unavailable or exceeds that bound.
+If maintenance reports `context-limit`, inspect `work.contextLimit` for required documents and bytes. Restore missing evidence or adjust the context bound, then resume the same task. No extraction call is spent while its known relationship evidence is unavailable or exceeds that bound.

package/skills/hivex/references/markdown.md

@@ -1,17 +1,12 @@
 # Optional Markdown convention
 
-Use the project's existing Markdown as it is. Hivex must not require this convention, frontmatter,
-numbered ADRs or a particular directory structure. Recommend these practices when adopting Hivex or
-writing documentation, without repeatedly proposing a migration of an established project.
+Use the project's existing Markdown as it is. Hivex must not require this convention, frontmatter, numbered ADRs or a particular directory structure. Recommend these practices when adopting Hivex or writing documentation, without repeatedly proposing a migration of an established project.
 
-These practices draw on Compi's authority map and documentation layout and the domain-modeling
-skill. They preserve the useful documentation discipline, not Compi's retired machinery.
+These practices draw on established authority-map and documentation-layout patterns and the domain-modeling skill. They preserve useful documentation discipline without prescribing retired machinery from any one project.
 
 ## Give knowledge one authoritative home
 
-Keep shared decisions at project or monorepo level. Package-specific or module-specific knowledge
-can stay with that package or module. Link shared rules instead of copying them into each area.
-Folders and files appear only when there is useful content to put in them.
+Keep shared decisions at project or monorepo level. Package-specific or module-specific knowledge can stay with that package or module. Link shared rules instead of copying them into each area. Folders and files appear only when there is useful content to put in them.
 
 A useful catalogue distinguishes:
 
@@ -23,57 +18,32 @@ A useful catalogue distinguishes:
 - Procedures for concrete operational or recovery tasks.
 - Research and evidence identified as dated support, not automatically current decisions.
 
-For example, a project may use `docs/README.md`, `docs/CONTEXT.md`, `docs/adr/`,
-`docs/guidelines/`, `docs/process/`, `docs/procedures/` and `docs/research/`. These are examples,
-not required paths. Multiple bounded contexts may have their own glossary and decisions with a
-small context map linking them; a monorepo need not duplicate one shared product glossary.
+For example, a project may use `docs/README.md`, `docs/CONTEXT.md`, `docs/adr/`, `docs/guidelines/`, `docs/procedures/` and `docs/research/`. Keep standing rules and design guidance in `guidelines`, and instructions for carrying out tasks in `procedures`; avoid overlapping directories with indistinct purposes. These are examples, not required paths. Multiple bounded contexts may have their own glossary and decisions with a small context map linking them; a monorepo need not duplicate one shared product glossary.
 
 ## Write decisions for the next reader
 
-State what was decided and why. Include the scope, conditions and exceptions that change how the
-rule is applied. Link the source or decision it depends on or replaces. A short paragraph can be
-enough; optional sections should carry information rather than serve as boxes to fill in.
+State what was decided and why. Include the scope, conditions and exceptions that change how the rule is applied. Link the source or decision it depends on or replaces. A short paragraph can be enough; optional sections should carry information rather than serve as boxes to fill in.
 
 For a consequential architectural trade-off, an ADR might be:
 
 ```markdown
 # Remove private cached data when access is revoked
 
-Cached private data is removed immediately when access is revoked. The normal cache lifetime
-still applies while access remains valid. This prevents stale local access after a permission
-change. See the cache policy for the general retention rule.
+Cached private data is removed immediately when access is revoked. The normal cache lifetime still applies while access remains valid. This prevents stale local access after a permission change. See the cache policy for the general retention rule.
 ```
 
-A title, truthful status and decision date can improve cataloguing. Tags are optional. If a rule is
-replaced, identify the replacement and whether the change is partial. Keep the historical reasoning
-readable; do not silently rewrite the past. A missing status means uncertainty to resolve from the
-content, not permission to assume acceptance.
+A title, truthful status and decision date can improve cataloguing. Tags are optional. If a rule is replaced, identify the replacement and whether the change is partial. Keep the historical reasoning readable; do not silently rewrite the past. A missing status means uncertainty to resolve from the content, not permission to assume acceptance.
 
-Use an ADR when the choice is consequential, reflects a real trade-off and would be surprising
-without its rationale. Do not create one for every routine edit or dependency. Sequential names
-such as `0001-short-decision.md` are convenient if the project adopts that convention.
+Use an ADR when the choice is consequential, reflects a real trade-off and would be surprising without its rationale. Do not create one for every routine edit or dependency. Sequential names such as `0001-short-decision.md` are convenient if the project adopts that convention.
 
 ## Compact an ADR without losing its history
 
-When replaced text obscures a decision's current meaning, preserve that history in a clearly marked
-Markdown archive and keep the active document focused on applicable rules, reasons, dependencies
-and exceptions. A wholly superseded ADR can remain as a short pointer to its replacement and archive.
-Preserve referenced anchors or update their links. Do not archive a live exception merely because it
-is old, or change what an earlier decision meant while shortening its current presentation.
+When replaced text obscures a decision's current meaning, preserve that history in a clearly marked Markdown archive and keep the active document focused on applicable rules, reasons, dependencies and exceptions. A wholly superseded ADR can remain as a short pointer to its replacement and archive. Preserve referenced anchors or update their links. Do not archive a live exception merely because it is old, or change what an earlier decision meant while shortening its current presentation.
 
-Compi uses `docs/archive/adr/` for this purpose; other layouts remain valid. Historical evidence should
-be available for focused consultation without being loaded into every model context. Declare its
-relative globs in `hivex.json` under `history`, then use the installed CLI's `--source` selection or
-a known relationship for bounded retrieval. Compaction must not silently make necessary evidence
-inaccessible. The human or implementing agent maintains these documents; Hivex does not rewrite or
-move the sources.
+A project may use `docs/archive/adr/` for this purpose; other layouts remain valid. Historical evidence should be available for focused consultation without being loaded into every model context. Declare its relative globs in `hivex.json` under `history`, then use the installed CLI's `--source` selection or a known relationship for bounded retrieval. Compaction must not silently make necessary evidence inaccessible. The human or implementing agent maintains these documents; Hivex does not rewrite or move the sources.
 
 ## Keep the glossary focused
 
-Define each project-specific concept briefly and use that term consistently. A glossary explains
-what a concept is; it is not an implementation manual, task plan or collection of general programming
-terms. Group related concepts when it helps and link context-specific definitions instead of copying.
+Define each project-specific concept briefly and use that term consistently. A glossary explains what a concept is; it is not an implementation manual, task plan or collection of general programming terms. Group related concepts when it helps and link context-specific definitions instead of copying.
 
-Code and executable contracts explain mechanics. Markdown preserves the intent, constraints,
-decisions and reasons that code cannot explain. Update that knowledge alongside the change rather
-than leaving the only explanation in a conversation or private agent memory.
+Code and executable contracts explain mechanics. Markdown preserves the intent, constraints, decisions and reasons that code cannot explain. Update that knowledge alongside the change rather than leaving the only explanation in a conversation or private agent memory.

package/src/cli/diagnostic.ts

@@ -1,26 +1,36 @@
 import { HivexError } from '../errors.ts';
 
-function bounded(text: string) {
+const bounded = (text: string) => {
   let result = '';
   for (const char of text) {
-    if (Buffer.byteLength(JSON.stringify(result + char)) > 256) break;
+    if (Buffer.byteLength(JSON.stringify(result + char)) > 256) {
+      break;
+    }
     result += char;
   }
   return result;
-}
-
-export function diagnostic(error: unknown) {
+};
+export const diagnostic = (error: unknown) => {
   let failure = new HivexError({
     code: 'READ_FAILED',
     message: 'Unable to read project knowledge',
   });
-  if (error instanceof HivexError) failure = error;
-  else if (error instanceof Error)
+  if (error instanceof HivexError) {
+    failure = error;
+  } else if (Error.isError(error)) {
     failure = new HivexError({ code: 'READ_FAILED', message: error.message });
-  let details = failure.details;
-  if (details && Buffer.byteLength(JSON.stringify(details)) > 384) details = { omitted: true };
+  }
+  let { details } = failure;
+  if (details && Buffer.byteLength(JSON.stringify(details)) > 384) {
+    details = { omitted: true };
+  }
   const message = bounded(failure.message);
   return {
-    error: { code: failure.code, message, messageTruncated: message !== failure.message, details },
+    error: {
+      code: failure.code,
+      details,
+      message,
+      messageTruncated: message !== failure.message,
+    },
   };
-}
+};