AGENTS.md

• Ordinary owned automated browser runs use versioned Chrome for Testing or the browser provisioned for the pinned Playwright version. Reject the installed auto-updating Chrome application, including explicit executable overrides and symlinks; never fall back to it when provisioning is missing. Report the resolved executable and browser version, and close owned contexts and browsers gracefully in cleanup. Attaching to an explicitly authorized user-owned browser is a separate operation: preserve its profile and lifetime. Keep regression checks for browser selection in the existing required checks; see browser automation.
• Never start the system Chrome app directly from an agent shell; use the repository's browser tooling and respect its scheduler and browser custody controls. For owned launches, pass --mute-audio and merge PaintHolding,MacAppCodeSignClone into any existing --disable-features value instead of adding a second switch. Finish owned process, context, and profile cleanup before releasing the browser lane. Never signal another holder or manipulate its lease to obtain a slot.
• The sole native-runtime exception is Slopcamera’s documented signature-verified, version-bound, immutable task-owned Chrome snapshot, never a direct launch of the installed application. Its current integrity-bound launch contract must disable MacAppCodeSignClone; retain vendor identity verification, browser custody, graceful cleanup, and regression checks. Qualify the native fix with live clone-growth and cleanup evidence before activating this exception. It is not an executable override or fallback for ordinary automation; see the native-runtime exception.

Contents

• src/ – the CLI, page-capture runtime, strict data and protocol models, provider-plugin kernel, built-in providers, runtime assets, helpers, and colocated tests.
• src/media/ – the finite-item media acquisition, archive, derivation, transcript, revision, verification, and cancellation runtime.
• src/control/ – the menu-bar control service, approvals, account connections, and the shared-foundation menu adapter.
• skills/ghostget/ – the single public Agent Skill and its focused operational references, including social publishing.
• .agents/skills/ – reusable cross-repository KB and phased-execution workflows; product-specific Ghostget operations remain under skills/ghostget/.
• kb/ – authored repository rationale, evidence, synthesis, and plans.
• WRITING.md and STYLE.md – internal and public prose contracts.
• docs/ – provider-plugin authoring, trust-boundary guidance, the generated assurance.md assurance case, the nightly verification and quarterly claims-review procedure, and the public Puerto Rico rental-listings search contract.
• scripts/ – standalone CLI, plugin lifecycle, clean-consumer package, and formal-verification checks.
• website/ – the dependency-free, statically generated ghostget.com documentation and landing surface; it is excluded from the published package.
• verification/ – the claims register, Quint models, Lean proofs, and checker pins behind docs/assurance.md; it is excluded from the published package.
• .github/workflows/ – read-only Linux and macOS checks, a nightly verification run outside Required whose read-only checks open or update one tracking issue on failure, checks-gated immutable releases, and Dependabot pull-request auto-merge.
• README.md, CONTRIBUTING.md, SECURITY.md, and LICENSE – usage, project policy, security reporting, and terms.
• package.json, bunfig.toml, tsconfig.json, and bun.lock – the standalone Bun package, isolated dependency layout, and frozen dependency graph.

Guidelines

• Use Bun 1.3.14. Complete Required PR CI is the normal final source integration gate for executable and documentation changes, together with relevant focused local checks and independent impact and diff review. Record the repository, reviewed workflow, run and attempt, complete required job union, actual checked commit and tree, PR head, and current base. Revalidate immediately before conditional merge; head or base movement requires matching current-candidate CI. Preserve the executable phase-composition and disjoint source coverage contracts in scripts/ci-pr-gate.test.ts.

• CI covers the complete Linux aggregate and a selected macOS suite. For impacted native behavior outside that suite, run relevant focused macOS checks or add and pass an independently reviewed CI extension. Keep every explicit local, native, coupled-sequence, installation, live, package-release, provider-control, and production acceptance requirement. Diagnose known failures and retain their relevant reproduction and repair checks. Keep bun run check available as the complete local aggregate and use it when coverage or equivalence is uncertain or a required coupled or local reproduction needs the complete sequence. Independently review workflow, discovery, command, deadline, and platform changes against the prior required coverage; edited coverage assertions alone cannot certify a weakened workflow. An older candidate's receipt never qualifies a new integration. CI overrides the shared cancel-in-progress: true rule: it cancels only superseded pull-request runs and gives every main push its own commit-keyed group, because release admission needs a successful push run on the exact tagged commit. A pull-request quint shard narrows Apalache only as decideApalacheScope in scripts/verification-quint-scope.ts decides from its diff against the base: it skips every check when no change can alter a verdict, checks only the changed models when only listed model files change, and checks every model on any other QUINT_APALACHE_SCOPE change or any error. It still typechecks, simulates, and replays every model; main push and nightly runs check every model with Apalache.

