@h1v35/hivex 0.1.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@h1v35/hivex",
+  "version": "0.1.0",
+  "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",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "mdast-util-from-markdown": "2.0.3",
+    "mdast-util-frontmatter": "2.0.1",
+    "mdast-util-gfm": "3.1.0",
+    "mdast-util-to-string": "4.0.0",
+    "micromark-extension-frontmatter": "2.0.0",
+    "micromark-extension-gfm": "3.0.0",
+    "micromark-util-normalize-identifier": "2.0.1",
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  },
+  "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",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "typescript-eslint": "8.64.0",
+    "prettier": "3.8.4"
+  },
+  "trustedDependencies": [],
+  "packageManager": "bun@1.4.2",
+  "engines": {
+    "bun": "1.4.2"
+  },
+  "license": "MIT",
+  "bin": {
+    "hivex": "src/cli.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "docs/README.md",
+    "docs/CONTEXT.md",
+    "docs/engineering.md",
+    "docs/adr/0003-independent-bun-installation.md",
+    "docs/adr/0010-practical-knowledge-assistance.md",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/H1V35/hivex.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skills/hivex/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: hivex
+description: Retrieve project decisions and their dependencies and exceptions with Hivex, support implementation and review, and maintain useful Markdown knowledge. Use when Hivex is requested or configured for a project.
+---
+
+# 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.
+
+## 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.
+
+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.
+
+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.
+
+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.
+
+## 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.
+
+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.
+
+## 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.
+
+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.
+
+`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.
+
+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.
+
+## 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.
+
+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.
+
+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.

package/skills/hivex/references/markdown.md

@@ -0,0 +1,64 @@
+# 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.
+
+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.
+
+## 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.
+
+A useful catalogue distinguishes:
+
+- An authority map explaining where each kind of knowledge belongs.
+- A domain glossary defining the project's terms, with avoided synonyms where useful.
+- Decisions and their reasons, often kept as ADRs.
+- Guidelines containing design invariants and lessons worth applying again.
+- Process documents explaining the working method.
+- 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.
+
+## 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.
+
+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.
+```
+
+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.
+
+## 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.
+
+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

@@ -0,0 +1,26 @@
+import { HivexError } from '../errors.ts';
+
+function bounded(text: string) {
+  let result = '';
+  for (const char of text) {
+    if (Buffer.byteLength(JSON.stringify(result + char)) > 256) break;
+    result += char;
+  }
+  return result;
+}
+
+export function 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)
+    failure = new HivexError({ code: 'READ_FAILED', message: error.message });
+  let details = failure.details;
+  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 },
+  };
+}

package/src/cli.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env bun
+import { checkReview } from './review.ts';
+import { documentCommand } from './documents.ts';
+import { knowledgeMaintenance } from './knowledge-maintenance.ts';
+import { knowledgeCommand } from './knowledge.ts';
+import { diagnostic } from './cli/diagnostic.ts';
+
+async function main(args: string[]) {
+  if (!args.length || args.includes('--help'))
+    return {
+      application: 'hivex',
+      purpose: 'Project decisions, dependencies and exceptions for the responsible agent.',
+      commands: [
+        {
+          name: 'sources',
+          usage:
+            'sources [--root <project>] [--limit <count>] [--cursor <continuation>] [--max-bytes <bytes>]',
+          modelCalls: 0,
+        },
+        {
+          name: 'read',
+          usage:
+            'read <document> [--root <project>] [--from <line>] [--to <line>] [--max-bytes <bytes>]',
+          modelCalls: 0,
+        },
+        {
+          name: 'update',
+          usage:
+            'update [--root <project>] [--max-calls <total>] [--max-input-bytes <total>] [--repair <document> --reason <correction>]',
+          modelCalls:
+            'One extraction and one check per batch; retained work resumes within the same budget.',
+        },
+        {
+          name: 'search',
+          usage: 'search <query> [--root <project>] [--limit <count>]',
+          modelCalls: 0,
+        },
+        {
+          name: 'neighbors',
+          usage: 'neighbors <decision-id> [--root <project>] [--limit <count>]',
+          modelCalls: 0,
+        },
+        {
+          name: 'ask',
+          usage:
+            'ask <task> [--root <project>] [--source <document>] [--max-calls <total>] [--max-input-bytes <total>] [--max-context-bytes <bytes>]',
+          modelCalls:
+            'One bounded automatic update/check batch and Luna/max assistance share a total budget; identical retained answers are reused.',
+        },
+        {
+          name: 'review',
+          usage:
+            'review <task> --base <git-ref> [--root <project>] [--source <document>] [--max-calls <total>] [--max-context-bytes <bytes>] | review --check <saved-report.json> [--root <project>]',
+          modelCalls:
+            'One automatic update/check batch and a review share one budget. Checking saved versions needs no model.',
+        },
+        {
+          name: 'recover',
+          usage: 'recover [--root <project>] [--acknowledge-uncertain]',
+          modelCalls: 0,
+        },
+        {
+          name: 'prune',
+          usage: 'prune [--root <project>] [--keep-completed <count>] [--keep-caches <count>]',
+          modelCalls: 0,
+        },
+        { name: 'status', usage: 'status [--root <project>]', modelCalls: 0 },
+      ],
+      modelOptions: '--codex <native-binary> --deadline-ms <100..1800000> --retry-failed',
+      configuration: 'Optional hivex.json with include/exclude relative Markdown globs.',
+      stage: 'Incremental project knowledge and task/diff assistance for the principal agent.',
+    };
+  if (args[0] === 'review' && args.includes('--check')) return checkReview(args);
+  if (args[0] === 'sources' || args[0] === 'read') return documentCommand(args);
+  if (args[0] === 'recover' || args[0] === 'prune') return knowledgeMaintenance(args);
+  return knowledgeCommand(args);
+}
+
+try {
+  const result = await main(process.argv.slice(2));
+  process.stdout.write(JSON.stringify(result) + '\n');
+  if (
+    result &&
+    typeof result === 'object' &&
+    'status' in result &&
+    (result.status === 'failed' || result.status === 'blocked')
+  )
+    process.exitCode = 1;
+} catch (error) {
+  process.stderr.write(JSON.stringify(diagnostic(error)) + '\n');
+  process.exitCode = 1;
+}