AGENTS.md git:20260909.d280115A

Immutable. This exact content is served forever at /api/v1/blob/dfd1d0cbeb569a87.

<!-- kb:context scopes/repository--cdb4ee2aea69 -->
# Contents

- `src/` – deterministic Markdown graph and attachment analysis, typed metadata and exact repository-scope queries, local hybrid retrieval, bounded Git provenance, code-mode sessions and DAG workflows, frozen-corpus evaluation authoring and execution, safe single-note authoring, percolation, repository-memory routing and audits, the advisory source inbox, structural navigation, initialization, CLI, capture, URL intelligence, and diagnostic code with colocated tests.
- `src/workflows/` – reusable code-mode decision-context, change-explanation, and plan-radar workflows with bounded parallel execution.
- `dist/` – committed Bun-targeted ESM entrypoints plus the compiled Defuddle worker.
- `skills/kb/` – the single public Agent Skill for querying, capturing into, planning in, percolating, refreshing, and validating a hraness/kb vault, with focused workflow references loaded on demand.
- `.agents/skills/` – internal plan authoring, phased execution, implementation, and independent review workflows.
- `kb/` – this source repository's authored rationale, maintained synthesis, and implementation plans; it is separate from the package's graph implementation and fixtures.
- `WRITING.md` and `STYLE.md` – internal and public prose contracts.
- `docs/` – design, capture, and agent-workflow documentation.
- `.github/workflows/` – read-only branch validation, canonical attested immutable GitHub Releases and optional stage-only npm mirrors.
- `portfolio-inventory.json`, `scripts/check-portfolio-inventory.ts`, and `scripts/check-installed-command-docs.ts` – canonical public package inventory and standalone public-command consistency gates.
- `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, and `LICENSE` – public usage, project policy, threat model, and terms.
- `package.json`, `tsconfig.json`, and `bun.lock` – standalone package and frozen verification configuration.

# Guidelines

- Use Bun 1.3.14 for repository commands and keep the authored Markdown compatible with Obsidian and ordinary text tooling.
- Follow `WRITING.md` for internal prose and `STYLE.md` for public prose.
- Follow the shared [Hraness README guidelines](https://github.com/hraness/.github/blob/main/README_GUIDELINES.md) for the README trust path and its website projection. Adapt the structure to KB's local-data and Agent Skill boundaries instead of copying a fixed template.
- Apply unreasonably robust programming when agent work is cheap. Model invalid states out of existence, parse every foreign value from `unknown`, and pair readable deterministic regressions with property tests for parsing, resolution, ordering, path confinement, and round trips.
- Treat a stable package or release version as exactly three canonical decimal components in the inclusive range `0..Number.MAX_SAFE_INTEGER`. Reject larger components at selection, package preparation, artifact verification, attestation verification, and release ordering boundaries.
- Deliver changes to `main` through a current-head pull request. Keep the stable `Required` CI job green, resolve every review thread, and serialize merges. Human approval stays optional while one regular maintainer would otherwise self-review. Never force-push or bypass the gate.
- Pin Hraness dependencies to reviewed immutable releases or full commits. Never connect repositories through sibling paths, Git submodules, or coordinated `main` assumptions; upgrade each consumer independently.
- Extract a shared package only after two concrete consumers require the same stable interface. Keep every shared package product-neutral and free of product imports.
- Keep this package headless. It must not depend on `@hraness/ui` or `@hraness/design-kit`; consumers own any accessible primitives, stable visual composition, product layout, and content layered over KB data.
- Keep Direct deterministic compositions and adapters development-only and outside every production dependency graph, packed file set, and public export.
- Freeze public CLI, metadata, graph, and workflow interfaces before parallel lanes begin. Give package manifests, lockfiles, committed `dist/`, skill mirrors, and other convergence surfaces one owner while lanes edit disjoint paths.
- Keep mandatory rules in the closest `AGENTS.md`, current procedures in `docs/`, executable contracts in types and tests, and pull-based rationale, evidence, synthesis, and plans in this repository's `kb/` vault.
- Treat this repository as the complete project. Files and Git prose may use only its public names, paths, commands, and examples; do not refer to or infer a non-public source repository.
- Keep Markdown authoritative and graph maintenance deterministic and local-first. Derive focused metadata, backlink, traversal, and percolation views directly from the current files; never commit a second graph database, event log, or generated fact file.
- Keep concepts as ordinary `type: concept` notes and source-owned typed relationships as compact frontmatter. Never write reciprocal, inferred, transitive, or similarity-derived edges into notes.
- Keep QMD state optional, local, dynamically loaded, and rebuildable from Markdown. The default hybrid path may combine local full-text and vector ranks, but query expansion and reranking remain opt-in costs. Join every match to current authored metadata and graph state.
- Pin required QMD compatibility behavior to an immutable public Hraness fork commit. Verify the installed bytes in focused tests and update or return to upstream only when equivalent store-local model behavior is published.
- Keep exact matches and QMD results inspectable as separate retrieval evidence. Return graph neighbors and Git history as context and provenance, not silent relevance boosts, authored links, or inferred facts.
- Keep `@hraness/kb/evaluation-builder` as the cohesive public boundary for frozen-corpus authoring, evidence compilation, implementation commitments, seal validation, and v2 evaluation mechanics. Keep repository-specific corpora, configurations, retriever descriptors, and promotion expectations in the consumer.
- Treat a code-mode session as a read-only snapshot that shares one vault scan. Reopen it after Markdown changes. Validate workflow DAGs before execution, cap nodes and concurrency, serialize QMD nodes, and bound Git workers below the global limit.
- Keep bundled workflows free of hidden writes and process-global state. Require explicit vault and repository inputs and return structured results that agents can inspect or compose.
- Keep `AGENTS.md` normative and always loaded for ownership, prohibitions, required commands, invariants, and gates. Optional `type: agent-context` hubs under `scopes/` are pull-based rationale, history, examples, evidence, and links; they cannot override a guide or become the sole home of a load-bearing edit rule.
- Derive every scope-hub identity from the full exact repository-relative directory scope, with `.` for the root, and require one reciprocal `kb:context` marker before the mapped guide's headings. Unmapped guides remain valid; moving a scope changes identity.
- Confine repository-context lookup and agent-guide audits to the selected repository. Require real scope directories and regular guide files, reject collisions and symlinked mappings, skip generated or vendor directories, and never follow symbolic-link directories.
- Treat `repository_scopes` as exact case-sensitive authored paths. Match directories lexically to descendants, match files only to themselves, report existence separately from validity, and never infer or rewrite scopes from Git history.
- Treat agent-guide length, long-bullet, inherited-chain, and exact-duplicate audit findings as deterministic advisories rather than correctness. Keep required edit-time rules in the guide even when they exceed a suggested budget.
- Derive backlinks from explicit wikilinks and typed relationships. Keep both authored and managed front doors navigational, never inject reciprocal links, and leave title, alias, inbox, and percolation candidates advisory until their evidence is reviewed.
- Keep parallel note edits sharded by source file. Serialize same-note local writers, make replacements atomic and revision-checked, let edit lanes check graph policy without refreshing a catalog, and reserve the single managed catalog write for integration. An authored catalog mode must never rewrite the front door.
- Restrict generated edits to marked, tool-owned regions; preserve concurrent authored changes when refreshing; and fail closed on malformed markers, unsafe paths, or invalid local attachments.
- Treat capture inputs and outputs as hostile. Keep network, browser, subprocess, byte, item, depth, path, credential, and terminal boundaries bounded and covered by named regressions.
- Keep `skills/kb/` as the only public Agent Skill and byte-identical between the repository and packed package. It remains inert after installation and must be usable from `node_modules/@hraness/kb/skills/kb/` without a source checkout. Mark repository-only skills with supported internal metadata so public discovery omits them.
- Keep Archive.today-family discovery read-only and exactly bound to the requested source URL at every redirect hop. Preserve useful structured provider results ahead of archive fallback, and keep search-derived metadata in a separately owned sidecar with categorical provenance and failure states. Resolve fixed search-engine hosts through the public-network boundary, disable redirects, serialize engines, and confine the helper's process memory.
- Keep security-sensitive runtime forks pinned to immutable commits and exercise their behavior through the standalone install gate.
- Keep `portfolio-inventory.json` byte-canonical and consistent with the public package identity, version, repository, direct `@hraness/*` dependency edges, and Hraness-owned dependencies pinned by exact immutable GitHub specifiers.
- Pair concrete behavior tests with property tests for parsing, resolution, ordering, path confinement, and round-trip laws.
- Run `bun test src/benchmark.test.ts src/evaluation.test.ts src/evaluation-kb.test.ts src/search.test.ts src/sdk.test.ts` when changing rank fusion, retrieval defaults, frozen-corpus execution, or built-in evaluation adapters. The six-case synthetic rank-fusion fixture is a deterministic regression, not a retrieval-quality or performance benchmark. Keep real-corpus manifests versioned, judgments independent of rankings, raw lane evidence intact, and performance claims tied to named hardware and measured runs. Run `bun run check` before handing off a change; it must leave committed `dist/` and `bun.lock` unchanged.
- Follow `docs/publishing.md` for canonical GitHub Releases and optional npm mirrors. Keep the package name, CLI names, exports, root `DISCLOSURE`, and `contentPolicy.class=dual-use`. Canonical publication must not depend on npm availability, npm `latest`, or staged promotion. Preserve old npm versions and immutable tags.
- Use two exact active rulesets matching `refs/tags/v*`: **Immutable version tags** restricts update and deletion with an empty bypass list; **Release tag creation** restricts creation and has owner `User` ID `894119` as its sole always-bypass actor. Never grant generic GitHub Actions integration ID `15368`, an administrator, repository role, team, or other integration this bypass. Never combine creation with update/delete, move a tag, or create probe tags. Create the exact annotated stable package tag on reviewed `main` after its required checks pass. The protected tag workflow must bind the actor and event sender to owner `User` ID `894119` and public repository ID `1308971873` before checkout.
- Run release verifiers from exact current `main`, build and smoke exact tagged source, and revalidate the complete verifier closure immediately before each release mutation. Keep source verification read-only and isolated from attestation credentials. The source-free attestation job must reauthorize the exact run/attempt and both actors before requesting credentials, bind the handoff to verified hashes, and sign the archive, packing receipt, manifest, and checksums. Require cryptographically verified hosted-run certificate identity, exact repository/owner IDs, tagged source/workflow/ref, run/attempt, and subject hashes before release publication or npm mirroring.
- Publish exactly the canonical tarball, `npm-pack.json`, strict `release-manifest.json`, `SHA256SUMS`, and `provenance.jsonl`. Verify exact Actions-bot creator ID `41898282`, title/body/source/run, complete asset names/sizes/digests, immutable publication, stable ordering, and GitHub Latest. Prepare a draft, upload only missing matching files, then publish it; never overwrite assets, delete/recreate a release, or relabel an earlier attempt's provenance. A conflicting or cross-attempt partial release fails closed for exact reconciliation. No second stable release may start before the first completes.
- Trust only `.github/workflows/npm-stage.yml` with `npm stage publish` permission bound to the exact `npm-stage` environment. Keep that environment restricted solely to selected default branch `main`, administrator bypass disabled, no required deployment reviewers, and no secrets. Optional mirrors are intentional current-main dispatches; only boolean `publish_to_npm=true` may admit the source-free staging job with `actions: read`, `contents: read`, and `id-token: write`. Reauthorize the current run attempt, both owner actors, active workflow, public repository, main, and verified source. Download and verify the exact canonical GitHub artifact rather than rebuilding mirror bytes.
- Preserve npm's safe packed-configuration, clean default `latest`, strictly increasing version, and durable unresolved-intent guards. Reject top-level `tag` and noncanonical `publishConfig`. Record a successful intent step immediately before mutation, inspect terminal writes before job names, require its immediately preceding safe positive Actions step number, and scan every retained attempt. npm's short-lived trust assertion cannot list stages. Resolve provider state out of band; exceptional `resolved_stage_version` clears only its exact rejected stage after provider resolution. Prior npm latest must retain its annotated tag, immutable Actions-authored release, and main ancestry; GitHub Latest may be newer. Accept zero-asset prior releases only for the enumerated, source-bound legacy tags `v0.19.0`, `v0.19.1`, and `v0.19.2`; other prior versions require the canonical five assets and must be at least `0.19.4`. Disallow traditional publishing tokens. Public promotion remains human-gated by two-factor authentication until npm approves a classification change; do not claim this workflow prevents out-of-band stages.

<!-- hra-local-efficiency:start -->
- Treat the user's request to change this repository as standing authorization for routine task-owned commits, pushes, pull requests, merges, releases, deployments, and production verification after the gates applicable to that action pass. Do not ask for duplicate confirmation. Build confidence through relevant automated checks, bounded diagnostics, and independent review, not another human approval. Passing checks does not expand task scope or authority.
- Separate artifact admission from live qualification and operational activation. Use applicable automated source, security, package/install, and provenance evidence for artifact admission; live provider qualification is not a universal publication prerequisite. Preserve explicit live acceptance criteria and require relevant live evidence for claims that depend on it. If publication or an artifact's install, upgrade, or default-use path activates risky unqualified behavior, keep that behavior guarded or disabled, or obtain bounded relevant evidence before shipping or activation.
- Use the repository's documented delivery workflow and preserve the identity, target, capacity, migration, and recovery guards applicable to operational activation. Replace an obsolete gate through a reviewed source and policy change with corresponding tests, never an ad hoc skip. Preserve every runtime-enforced approval, access control, branch protection, environment rule, safety policy, and required final gate. Ask for user input only when delivery needs a material product decision, missing credentials or authority, unavoidable interactive authentication, an irreversibly destructive action outside task scope, or resolution of a failure that cannot be handled safely and autonomously.
- Preserve production and user data throughout delivery. Inspect the exact account, environment, deployment, and data target before writes. For data changes, inspect a dry run or equivalent migration plan and validate the recovery path before any effect that could lose or corrupt data. Prefer additive, backward-compatible migrations and bounded batches. Record mutation intent, use idempotency or conditional writes, and reconcile uncertain results before retrying. Verify deployed identity, health, and relevant data invariants after delivery. Routine delivery never authorizes resetting, truncating, dropping, or overwriting user data; stop the unsafe operation if preservation or recovery cannot be established.
- Prefer short-lived repository workload identities such as OIDC trusted publishing, GitHub Apps, and narrowly scoped machine identities. Use unattended stable publication and production promotion when supported by the provider and repository. Establish supported machine authority once and verify it with a non-publishing preflight where available; routine releases should not require recurring interactive authentication or conversational approval. Retain account two-factor authentication and provider controls, including required authentication for approval of an exact staged artifact; do not add long-lived personal tokens to eliminate an interactive prompt.
- Keep delivery gates proportional to the failure they prevent. Prefer required checks on the current integration candidate, independent agent review, and atomic or conditional integration. Add a merge queue or another approval stage only for a demonstrated coordination or safety need. Replace redundant queues, serial waits, and duplicate checks through reviewed policy changes while retaining evidence for the integrated result.
- Preserve useful reasoning fan-out, but avoid unnecessary checkout fan-out. Prefer subagents in the current task for bounded research, review, diagnosis, and focused checks when they can safely share one working tree; create a separate task or worktree only for independently deliverable divergent edits, an isolated verification tree, or a different execution environment.
- Give each expensive focused validation command and external wait one owner. The integration owner reviews that evidence and runs the repository-required aggregate or final gate once after convergence. Reuse evidence only for the exact Git tree, command, lockfiles, toolchain, relevant environment, and validity period, and never to skip a required final integration, merge, release, deployment, or production-verification gate.
- On Hraness development machines, use `$hra-local-efficiency` and the installed host scheduler for heavyweight top-level commands when available. Keep ordinary work in the compute lane; give authenticated browser/dev-server/Chromium work one `browser-auth` owner and Mac-only validation one `mac-native` owner.
- When a CI or policy gate scans complete Git history, check out the exact governed SHA and fetch only the fully qualified governed refs before scanning. Preserve the complete-history gate and reject unexpected refs instead of importing unrelated concurrent heads.
- At closeout, record applicable branch, PR, check, merge, release, deployment, and production evidence. Archive only conclusively finished tasks, never from silence alone, and reclaim only freshly revalidated clean merged worktrees through the guarded exact-path flow.
<!-- hra-local-efficiency:end -->