• 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 and pair readable regression examples with property tests for general laws.

• 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 replace them with sibling paths, Git submodules, or coordinated main assumptions.

• Extract a shared package only after two concrete consumers need the same stable interface. Keep shared packages product-neutral and keep consumer planning, policy, agent loops, and unrelated consumer UI outside Ghostget's menu-bar control surface.

• For UI work, consume shared design-kit or @hraness/ui primitives only at immutable versions; keep product composition in the owning product and keep website/ dependency-free.

• Freeze shared interfaces before parallel lanes begin. Give public barrels, manifests, lockfiles, generated catalogs, 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/.

• Keep Ghostget a bring-your-own-agent CLI and TypeScript SDK with a menu-bar control surface for accounts, capabilities, permissions, interfaces, approvals, activity, and installation guidance. Do not add a bundled model, planning or tool loop, or agent runtime.

• Keep exactly one public Agent Skill at skills/ghostget/. Bundle product workflows as references and mark repository-maintenance skills under .agents/skills/ internal.

• Keep website/ informational: it may explain and document Ghostget, but must not grow an agent runtime, authenticated product surface, or browser-based substitute for the CLI and SDK.

• Keep the package root import side-effect-free. Importing @hraness/ghostget must not start the CLI, inspect local state, load built-in providers, or access the network.

• Expose bounded semantic provider operations. The separate public web gateway accepts only explicitly policy-admitted HTTPS retrieval URLs through its pinned transport and durable audit boundary. Never add caller-selected provider headers, cookies, selectors, scripts, shell commands, or arbitrary file access.

• Keep media acquisition to one authorized, accessible, finite, non-DRM item. Reject playlists, live streams, affirmative DRM, unsupported authentication, and access-control bypasses. Promote an item only after its inspectable archive, versioned manifest, and SHA-256 records pass complete verification.

• Treat source plugins as trusted in-process code. Treat portable child-process execution as ordinary-failure containment, not a hostile-code sandbox, and require an explicit trust decision for the exact verified bundle.

• Parse every foreign manifest, package, message, plan, receipt, response, and CLI value from unknown; reject extra fields, malformed bounds, ambiguous ownership, and drift.

• Keep installed support discoverable from the validated active catalog. Reject duplicate plugin, route, or operation ownership before a command can use it.

• Keep built-in durable contract hashes versioned and invariant across package layout and execution environment. Derive the exact current source/dependency closure automatically, snapshot it at registry startup, and revalidate it before and after lazy runtime load; do not maintain a manual closure allowlist or ask an end user, provider operator, or maintainer to approve source hashes. Portable-plugin identity must remain bound to its exact verified artifact.

• Bind every authenticated request to one exact account realm, provider target, transport, contract version, and implementation identity. Never silently switch transport.

• Keep mutations behind exact preview, confirmation, durable dispatch, and at-most-once evidence. An observed, subject-bound R3 posts.publish or media.publish may dispatch through the explicit --execute path, which still records the exact immutable plan and single-dispatch lifecycle under the same account permission fence as confirmation; managed Ask or Deny refuses it. By owner decision, deleting the connected X account's own post through x-web content.delete may also skip confirmation, through --execute or the native app host's x.action.commit, but only under an explicit owner Allow for that exact account capability: a managed Allow, or, while operation permissions are unmanaged, a separate owner grant record bound to that capability digest. The owner grants it in GhostGet's fixed native dialog or through a human-gated permission change; the record never turns on management or affects another operation, and a managed Ask or Deny always wins over it. It keeps the exact plan, ownership checks, and single-dispatch lifecycle, rechecks that Allow at dispatch, and refuses any other state. Every other write keeps its confirmation requirement. Never retry or clear an indeterminate dispatch; reconcile it from separately obtained exact evidence.

