@h1v35/hivex 0.2.1 → 0.3.0

package/README.md

@@ -1,27 +1,57 @@
 # 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.
+A project foundation and reusable knowledge for autonomous agents. Hivex provides recommended Markdown, focused workflow skills and retrieval of decisions, dependencies and exceptions. Project Markdown remains authority and the responsible agent directs the work.
 
 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
+## Project foundation
 
-This release-in-development supplies initial updates and task consultation (#47), plus automatic incremental maintenance and interpretation repair (#48), and task/diff review assistance (#19). Release preparation remains separate from this CLI contract.
+Hivex combines incremental knowledge, local retrieval, optional model assistance and a small adoption workflow. Its five general skills cover design, documentation, implementation, independent review and Git/triage. Use the capabilities a task needs rather than a compulsory sequence.
 
-No installed command approves an implementation. The principal reviewer verifies findings, tests and the actual source evidence. See the [approved product decision](docs/adr/0010-practical-knowledge-assistance.md).
+No installed command approves an implementation. The principal reviewer checks findings, relevant tests and source evidence. The [knowledge decision](docs/adr/0010-practical-knowledge-assistance.md) and [foundation decision](docs/adr/0012-project-foundation-and-workflow.md) define these responsibilities.
 
-## Install the CLI and skill
+## Install the CLI and skills
 
-Requires Bun 1.4.2. Once the release is available from npm:
+Requires Bun 1.4.2:
 
 ```sh
 bun add --dev --exact @h1v35/hivex
 bun hivex --help
 ```
 
-Copy `node_modules/@h1v35/hivex/skills/hivex` into the skill directory used by your agent. For an agent that discovers project skills in `.agents/skills`, use `.agents/skills/hivex`. Keep the CLI and skill at the same release; upgrade the copied skill when upgrading the package. The skill and its Markdown guide are portable and do not require private tools or other installed skills.
+The package includes `hivex`, `hivex-design`, `hivex-document`, `hivex-implement`, `hivex-review` and `hivex-git` under `skills/`. Install the directories together in the skill location your agent discovers. Keep them at the same release as the CLI; the relative references between these bundled skills should stay intact.
 
-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.
+For agents using project-local `.agents/skills`, package links avoid copied skills becoming stale. Run from the project root after installation:
+
+```sh
+mkdir -p .agents/skills
+for skill in hivex hivex-design hivex-document hivex-implement hivex-review hivex-git; do
+  target=".agents/skills/$skill"
+  if [ ! -e "$target" ] && [ ! -L "$target" ]; then
+    ln -s "../../node_modules/@h1v35/hivex/skills/$skill" "$target"
+  fi
+done
+```
+
+Existing skill entries are preserved; inspect them before replacing a custom or older installation. An agent using another discovery location can install the same directories there. The bundled skills do not require the former external general-workflow skill set.
+
+The current knowledge profile needs an authenticated Codex CLI session with Luna/max available. Invocation validates that profile without silent fallback. Document discovery, source/version checks, snapshot operations and initialization do not require a model.
+
+## Initialize a project
+
+```sh
+bun hivex init
+# Or prepare another existing project directory:
+bun hivex init --root /path/to/project
+```
+
+Initialization creates missing foundation documents, a source configuration and Git ignore rules that keep `.hivex/graph.json` shareable while local execution state stays ignored. It reports created, preserved and updated paths, makes no model calls, and does not install dependencies, configure global tools or write to GitHub. Repeating it preserves existing Markdown, configuration, graph and history.
+
+An existing `.hivex/.gitignore` with active patterns can override the root rules, exposing local state or hiding the snapshot. Initialization reports this conflict before writing files; reconcile those nested patterns with the root ignore policy before continuing.
+
+The foundation includes a short `AGENTS.md`, documentation map, draft PRD and glossary, ADR directory, engineering and triage guidelines, and a tracker procedure. The principal agent completes the project's actual purpose, vision and language from evidence and owner decisions. Draft headings do not stand in for those decisions.
+
+Use the documentation skill to migrate existing material to the standard when reasonably possible, preserving useful content, links, history and monorepo/package/module scope. The CLI does not infer semantic migrations or overwrite existing sources. The Git skill aligns useful labels and tracker conventions within the owner's authorization; project-specific areas remain local.
 
 ## Run
 
@@ -109,10 +139,18 @@ bun hivex snapshot export --root /path/to/project
 bun hivex snapshot import --root /path/to/project
 ```
 
-`snapshot export` writes `.hivex/graph.json` atomically as stable, readable JSON. Commit that file alongside the Markdown it describes to share decisions, relationships, source versions, evidence, available provenance and coverage. It exports the graph, not work records, process identities, budgets or cached model answers. Both snapshot operations make zero model calls.
+`snapshot export` writes `.hivex/graph.json` atomically as stable, readable JSON. Commit that file alongside the Markdown it describes to share decisions, relationships, source versions, evidence, available provenance and coverage. It exports the graph, not work records, process identities, budgets or cached model answers. Snapshot operations make zero model calls.
 
 A fresh clone can use `search`, `neighbors` and `status` directly from the shared snapshot without creating a local database. Its first update reuses matching ingestion units and starts local work accounting. If a local graph already exists, it takes precedence: use `snapshot import` to adopt a new shared version. Import refuses while local work is unfinished and never resets attempts or budgets. Complete or recover that work through its normal lifecycle first.
 
+When Markdown moves, explicitly relocate its knowledge before the next update:
+
+```sh
+bun hivex snapshot relocate docs/old-guide.md docs/guidelines/guide.md --root /path/to/project
+```
+
+The old source must no longer be selected, and the destination must be selected current Markdown. Relocation preserves IDs, relationships, source versions and uncertainty, leaving existing work, cached answers and budgets intact. It makes zero model calls and refuses unfinished local work. An identical move to a destination without prior knowledge reuses ingestion coverage when all retained source evidence has matching, known versions. If content changed, source versions are mixed or missing, or the destination already had knowledge, its coverage becomes pending so the usual update/check can validate the result. Mismatched evidence remains stale until then. Keep the relocation report with the change and export the final graph; do not use relocation to hide unrelated missing evidence.
+
 The snapshot response identifies current, stale and unavailable source versions, pending units and warnings. A changed or absent source is not silently current; matching sources remain reusable. Partial and uncertain knowledge can be shared with those states retained. Freshness is not proof that a model interpretation is correct: the cited Markdown remains authority.
 
 Keep only the shared graph under version control, for example:
@@ -124,11 +162,13 @@ Keep only the shared graph under version control, for example:
 
 Read-only queries do not rewrite the snapshot. Export intentionally when reusable knowledge changes, not on every consultation. Invalid snapshots or symbolic-link paths fail without replacing local knowledge. Existing local stores continue to work without a shared file.
 
-## Agent skill and Markdown practice
+## Workflow skills and Markdown practice
+
+The [Hivex skill](skills/hivex/SKILL.md) handles local retrieval, incremental knowledge, uncertainty and accounting. The additional capabilities are [design](skills/hivex-design/SKILL.md), [documentation](skills/hivex-document/SKILL.md), [implementation](skills/hivex-implement/SKILL.md), [review](skills/hivex-review/SKILL.md) and [Git/triage](skills/hivex-git/SKILL.md).
 
-The [portable Hivex skill](skills/hivex/SKILL.md) teaches consultation before implementation, support to the principal reviewer, documentation maintenance, uncertainty and budget handling. It uses the installed CLI's actual interface and does not require private tools or other skills.
+The [Markdown foundation](skills/hivex/references/markdown.md) defines the recommended adoption layout, concise agent entrypoint, purpose, glossary, decisions, guidelines and procedures. Knowledge operations continue to accept other Markdown layouts. Preserve a project's useful rules and exceptions when adopting the baseline.
 
-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.
+Prefer DDD and meaningful responsibilities, risk/value-based tests with optional TDD, and one independent review by default. The reviewer matches the implementation agent's model and effort. Use local knowledge before model-assisted interpretation, and explain technical details clearly when they matter to the owner's understanding or decisions.
 
 ## Development
 
@@ -139,7 +179,7 @@ bun run format:check
 bun run test
 ```
 
-Tests use the public CLI and a simulated native transport. Real Luna evaluations are bounded and reported separately; simulated token usage is not a consumption measurement. Development is issue-first, with coherent PRs, independent Standards/Spec review and CI on the final commit. See the [engineering workflow](docs/engineering.md).
+Tests use the public CLI and a simulated native transport. Real Luna evaluations are bounded and reported separately; simulated token usage is not a consumption measurement. Development is issue-first, with coherent PRs, an independent review covering scope/correctness/standards and CI on the final commit. See the [engineering workflow](docs/guidelines/engineering.md).
 
 Earlier candidate/fidelity/comparison/admission protocols and their tests are retired from the active CLI. Their code remains in Git history and historical evidence keeps its original results. They do not impose a requirement to reproduce an Opus graph or exhaustively replay an old gold suite.
 

package/docs/CONTEXT.md

@@ -4,6 +4,12 @@ Hivex supplies project knowledge to the agents responsible for implementation an
 
 ## Language
 
+**Project foundation**: The recommended starting documents, workflow capabilities and knowledge practices that an adopting project tailors to its own purpose and decisions.
+
+**Initialization**: Preparing missing foundation files and configuration without supplying new project facts or replacing existing knowledge.
+
+**Adoption**: Fitting the foundation to a project by completing its meaning, preserving useful existing knowledge and aligning documentation and working practices.
+
 **Document**: A selected Markdown file, wherever its project, package or module keeps it.
 
 **Archived document**: Historical Markdown preserved as evidence of replaced decisions and their reasons. It remains available for focused retrieval without being presumed current authority.
@@ -34,6 +40,8 @@ Hivex supplies project knowledge to the agents responsible for implementation an
 
 **Interpretation repair**: Replacing a wrong derived interpretation by comparing it with unchanged Markdown. It preserves source authority and does not resolve a genuine policy conflict by itself.
 
+**Source relocation**: Moving existing knowledge to a document's new location, retaining its decisions and relationships while distinguishing reusable evidence from content that needs a new check.
+
 **Context**: The decisions, related evidence and remaining uncertainties relevant to a particular task.
 
 **Implementation version**: The captured change against a particular base together with the exact contents of the affected files. Later code changes are outside that review.

package/docs/README.md

@@ -1,10 +1,13 @@
 # Documentation map
 
 - [Domain language](CONTEXT.md): documents, decisions, relationships, evidence and bounded work.
-- [Engineering workflow](engineering.md): development, verification and knowledge maintenance.
+- [Engineering guidelines](guidelines/engineering.md): development, verification and knowledge maintenance.
+- [Triage labels](guidelines/triage-labels.md) and [tracker procedure](procedures/issue-tracker.md): work selection, Git and review.
+- [Runner procedure](procedures/self-hosted-runner.md): install and move the repository's CI runner.
 - [Practical knowledge assistance](adr/0010-practical-knowledge-assistance.md): the current approved contract, staged delivery, autonomy, semantic relationships, uncertainty and cost.
 - [Shared knowledge and selective history](adr/0011-shared-knowledge-and-selective-history.md): accepted extension for compact ADRs, bounded historical retrieval and a Git-versioned knowledge snapshot.
-- [Recommended Markdown convention](../skills/hivex/references/markdown.md): optional organization and writing practices for any adopting project.
+- [Project foundation and workflow](adr/0012-project-foundation-and-workflow.md): initialization, the five shared capabilities, triage and efficient agent instructions.
+- [Recommended Markdown convention](../skills/hivex/references/markdown.md): the default adoption structure and writing practices, with preservation of existing project knowledge.
 - [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/0011-shared-knowledge-and-selective-history.md

@@ -25,3 +25,7 @@ Use deterministic structural and source-version checks to distinguish reusable k
 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/adr/0012-project-foundation-and-workflow.md

@@ -0,0 +1,21 @@
+---
+title: Project foundation and adaptive workflow
+status: accepted
+date: 2026-09-13
+---
+
+# Project foundation and adaptive workflow
+
+Adopting Hivex should establish a useful base for autonomous project work as well as reusable knowledge. Distribute a small documentation foundation and five independent skills for design, documentation, implementation, review and Git/triage, alongside the knowledge-support skill. This extends the distribution scope of [ADR 0010](0010-practical-knowledge-assistance.md); the CLI does not become a development-session orchestrator or the principal reviewer.
+
+`init` prepares missing project Markdown, source configuration and Git visibility rules with no model calls. It preserves existing files and local knowledge. The principal agent completes purpose, vision and domain language from actual evidence and owner decisions, and guides migration to the standard where reasonably possible. Preserve useful content, links, history and monorepo/package/module authority. Existing layouts remain valid inputs to knowledge operations.
+
+Use mature, reusable engineering and documentation practices, leaving a consumer's product, stack, host and historical authorization details in that consumer. Prefer DDD and meaningful module responsibilities without imposing hexagonal architecture or speculative abstractions. Work uses the capabilities it needs; neither every planning stage nor additional tickets are compulsory when the change is already defined.
+
+Choose tests by value and risk, including critical flows, stable rules and regressions. TDD is optional when behavior is defined. Use one independent review by default, and another when concrete risk or findings warrant it; the reviewer uses the implementation agent's model and effort. The knowledge model remains a separate role. Start knowledge assistance with local retrieval and source reading, calling the model when it adds value. Preserve budget, history and uncertainty rather than rerunning work to obtain approval.
+
+Use readiness, participation, dependency, type, scope and risk labels for their distinct purposes. Labels neither select models nor grant permission. Work labels such as `epic`, `research`, `prototype` and `decision` should survive replacement of a skill; avoid aliases that repeat existing meaning.
+
+Keep AGENTS.md as a concise entrypoint, with orientation, development/verification guidance and relevant project-specific constraints. Its links identify when an authority matters; they do not force every source into every task. The [open AGENTS.md convention](https://agents.md/) requires no fields beyond ordinary Markdown, so the foundation supplies a recommended shape rather than a proprietary schema or line-count limit.
+
+Skills use focused descriptions and conditional references, preserving the user's scope and existing authorization. Retire superseded general skills only after their useful capabilities and callers are covered; specialized skills remain separate. Communicate in clear language, briefly explaining unfamiliar technical terms when they matter to understanding or deciding.

package/docs/{engineering.md → guidelines/engineering.md}

@@ -9,23 +9,19 @@ Hivex is a TypeScript/Bun product. Modules group behavior by domain responsibili
 
 ## 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.
+Work is issue-first in `H1V35/hivex`. Use design, documentation, implementation, review and Git as capabilities selected for the task. Resolve open decisions through discovery or a grill, and create additional specs or execution tickets when they help define or divide work. A defined change can proceed directly to implementation and 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.
+Use one independent review by default, covering scope, correctness and standards; add another when concrete risk or findings justify it. Independent code reviewers use the implementing 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.
+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).
 
-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).
+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.
 
@@ -35,7 +31,7 @@ Runtime settings identify Bun globals and Bun executables while keeping the pres
 
 ## 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.
+Choose tests for value and risk, prioritizing critical flows, stable rules and demonstrated regressions. TDD is optional when behavior is sufficiently defined; explore unresolved behavior before committing its assumptions to tests. Do 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.
 
@@ -61,9 +57,9 @@ Keep docs with the monorepo, workspace or module they describe. Link to common r
 
 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.
+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.
+Start knowledge support with local search, neighbors and source reading, reusing current context. Use model-assisted interpretation or review when it adds useful information rather than as a mandatory step for every change. 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
 
@@ -76,3 +72,9 @@ A replacement workflow can be used before every historical artifact is retired w
 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.
+
+## Shared project foundation
+
+The [foundation decision](../adr/0012-project-foundation-and-workflow.md) adds a recommended documentation and workflow baseline to Hivex distribution. The CLI prepares missing files without model calls; the principal agent completes meaningful project content and migrates existing documentation when appropriate. Preserve monorepo, package and module authority and the adopting project's actual decisions.
+
+Keep AGENTS.md as a brief, consistent entrypoint with relevant pointers and indispensable project details. Use clear language, explaining a technical term when it matters to understanding or a decision, without explaining every term or changing the owner's requested level of detail.

package/docs/guidelines/triage-labels.md

@@ -0,0 +1,29 @@
+# Triage labels
+
+Labels should help people and agents select or act on work. Keep their meanings distinct and the catalogue small.
+
+## Readiness
+
+| Label             | Meaning                                           |
+| ----------------- | ------------------------------------------------- |
+| `needs-triage`    | The issue needs evaluation.                       |
+| `needs-info`      | Essential information is missing.                 |
+| `ready-for-agent` | The work is defined enough for an agent to begin. |
+| `ready-for-human` | The work requires human implementation.           |
+| `wontfix`         | The issue will not be actioned.                   |
+
+Keep the readiness state coherent. Readiness does not promise that every later decision is settled, select a model or override an unresolved dependency.
+
+## Participation, dependencies and risk
+
+`AFK` means the stated work can finish without further owner participation; `HITL` means owner participation is expected before completion. Use these when they help coordination. Neither grants permission or replaces readiness.
+
+Use native issue dependencies for actual blockers and `blocked` when a visible blocked marker helps selection. `deferred` means the work is decided but intentionally not scheduled. Avoid starting blocked or deferred work merely because its scope is defined.
+
+`high-risk` directs review attention to consequential changes. It does not choose a vendor, model or fixed number of reviews. Security severity labels (`severity: critical`, `severity: high`, `severity: moderate`, `severity: low`) describe the finding's severity, which is distinct from implementation risk.
+
+## Type and scope
+
+Use useful work types such as `bug`, `enhancement`, `documentation`, `refactor`, `testing`, `architecture`, `security`, `performance` or `ci`. `epic` groups coherent child work; `research`, `prototype` and `decision` identify work that resolves uncertainty. These names describe the work and do not depend on a particular skill.
+
+Use area or component labels that match this project. Preserve useful existing classification when adopting the standard; do not import another product's area catalogue or add labels that repeat the title. Follow the [tracker procedure](../procedures/issue-tracker.md).

package/docs/procedures/issue-tracker.md

@@ -0,0 +1,21 @@
+# Issues, triage and pull requests
+
+Hivex uses GitHub issues and pull requests in `H1V35/hivex`, with the `gh` CLI. Work is issue-first, with a coherent branch and PR for each change. Tracker/PR text and commit messages are Spanish; code, branches and repository Markdown are English. Commits and PR titles use an emoji followed by a Conventional Commit type/scope and a Spanish description.
+
+## Define and select work
+
+Read the relevant issue, discussion and dependencies. Reuse an existing issue when its scope covers the request or finding; create a separate one when it is independently actionable or cannot fit the current scope. Read-only retrieval does not require a new issue.
+
+Describe the intended outcome, boundaries and useful acceptance evidence. Split work into independently verifiable changes when that helps execution. Do not require a separate spec, a long user-story list or decision-map hierarchy for a task already defined.
+
+Apply the [triage labels](../guidelines/triage-labels.md) consistently. Work is selectable when its scope is ready and actual blockers are resolved. Labels do not authorize external actions or select the model. Ask only for decisions or information that cannot be recovered from existing evidence.
+
+## Implement, review and integrate
+
+Start from the current integration branch and keep changes coherent. Use the project's commit conventions; Conventional Commits provide a useful default. Prefer existing checks and native Git/tracker capabilities to an additional orchestration layer.
+
+Complete the relevant verification and independent review, then open a clear PR linked to its issue. Explain the resulting behavior, the validation actually completed and material limits. Follow CI to an actual result; a queued or skipped check is not a pass.
+
+Merge within the owner's existing authorization after required checks and review. Do not infer authority from readiness or supervision labels. Preserve shared history and clean up the local/remote branches and worktrees belonging to finished work. Implementation changes must be integrated; completed research, evidence or prototypes must have their useful results and required history retained before cleanup. Keep unfinished or uncertain work intact, regardless of branch age or whether it has a PR. Do not discard unmerged work without an established disposition and the applicable owner authorization.
+
+Record durable decisions in the appropriate Markdown authority and export changed Hivex knowledge with its sources. A tracker discussion is useful evidence but does not replace maintained project documentation.

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,6 +1,6 @@
 {
   "name": "@h1v35/hivex",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "Versioned project knowledge for people and agents.",
   "scripts": {
@@ -63,10 +63,14 @@
     "!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",
+    "docs/adr/0012-project-foundation-and-workflow.md",
+    "docs/guidelines/triage-labels.md",
+    "docs/procedures/issue-tracker.md",
     "skills/",
     "README.md",
     "LICENSE"

package/skills/hivex/SKILL.md

@@ -1,66 +1,46 @@
 ---
 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.
+description: Adopt Hivex's project foundation, retrieve relevant project decisions and their dependencies or exceptions, and maintain reusable Markdown knowledge. Use when Hivex is requested or configured for a project.
 ---
 
-# Hivex
+# Project knowledge and foundation
 
-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.
+Markdown records project intent and decisions. Hivex retrieves derived knowledge and its relationships for the agent responsible for design, implementation or review. Recover settled decisions before asking the owner to decide them again.
 
-## Start with the installed interface
+## Use the installed capabilities
 
-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 brief agent entrypoint and source configuration. Use `hivex --help` when the installed interface is unfamiliar; in a Bun project, `bun hivex` resolves the installed CLI. The package is `@h1v35/hivex`, not the unrelated unscoped package. Do not invent commands or silently change the knowledge model.
 
-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.
+For adoption, use `init` when the installed version provides it. It prepares missing documents and configuration without model calls. Use `hivex-document` to complete project meaning and migrate existing documentation to the standard when appropriate, and `hivex-git` for the tracker and labels. The five workflow skills are independent capabilities, not compulsory phases.
 
-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.
+## Retrieve before deciding
 
-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.
+Start with focused `search`, `neighbors` and `read`. Read the evidence and follow relevant dependencies, exceptions and replacements, including indirect ones. Reuse current context instead of repeating a query for every file.
 
-## Before implementation
+A preview, accepted label or isolated warning does not establish the full meaning. Check scope, conditions, versions and later decisions. If the sources settle the matter, apply it; otherwise explain the actual unresolved decision and recommend a course of action.
 
-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 `ask` for model-assisted interpretation when it adds value. It may maintain one relevant pending batch before answering under the same work budget. Explicit `--source` selection can focus current or historical evidence. Ordinary queries do not require ingesting all declared history.
 
-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.
+## Maintain the derived knowledge
 
-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.
+The principal agent maintains the Markdown. Detect new, changed or removed sources before relying on related graph entries, and use incremental `update` when needed. Large documents are processed in bounded rounds; preserve partial progress and the same work's consumed budget. Do not resend the whole corpus when only a later round remains.
 
-## During review
+When sources move, use `snapshot relocate <old> <new>` before updating. It preserves identities, relationships, evidence versions and prior work without model calls. Only an identical source with matching known versions at a previously unknown destination reuses coverage; changes, mixed or missing versions and consolidation remain pending for normal maintenance. Do not relocate unrelated knowledge to hide a warning.
 
-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.
+Repair a demonstrated interpretation error with `update --repair <document> --reason <correction>` after checking the source, its dependencies and replacements. Do not repair correct knowledge merely because a warning omits context, or change doctrine to satisfy the model. Keep unresolved limitations explicit.
 
-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.
+## Support review
 
-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.
+The principal reviewer directs implementation review and uses the implementing agent's model and effort. Hivex's knowledge model is separate. Use local evidence first; run `review "<task>" --base <git-ref>` only when model-assisted support adds useful information.
 
-## Maintain knowledge
+Confirm any finding against the actual code and documentary versions. A lack of model findings is not implementation approval. Save a review report outside the reviewed project or in an ignored location when needed; `review --check <report>` verifies its documentary and implementation freshness without a model call.
 
-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.
+## Share progress and preserve accounting
 
-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.
+After useful knowledge changes, `snapshot export` writes `.hivex/graph.json` for Git alongside its sources. Local SQLite, attempts, locks and caches remain ignored. A fresh clone reuses a matching snapshot; existing local state takes precedence until an explicit `snapshot import`, which refuses unfinished work.
 
-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.
+Budgets cover all phases and attempts of a work item. Resume that work with its retained accounting; a larger total limit is not a fresh allowance. Existing owner authorization remains valid. Report actual completed usage and unknown consumption honestly, including failed or interrupted attempts.
 
-`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.
+Use `recover` for interrupted execution, not ordinary retrieval. An uncertainty acknowledgement preserves uncertainty and cost; it does not certify a remote outcome or authorize an automatic retry. Use `prune` for obsolete completed work/caches when appropriate, preserving unfinished work and required evidence. Do not wipe state, restart counters or repeat semantic checks merely to obtain approval.
 
-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.
-
-## 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.
-
-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.
-
-## 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.
+If a result reports a context limit, inspect the required evidence and restore it or adjust the bound within scope before resuming the same work. Keep native execution permissions and timeouts appropriate to the task. For document layout and source conventions, consult [Markdown guidance](references/markdown.md) when establishing or reorganizing knowledge.

package/skills/hivex/assets/project/AGENTS.md

@@ -0,0 +1,11 @@
+# Project instructions
+
+## Orientation
+
+Use Hivex to recover relevant decisions, dependencies and exceptions before proposing or changing behavior. The [documentation map](docs/README.md) identifies the Markdown authorities; consult the parts relevant to the task.
+
+## Development
+
+Follow the [engineering guideline](docs/guidelines/engineering.md) for implementation and review. Use the project's documented setup and verification commands, scoped to the affected work.
+
+For issues, triage and pull requests, follow the [tracker procedure](docs/procedures/issue-tracker.md). Preserve decisions and authorizations already supplied by the owner.

package/skills/hivex/assets/project/docs/CONTEXT.md

@@ -0,0 +1,8 @@
+---
+title: Domain language
+status: draft
+---
+
+# Ubiquitous language
+
+## Terms

package/skills/hivex/assets/project/docs/PRD.md

@@ -0,0 +1,16 @@
+---
+title: Project purpose and scope
+status: draft
+---
+
+# Product brief
+
+## Purpose and problem
+
+## Users and their needs
+
+## Vision and intended outcomes
+
+## Scope and non-goals
+
+## Constraints and open decisions

package/skills/hivex/assets/project/docs/README.md

@@ -0,0 +1,18 @@
+# Documentation map
+
+Markdown records project intent, terminology, rules and reasons. Hivex retrieves this knowledge and its relationships; its graph is derived assistance. The responsible agent checks applicability against the sources and the owner's current decisions.
+
+- [PRD](PRD.md): purpose, problem, vision, users and scope. Draft sections are open work, not accepted product decisions.
+- [CONTEXT](CONTEXT.md): the project's agreed domain language.
+- [ADRs](adr/README.md): decisions whose reasons, alternatives or exceptions matter to future work.
+- [Engineering](guidelines/engineering.md): shared implementation and review principles.
+- [Triage](guidelines/triage-labels.md): the meaning and use of issue labels.
+- [Issue tracker](procedures/issue-tracker.md): how work enters and moves through Git and review.
+
+Guidelines define ongoing rules; procedures explain how to perform an operation. Folder placement alone does not grant or remove authority. Read the scope, status, conditions and later amendments of each document.
+
+Keep documents at the monorepo, package or module they describe. Link shared rules instead of copying them into every scope. Prefer this structure when adopting Hivex, preserving and completing useful existing documents and updating their links.
+
+Use `docs/archive/` when replaced detail needs preserving outside a concise current document. Leave an explicit replacement/history link in the current authority; historical material does not silently regain force. Hivex's history selection keeps this material available for focused retrieval.
+
+Maintain the owning document as part of a change. Do not leave durable decisions only in chats, tracker comments, model output or vendor-private memory.

package/skills/hivex/assets/project/docs/adr/README.md

@@ -0,0 +1,5 @@
+# Architectural and domain decisions
+
+Add a numbered Markdown decision when its rationale, alternatives, scope or exceptions will help future work. A short statement of the context, decision and reason can be sufficient; add detail when it matters.
+
+Preserve the distinction between proposed, current and replaced decisions. When changing a decision, record what changed and link its predecessor and replacement. Keep useful history without turning the current document into an unbounded transcript.

package/skills/hivex/assets/project/docs/guidelines/engineering.md

@@ -0,0 +1,37 @@
+# Engineering
+
+## Understand the change
+
+Use the project's Markdown and Hivex's relevant decisions, neighbors and sources to recover settled context. Apply the scope, conditions, exceptions and replacements. Ask the owner only when evidence cannot resolve a meaningful decision; give a clear recommendation.
+
+Choose the workflow the task needs. Implement a defined change directly, use a grill for open decisions, and use focused research or a disposable prototype when it answers a real question. Additional specs and tickets should help define or divide work. They are not mandatory stages for every task.
+
+## Design and implementation
+
+Prefer domain-driven design: group behavior by meaningful domain responsibilities, use the agreed language and keep interfaces small. Do not impose hexagonal architecture or speculative layers. Respect existing accepted project choices and raise genuine conflicts before replacing them.
+
+Prefer an existing library, standard facility or small direct implementation when it solves the problem. Create files and abstractions for meaningful responsibilities, not to satisfy arbitrary structure. Keep code self-explanatory; documentation records intent and reasons that code cannot explain.
+
+Delegate suitable bounded subtasks when authorized and useful. Keep responsibility for the integrated result. Model and effort choices belong to the task or project configuration, not to issue labels.
+
+## Tests and verification
+
+Choose checks for value and risk. Prioritize critical flows, stable rules and demonstrated regressions. TDD is optional when the behavior is sufficiently defined; use exploration first when product assumptions remain open.
+
+Test observable behavior at useful interfaces with independent expected results. Avoid tests that freeze internal helpers, arbitrary structure or the implementation's own calculation. Investigate failures against the intended behavior before deciding whether the code or the test needs correction.
+
+Run the relevant checks for the affected surfaces. Documentation and configuration need appropriate reference, format or behavior checks, not a test for every edit. Record what was actually verified and any material limits; do not turn unavailable or interrupted checks into passes.
+
+## Independent review
+
+Use one independent review by default, covering scope, correctness and project standards. Add another when concrete risk or findings justify it. The reviewer uses the implementing agent's model and reasoning effort; do not substitute the knowledge model for that review.
+
+The principal reviewer verifies possible conflicts with relevant decisions, dependencies and exceptions. Hivex assists that review. Start with local recovery of evidence; use model-assisted review when it adds value, rather than by ceremony. A model's lack of findings is not approval of an implementation.
+
+Resolve findings on their merits. Do not rerun reviewers or modify doctrine merely to obtain approval. Apply existing owner authorization and the repository's Git procedure to completion.
+
+## Maintain knowledge and communicate clearly
+
+Update the document that owns an accepted decision, using new documents only for distinct purposes. Preserve source versions, relevant history and honest uncertainty. Keep Hivex's incremental progress and budget rather than reingesting the whole corpus or resetting work after each round.
+
+Use familiar language and concrete explanations. Briefly explain a technical term when the owner needs it to understand or decide; do not explain every term or change the requested level of detail.