AGENTS.md

Contents

• src/identity/ contains provider-neutral identity, profile, signed-message, entitlement-protocol, and view contracts, with Convex function references and billing transport isolated behind explicit opt-in subpaths.
• src/registry.ts, src/urls.ts, and src/client-configuration.ts contain the frozen v1 registry, the separate current authority registry, and the validated product-binding factory.
• src/oidc-rp.ts, src/oidc-surface-server.ts, src/auth-proxy.ts, src/browser-session.ts, and src/bearer-verifier.ts contain browser and server authentication transports.
• src/convex-browser-auth*.ts, src/receipt-verifier.ts, and src/entitlements.ts contain bounded downstream token, receipt, replay, and authorization checks.
• src/react.tsx, src/profile-form.tsx, src/profile-form.stylex.ts, and src/profile-form.css contain the optional React surface and precompiled presentation entry.
• src/*.test.ts, src/*.test.tsx, and src/*.property.test.ts contain deterministic examples and arbitrary-input laws.
• scripts/ contains the portable inventory validator, ESM build, public-boundary scan, and clean-consumer package smoke.
• .github/workflows/ contains read-only branch validation and checks-gated immutable GitHub Release automation.
• .agents/skills/ contains portable cross-repository KB and phased-execution workflows.
• kb/ contains authored repository rationale, maintained synthesis, and implementation plans.
• WRITING.md and STYLE.md define the internal and public prose contracts.
• package.json, portfolio-inventory.json, tsconfig.json, eslint.config.mjs, and bun.lock contain standalone package, portfolio, and verification configuration.
• README.md, CONTRIBUTING.md, SECURITY.md, and LICENSE contain public usage, project policy, and terms.

Guidelines

• Use Bun 1.3.14. Keep the package source-first, ESM-only, and independently buildable without workspace protocols or private packages.
• Follow WRITING.md for internal prose and STYLE.md for public prose.
• 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 parsers, ordering, transitions, and round trips.
• 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 the optional React profile surface product-neutral. Shared interface composition may layer accessible primitives from @hraness/ui, stable optional composition from @hraness/design-kit, and product-owned layout and content in consumers; add either dependency only for a concrete shared need.
• Compile profile recipes through the pinned public @hraness/ui/stylex-build collector. Keep the compiler development-only, preserve source-first types, and keep every root and non-React entry free of presentation imports. Do not copy compiler internals or add runtime injection.
• Preserve native form controls, semantic hooks, all seven public profile variables, shorthand resets, physical-axis sizing, optional React peers, and profile save/revision behavior. Run canonical artifact, absolute-root determinism, packed-consumer, and real native-form browser checks before release. Browser fixtures exercise the built form and substitute only the external save transport.
• Keep Direct deterministic compositions and adapters development-only and outside every production dependency graph and published export.
• Freeze protocol and package interfaces before parallel lanes begin. Give registries, manifests, lockfiles, generated output, 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 kb/.
• Pin the Result runtime to its exact immutable v0.2.1 commit. Bun 1.3.14 cannot freshly resolve duplicate nested and direct references to the same Git tag, so package smoke must cover a consumer that also pins the public Result tag.
• Keep Accounts as the sole account, client-registration, identity-link, and entitlement authority. A consumer can bind only its registered origin, client ID, callback, and auth mode.
• Keep PeopleBlade current-only, production-only, and email-OTP-only at https://peopleblade.com with client hraness:peopleblade:production:v1. Treat it as a linked product: only a signed one-to-one product-link receipt may bind an existing local subject to a Suite account, and email equality never links or merges accounts.
• Keep issuer, JWKS, resource, protocol version, wire version, client-ID format, algorithms, and security checks derived from closed package data. Never accept them from callers or discovery.
• Preserve authorization code with S256 PKCE, exact state and nonce, issuer and audience checks, encrypted HttpOnly token custody, refresh rotation, receipt validation, replay ordering, and entitlement freshness.
• Parse foreign configuration, JWT claims, profiles, keyrings, receipts, and views from unknown. Fail closed on malformed or stale evidence.
• Keep released identity parsing behavior-compatible for bounded historical evidence. Remove retired client identities, origins, and OAuth registrations from every trust surface, including deprecated registries; preserve the published v1 browser coordination strings, add no new consumer through a compatibility API, and put all new use through the validated factory.
• Deeply freeze every exported registry and security policy value and every returned trust configuration. Never expose mutable canonical state through arrays, nested endpoint objects, keyrings, or provider configuration.
• Keep billing prices, provider lookup keys, registry mutation, reconciliation, email delivery, provider mechanics, project identifiers, credentials, and product reservation policy outside this repository.
• Keep the root and client-configuration entries free of opt-in Convex function-reference and billing-transport dependencies. Keep browser and server entrypoints separate. Browser JSON never receives an OAuth bearer or provider subject, and browser bearers remain memory-only.
• Add a readable deterministic test for every behavior change and a property test for every parser, round trip, ordering law, or arbitrary-input invariant.
• Treat this repository as the complete public project. Public files and Git prose may refer only to its public package, paths, commands, products, and protocol values.
• Treat every packed file as scannable public input. Fail the gate when any file cannot be inspected completely, and run bun run check before handing off a change.

• 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 repository's required validation, review, identity, and rollout gates pass. Do not ask for another confirmation at each delivery step.
• Use the repository's documented delivery workflow and preserve every runtime-enforced approval, branch protection, environment rule, safety policy, and final gate. Ask for user input only when delivery needs a material product decision, missing credentials or authority, an irreversibly destructive action outside task scope, or resolution of a release failure that cannot be handled safely and autonomously.
• Prefer short-lived repository workload identities such as OIDC trusted publishing, GitHub Apps, and narrowly scoped machine identities. Do not add long-lived personal tokens, weaken two-factor authentication, or bypass provider controls to eliminate an interactive prompt. Batch unavoidable human-gated production promotions into intentional stable releases while agents publish validated prerelease or beta channels through workload identities when the repository supports them.
• 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.