• Keep raw authenticated traffic, cookies, tokens, profiles, private content, and local paths out of Git, tests, receipts, logs, and diagnostics.

• Pair concrete behavior with deterministic example tests. Add property tests for strict parsers, canonical encodings, identifiers, ordering, round trips, lifecycle transitions, and arbitrary input.

• Model consequential lifecycle workloads as bounded action and fault schedules over the production reducer or port. State safety and conditional progress laws with their environmental assumptions explicitly, keep clocks and randomness injected, and retain fast-check's seed and shrink path. Replay one exact property with GHOSTGET_PROPERTY_SEED, GHOSTGET_PROPERTY_PATH, and an anchored --test-name-pattern, then promote a minimized failure to a named regression. Reducer terminalization from supplied reconciliation evidence is not provider liveness.

• Keep the Bun runner timeout and concurrency policy in package.json; test bodies may own explicit product deadlines and elapsed assertions, but must not call setDefaultTimeout or pass per-test runner timeouts.

• Treat a checker timeout, an inconclusive or unparsed checker result, and a successful compile or typecheck alone as missing evidence; the verification job fails on each.

• Count a Quint model as conformance evidence only after an ITF trace replay test drives production code through its traces; until then it is design evidence. Pair every model with a seeded mutant or pre-fix variant that its checkers must find.

• Promote every recorded shrink or failing seed to a named example test.

• Pin Quint, Apalache, the JDK, elan, and Lean to exact versions, and admit every downloaded checker archive only at its pinned SHA-256.

• When you add or change a rule in an AGENTS.md, update its claims and rule digest in verification/claims.json in the same change. Give every claim its not-verified scope, and regenerate docs/assurance.md.

• Treat this repository as the complete project. Use only its public names, paths, commands, and dependencies in code, tests, documentation, and Git prose.

• Follow docs/publishing.md for canonical GitHub Releases and optional npm mirrors. Starting with v0.16.13, publish the exact five-file archive/packing-receipt/manifest/checksums/provenance contract independently of npm. Keep direct lightweight tags, exact owner/repository/workflow/run reauthorization, complete read-only source and isolated-install acceptance, a separate checkout-free OIDC attestation job, strict signed certificate/source/run/attempt verification, one bounded draft/upload/readback/publish writer, immutable Latest convergence, and current-main release-control closure. Preserve historical versions, tags, and assetless Releases. Keep immutable Releases enabled; an administrator re-reads that setting at setup, after any control change, and during drift recovery, and every Release run's immutable-release readback still fails closed on a mutable Release. Grant no Administration to workflows. The same tag Release run then publishes the identical canonical bytes to npm through the npm-release environment and OIDC trusted publishing: checkout-free, artifact by numeric ID, no contentPolicy declaration, clean npm configuration, exact archive hash, immutable canonical-release readback, idempotent exact-prior-publication recognition, and npm's monotonic default latest guard, followed by read-only registry identity and provenance admission. No dispatch, staged publish, token, or human step follows the tag push; an npm failure is rerun from the same run and never blocks canonical publication. The Release workflow owns only the immutable Release and its npm mirror; it never reads, creates, or updates a website deployment ref, receives no additional credentials, and never waits for Vercel. Merging reviewed main history deploys the site directly. Derive the authoritative run ID from the Release's sampled exact Actions receipt. In the initial verify job's authority resolution, read that Actions run exactly once and bind stable actor and triggering-actor numeric IDs and types, repository identities, workflow ID and path, tag-push event, source SHA, completion, success, and the applicable attempt; do not authorize on mutable logins or the run display name. The canonical download admits a receipt attempt whose conclusion is not success only through that attempt's complete bounded job inventory proving the four canonical jobs succeeded, because a later npm job cannot revoke a published immutable Release; when that attempt attested but did not publish, it also requires a strictly later completed attempt of the same run whose own complete inventory proves all four: the current attempt or, when that attempt did not publish, one of at most three exact intermediate attempts. Manual recovery requires a positive current attempt and admits an unsuccessful latest attempt only through that attempt's own bounded job inventory proving all four or, when that attempt did not publish, through the earlier receipt attempt that the Release body names, whose own bounded inventory must prove all four or, when that receipt attempt attested but did not publish, through one of at most three attempts strictly between it and the latest whose own attempt record binds the exact release actors, repository, workflow ID and path, tag push, tag, SHA, and completion and whose own complete bounded inventory proves all four; a wider gap fails closed, and the mutable body only selects which inventories to read. The GitHub publisher downloads the attested artifact only by numeric artifact ID behind an exact-identity guard, so a failed-jobs rerun publishes the exact bytes and signed attempt its run already attested, never another run's or a later attempt's. Later strict by-tag Release reads revalidate the sampled exact source receipt, tag, Latest projection, Release ID and publication time, source SHA, and workflow source using the carried run ID without rereading Actions. Carry that run ID through every later authority and release-outcome check. Grant actions: read only to the initial verify job.

