@h1v35/hivex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 H1V35
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# 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.
+
+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.
+
+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 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.
+
+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
+
+Use Bun 1.4.2. In this checkout:
+
+```sh
+bun install
+bun hivex --help
+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.
+
+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
+{
+  "include": ["docs/**/*.md", "packages/**/*.md", "src/**/decisions/*.md"],
+  "exclude": ["docs/archive/**"]
+}
+```
+
+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. Symlinks are not followed. The previous experimental `collections` configuration
+is rejected with a migration message rather than silently reinterpreted.
+
+## Recover context
+
+```sh
+bun hivex sources --root /path/to/project --limit 20
+bun hivex read docs/policy.md --root /path/to/project
+bun hivex search "cache access revocation" --root /path/to/project
+bun hivex neighbors <decision-id> --root /path/to/project --limit 24
+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.
+
+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.
+
+## Update and repair knowledge
+
+```sh
+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.
+
+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:
+
+```sh
+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 single project-local `.hivex/knowledge.sqlite` stores derived knowledge and work 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.
+
+## 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 [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
+
+```sh
+bun run typecheck
+bun run lint
+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).
+
+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:
+
+```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.

package/docs/CONTEXT.md

@@ -0,0 +1,59 @@
+# 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.
+
+## Language
+
+**Document**: A selected Markdown file, wherever its project, package or module keeps it.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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

@@ -0,0 +1,14 @@
+# 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.
+- [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.

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

@@ -0,0 +1,37 @@
+---
+title: Independent Bun installation
+status: accepted
+date: 2026-09-07
+---
+
+# Independent Bun installation
+
+## 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.
+
+## 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.
+
+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.
+
+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).

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

@@ -0,0 +1,92 @@
+---
+title: Practical knowledge assistance with bounded work
+status: accepted
+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.
+
+## 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.

package/docs/engineering.md

@@ -0,0 +1,174 @@
+---
+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.
+
+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.
+
+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).
+
+The lint configuration owns executable syntax/complexity constraints: cyclomatic complexity 20,
+cognitive complexity 15, at most four parameters, nesting depth three and no nested/chained
+ternaries. Refactor around meaningful responsibilities rather than adding tiny wrappers merely to
+make a number pass. Changes to those limits require a documented decision.
+
+## 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
+
+Early use in Compi can support validation and recovery before full retirement. Necessary adoption
+and verification work belongs to Hivex completion. Alternative model integrations are evolutionary work;
+keep the current Codex/Luna route usable without spreading its assumptions into the knowledge model.
+
+After knowledge recovery, replacement validation and consumer migration, 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.
+
+Early use can precede complete legacy recovery. Complete closure requires useful historical knowledge
+in Markdown, Hivex demonstrated in Compi and the old active machinery retired with its consumers.
+Validate the new 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. Compi adopts a pinned published version 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.