kb: Instructions file for Codex

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 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.