• Treat the Release display title, Actions workflow-run display name, actor logins, and receipt body as mutable presentation or control-plane data. Validate the sampled exact source receipt on every accepted Release read; stable numeric identities and types, the protected tag, and immutable Release coordinates remain authority.

• Keep the npm-release environment fail closed: administrator bypass disabled, no reviewers, no secrets, sole protection rule branch_policy, and the single custom deployment policy tag v* with no branch admitted. Only publish_npm may reference it or mint an npm OIDC token; the npm trusted publisher names release.yml and this environment. Any drift blocks npm publication; do not weaken the environment to recover a run.

• At setup, after any control change, and during drift recovery, a signed-in administrator must freshly prove immutable Releases enabled and read back all four active repository tag rulesets. They form two split pairs: one pair targets only refs/tags/v*, and the other targets only refs/tags/desktop-v*-macos-arm64. In each pair, the creation-only ruleset must have exact rule creation; its always-bypass actors are exactly User 894119 plus, for the stable v* pair only, the hraness-release-tagger App 5164973 Integration; it must never authorize update or deletion. The immutable ruleset must have no bypass actors and exact deletion plus update rules; it must never authorize creation. Any other active tag ruleset is drift. Current rulesets 22311815 / Release tag creation and 19989752 / Immutable version tags for stable tags, and 22960902 / Desktop release tag creation and 22960911 / Immutable desktop release tags for desktop tags, are retained evidence; their split semantics, not their IDs or names, are authority. Never give GitHub Actions or any other Integration a release-tag bypass. The Release workflow must not receive Administration permission or call ruleset endpoints. Checked-in CODEOWNERS supplies ownership and notification only. Protect-main has no bypass actors and retains pull-request admission plus the exact Required CI check. Keep its approval minimum at zero and require_code_owner_review=false until a second eligible independent code owner exists. Keep Vercel's Production Branch on main; keep exact project prj_TZbDZ38ABPan158IqnczgsuTu6Ue, team team_UAd1iD2XogJlbFg4h14mRaPM, GitHub repository ID 1316443113, link.productionBranch=main, autoExposeSystemEnvs=true, and persistent autoAssignCustomDomains=true. autoAssignCustomDomains is never a release-time toggle. Merges to main deploy the production site directly through the Vercel Git integration; pull requests produce previews, never production. Staged recovery pins one exact uncontested deployment and uses one owner-authorized vercel promote <exact-id-or-url> followed by complete readback.

• .github/workflows/auto-tag.yml releases a merged version bump with no human step: once that commit's own main push CI run succeeds, it creates the exact direct lightweight v<version> tag on that commit through the hraness-release-tagger App, and never moves or replaces an existing tag. An owner release request authorizes the agent to create and push the exact admitted lightweight tag through the existing owner User 894119 session when auto-tag did not, without a second conversational approval. Verify that signed-in identity and its administrator access to this repository before use. Push the tag only after the tagged commit's own main push CI run has completed successfully, because Release admission reads that run once and never waits. Preserve all source, tag, immutable-release, and delivery gates. Missing access, control drift, and provider or runtime denials still block the affected action. This authorization grants no workflow or Integration identity additional permissions or tag bypass beyond the hraness-release-tagger App's stable-tag creation bypass.

• Bind every Release run at entry to a protected tag-push event and embedded sender owned by User 894119 or hraness-release-tagger[bot] Bot 337004703 (matching the run actor) in public Ghostget repository ID 1316443113. Before the sole write-capable job checks out source, use only actions:read to bind the exact current attempt—including both actor and triggering_actor—to Release workflow ID 323493609, its exact path, the verified direct tag object, and current-main ancestry; reject delegated reruns.

• Before publish_npm sets up npm or mints OIDC, bind its current attempt—including both actor and triggering_actor—to owner User 894119 or hraness-release-tagger[bot] Bot 337004703, Release workflow ID 323493609, the protected tag ref, the verified source SHA, and public Ghostget repository ID 1316443113; delegated reruns must fail closed. Download the attested canonical artifact only by numeric artifact ID and bind all five files to the verify hashes and bundle digest. Independently parse the packed manifest inside that checkout-free job and permit no top-level tag plus only publishConfig.access=public and the canonical npm registry—reject scoped registries, proxies, credentials, and all other publication settings. Admit only an absent registry version newer than public latest, or the same version already public with the exact canonical integrity (skip without a second write); never overwrite a published version. Scrub ambient tag variables and project, user, and global npm configuration; prove pinned npm's clean default tag is latest; re-read the immutable canonical Release immediately before npm publish without --tag. Require the exact public registry package and its npm provenance to match the canonical archive in admit_npm before advertising registry availability; canonical publication is independent of npm latest.

• The @hraness/ghostget npm coordinate is published as ordinary software by owner decision on 2026-09-10: the package carries no contentPolicy declaration and no DISCLOSURE file, matching the other Hraness listings. Ghostget's page capture, media archiving, encrypted reads, and typed provider operations behind exact preview and explicit confirmation are agent tooling, not security-research or obfuscation software. The first publication of the new coordinate was one owner-authenticated publish of the exact canonical archive; every later version publishes automatically from the tag Release workflow's trusted publisher with provenance, unified with the other Hraness packages. Do not add a content-policy declaration or a staged-publish requirement back without an owner decision.

• A matching archive hash is insufficient release authority. Before GitHub mutation, require successful cryptographic verification of the canonical attestation bundle for all four subjects, exact signed certificate repository/source/workflow/run/attempt identity, and safe archive/receipt inspection. Promotion CI independently verifies the published canonical archive and original successful Release run. The Vercel build checks immutable metadata, bot/source receipt, exact five descriptors, manifest/archive digests, local HEAD/tag, and Latest; it trusts authenticated canonical workflow admission and does not claim local Sigstore verification. Historical assetless Releases retain their prior npm manifest admission.

• Public copy (websites, READMEs, docs, package and GitHub descriptions, CLI help, llms.txt, generated pages) follows STYLE.md, synced from hraness/.github. Text a model writes for publication also follows GENERATION_STYLE.md.
• The delivery vocabulary in this file (admission, qualification, custody, receipt, bounded, lane, gate, surface, projection) is internal. Translate it into what the reader gets.
• Take one-line product and sibling descriptions from the portfolio registry and versions from the release record. Tests pin facts, not prose.
• Run bun run check:copy before handoff when the repository has it.

• Essays and blog posts follow the essay addendum in GENERATION_STYLE.md and ARTICLE_COPY.md in @hraness/design-kit. The byline is “Hraness”, every post shows the provenance note naming its recorded reviewer, and no AI-drafted post is credited to a person unless that person rewrites and adopts it.
• Take product names, one-line descriptions, addresses, status labels, and relations from the portfolio facts in @hraness/design-kit. Render versions from the release record (package.json, a published-release file), never typed by hand.
• Write a “How X uses Y” post only for a registered relation that has a description. Change the relation and its post in the same change. Link between products only along registered relations, and between a technique post and product posts about the same technique.
• Every post has a review record: reader job, non-obvious answer, sources with the date checked, owner, reviewer identity, reviewer type (ai or human), a score out of 12, and a reassessOn date 28 to 56 days after review. The reviewer is independent of the run or person that drafted the post. An AI reviewer is recorded and shown as AI; humanReview stays null unless a person reviewed the post.
• A new post starts out of search indexes, sitemaps, and feeds. It becomes indexable only when its review record is complete, scores at least 9 of 12 with no zero score, and the page shows the provenance note.
• When a product is renamed or a relation changes, update the post bodies that mention it in the same change.

• Launch posts, their social posts, product mockups, and launch films follow the launch beats and social posts addendum in GENERATION_STYLE.md and the beats shape under “Introducing a product” in ARTICLE_COPY.md in @hraness/design-kit. Channel limits are in the launch posts section of MESSAGING.md.
• Build them with the product-launch agent skill, the ./mockups and ./launch exports of @hraness/design-kit, and slopcamera html init --template launch-film.
• Take every number in a beat, social post, film caption, or store listing from the product's launch facts module, and the status from the release record. Keep mockup accessible descriptions accurate; visible captions are optional and must add useful context.
• The social kit emits posts for X, Bluesky, Threads, and LinkedIn, and a fact sheet for the Show HN post and the Product Hunt first comment. A person writes those two.

• 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.
• Prefer agentic service provisioning for new infrastructure. Check Vercel Marketplace for a native product that can provision the required resource first; use Stripe Projects as a supported alternative when it better covers the service or the Marketplace route only connects an existing account. Verify the current catalog, account, region, plan, recurring cost and resource capabilities before selecting a route. Prefer supported provider CLIs or APIs over browser-only setup when neither catalog fits, and explain the concrete exception. Reuse existing owner-controlled resources where appropriate; this preference alone does not authorize migrations, duplicate accounts, paid upgrades or wider access. Continue setup already authorized by the task and budget without duplicate confirmation. Keep provider credentials and generated environment files private, complete required interactive authentication, and verify deployment, persistence and recovery separately from successful provisioning.
• 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. Releases and deployments run without a human in the loop: do not add required reviewers, manual approval environments, or wait timers to release or deployment paths, and remove any you find through a reviewed change. Keep account two-factor authentication, and do not add long-lived personal tokens.
• Main delivery is unattended. Open the pull request and enable auto-merge in the same breath (gh pr merge --auto --squash <number>), then move on; the required Required check is the reviewer. Until a repository's ruleset requires a check, --auto merges immediately, so wait for green checks there before merging. Never request a human reviewer or add required approvals, code owners, required conversation resolution, merge queues, manual-approval environments, or wait timers, and remove any you find with scripts/apply-delivery-policy.py from hraness/.github rather than by hand. Required checks run on the pull request head and are not re-required after main moves, so auto-merge never stalls behind another merge; main reruns the same gate after integration, and a red main is fixed forward by the next change. Repositories without CI use direct pushes to main.
• 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 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.

• CI exists to admit a change in minutes, not to perform a ceremony. Every workflow declares concurrency: { group: <name>-${{ github.ref }}, cancel-in-progress: true } (release and deploy workflows set cancel-in-progress: false), a timeout-minutes on every job, and permissions: contents: read at the top with job-level widening only where needed.
• One job named Required closes every check workflow: if: always(), needs: every blocking job, and a single step that fails unless each needs.<job>.result == 'success', or skipped because the change filter below reported its inputs unchanged. Branch policy requires only Required (plus a provider's own automated admission status when the product depends on it). Never make CodeQL, scheduled, or advisory jobs required.
• Cache by lockfile hash and restore before install: Swatinem/rust-cache@v2 (with save-if: ${{ github.ref == 'refs/heads/main' }}) for Cargo, oven-sh/setup-bun@v2 plus actions/cache on ~/.bun/install/cache for Bun, actions/setup-node cache or actions/cache for npm/pnpm, actions/setup-python with cache: pip or astral-sh/setup-uv with cache for Python. Playwright browsers are cached under ~/.cache/ms-playwright keyed by the Playwright version.
• Rust: install the pinned toolchain with dtolnay/rust-toolchain (rustup toolchain install at most once per job, --profile minimal), set CARGO_INCREMENTAL: 0, CARGO_TERM_COLOR: always, CARGO_NET_RETRY: 10, RUSTFLAGS: -D warnings and RUST_BACKTRACE: short at workflow level, use cargo nextest or one cargo test --workspace --locked after a shared cargo build --all-targets --locked, run clippy and fmt once on Linux only, install tools with taiki-e/install-action or cargo-binstall instead of cargo install, and build release binaries in one job whose artifact every later job reuses. Never build the same crate twice in one workflow.
• Run the matrix Linux-first. A macOS or Windows job exists only when the product ships a native surface for that OS, runs the OS-specific tests only, and is never the only place a generic check runs. Split long serial script lists into parallel jobs that share one build artifact instead of one job that runs for twenty minutes.
• Skip work that cannot change the result inside the workflow: a change-detection job runs dorny/paths-filter@v4 (it needs job permission pull-requests: read, and predicate-quantifier: some-with-excludes needs v4), and jobs whose inputs did not change skip through job-level if:. Never put paths, paths-ignore, or branches-ignore on the pull_request trigger of the workflow that produces Required: a skipped workflow never reports Required, and the pull request can never merge. Every uses: pins a major tag or a SHA with a version comment, and Dependabot keeps github-actions current weekly with auto-merge.
• Measure before and after: a CI change records the previous and new median wall time of the slowest workflow in its pull request body. Regressions that add more than a minute to Required are reverted forward the same day.

• GitHub Release pages follow RELEASES.md in hraness/.github: the title is the registry product name and the tag, and the body is a summary, ## Changes, ## Install, ## Verify, then the repository's identity record as a trailing HTML comment.
• The summary and changes come from the version's section of CHANGELOG.md in the tagged commit. Write that section in the version bump pull request. The release workflow copies it, generates Install and Verify from the release record, fails when the section is missing or empty, and never uses GitHub's generated notes.

• costs.json at the repository root is the checked registry of every product data surface: store, kind (authoritative | derived | telemetry | served), retention class (ephemeral | ttl:<ISO-8601> | account | tombstone | persistent), owner module, and budget. A new table, bucket, stream, dynamic route, blob, or provider meter fails check:cost-surfaces until it registers.
• Bound every input before storage or provider I/O: request bytes, row counts, page sizes, batch sizes, retry counts, and event payloads. Unbounded input is a contract violation.
• No writes on read paths. Reads may cache; they never mutate. Hand a read path a read capability with no writer members, such as AuthIncarnationReader, not an environment that reaches writers. The control snapshot that ghostget status and ghostget tui --snapshot read, and its account and permission listings, take no admission and create no state; account saves, the control-service startup backfill, and admitted execution paths create auth incarnations. The auth checks of a cache read, a live-read publication, and an omni materialization read the incarnation through AuthIncarnationReader, so a missing incarnation reads as changed and nothing is created. Read-path preparation (capability and omni reads, cache-only invocations, and control-plane inspection), confirmation preparation, and the operation-permission account identity bind the current incarnation the same way: they read it through AuthIncarnationReader, fail closed when it is missing, and create none. Only explicit invocation preparation, an admitted execution path, may create a missing incarnation. invoke --projection-identity-only is the SDK's identity preflight for a live invoke, so it is execution preparation and remains an admitted creator; invoke --cache-only is a read path and creates none. Two bounded exemptions (D14). First, a read-projection cache read may create and release its own admission claim and remove a claim whose recorded owner is proven dead, because it must exclude a concurrent projection transition; the claim is coordination state with no data. Second, a cache read may create the projection encryption key and its store-key marker when they are absent, because a miss returns the query key that this encryption key derives; each is created at most once per state home and holds no user data. The exemptions cover nothing else.
• repair-signals is a bounded derived diagnostic cache, not execution authority or an audit log. Keep failed-invocation signals free of account identifiers, inputs, private content, and raw errors. Catalog/check/cache-only/identity-only inspection must not record demand. Repair handoffs never authorize capture, retry, activation, or publication; changed contracts remain unverified candidates.
• Derived state is rebuildable and lives in the cheapest tier that can serve it. Only authoritative state pays for transactional storage.
• Every mutation carries an idempotency key; a retried write never double-charges storage, quota, or provider spend.
• Analytics and metering events come from a checked allowlist with a byte ceiling per event.
• Content bytes live in the content store; the control plane keeps references and metadata only.
• Run bun run check:cost-surfaces before handoff whenever a data surface changes.

• Prefer the globally installed algal-* skills for bounded git state, diffs, repository survey/search, test and release gates, CI polling, and web fetches instead of repeated raw tool output.
• At session start, if the algal skill is unavailable, install the current skill pack for Claude Code, Codex, and Devin for Terminal with bunx skills add 0thernet/algal-skills --global --agent claude-code codex devin --skill '*' --copy --yes.
• Confirm installation with bunx skills list --global. If Bun or network access is unavailable, continue with repository-native tools instead of blocking delivery.
• Treat ALGAL receipts as execution evidence, not provider attestation, and preserve the repository's normal verification and release gates.