AGENTS.md · diff
git:20260905.4402562 to git:20260905.7aa6da5
11 added, 3 removed. Audit A to A.
<!-- kb:context scopes/repository--cdb4ee2aea69 -->
# 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.
- `skills/wrench/` – 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 Wrench operations remain under `skills/wrench/`.
- `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, and the public Puerto Rico rental-listings search contract.
- `scripts/` – standalone CLI, plugin lifecycle, and clean-consumer package verification.
- `website/` – the dependency-free, statically generated `wrench.rip` documentation and landing surface; it is excluded from the published package.
- `.github/workflows/` – read-only Linux and macOS checks plus checks-gated immutable releases and release-only website production promotion.
- `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 and run `bun run check` before handing off a change.
- 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 product UI outside Wrench.
- 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 Wrench a bring-your-own-agent CLI and TypeScript SDK. Do not add a bundled model, planning or tool loop, agent runtime, application UI, native app, or app template; consumers own those layers.
- Keep exactly one public Agent Skill at `skills/wrench/`. Bundle product workflows as references and mark repository-maintenance skills under `.agents/skills/` internal.
- Keep `website/` informational: it may explain and document Wrench, 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/wrench` must not start the CLI, inspect local state, load built-in providers, or access the network.
- Expose bounded semantic operations, never caller-selected requests, endpoints, 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. 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 `WRENCH_PROPERTY_SEED`, `WRENCH_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 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 the interactive npm bootstrap and later stage-only trusted publishing. A monotonically greater stable version reaching `main` must automatically enter the exact staging pipeline; an unchanged version must no-op, and manual dispatch remains the current-`main` recovery path. Keep the minimal OIDC job behind the main-only `npm-stage` environment with no required GitHub deployment reviewers, and bind npm trust to that exact environment and stage-only action. CI must stage automatically after verification. Bind the staged artifact to source commit `C`; protected `main` may advance only by proven linear ancestry while the long gate runs, and the terminal job must observe two equal combined main-plus-tag-absence advertisements around that ancestry proof immediately before staging. Human inspection and two-factor approval of the npm stage remain mandatory before the version becomes public. Verify that exact public artifact before creating its tag. Treat a raw `v*` tag as a release request, not a completed release; completed immutable Releases define ordering. Keep the requested tag as a direct lightweight tag on package commit `C`, with protected linear `main` equal to or descended from `C`; the read-only release gate must rebuild and compare the public npm tarball before its sole `contents: write` job creates or verifies the immutable Latest GitHub Release with `make_latest=legacy`. Immediately before tag dispatch, require signed-in administrator readback that immutable Releases are enabled; do not grant Administration to the workflow, and treat the residual setting-toggle window as a trusted control-plane boundary. The Release workflow must never read, create, or update `website-production`, receive the release App key, or wait for Vercel. Load the separate production-promotion workflow from reviewed main source `W`; prove release `C<=W<=M` for protected current main `M`, allowing only linear descendant movement after dispatch; bind its automatic `workflow_run` to Wrench repository ID `1316443113` and Release workflow ID `323493609` plus the exact path, tag-push event, first attempt, success, head repository, tag, and peeled immutable release SHA. Manual recovery on that same main-origin workflow accepts an untrusted stable-tag input and no upstream SHA. Record the complete bounded Vercel Production baseline before any key-environment wait. An already-exact ref must take a separate read-only path with no environment, App variable, private key, token mint, or Git push.
- - A required fast-forward must enter `production-ref-writer-key` with `deployment: false`, reviewer `0thernet`, `prevent_self_review=false`, and no administrator bypass; revalidate source and immutable release authority after approval; and authenticate one private Hraness App. The App registration and every minted token must close to exactly `metadata:read`, `contents:write`, and `workflows:write`, with no Administration or other permission. Workflows write is required because an admitted fast-forward may introduce reviewed `.github/workflows` changes. Runtime must request and validate a token narrowed to Wrench repository ID `1316443113`; privileged setup must separately enumerate the installation-wide selected-repository set and prove it contains only Wrench before key admission. The writer's retained admission proof is workflow run `33691443614`: an ordinary `P` to `C` update was denied, the dedicated App performed the only leased fast-forward, the stale lease was rejected, and token revocation converged to two stable authorization denials. Retain persistent canary `refs/heads/website-production-canary` at exact `C=0bf88a064233635e0c5485c61f9c533974a7dca4`; never reset, delete, or repurpose it. Keep the production lifecycle and App-only update rules mirrored on that ref, keep the single-use canary source removed, and retain the exact run, ref, ruleset, rule-suite, denial, and token-revocation evidence. Keep the production helper hard-bound to `website-production`. Never broaden permissions silently. Scrub every `WRENCH_RELEASE_APP_*` value from read-only `gh` children. Fetch only the exact verified tag through the private askpass token, peel it locally to the independently verified SHA without executing tagged code, and then push that admitted object through the same ephemeral credential boundary with explicit `--force-with-lease=refs/heads/website-production:<expected-old>`. Mask the installation token around that exact fetch and one leased push, then send exactly one empty-204 revocation request and require two stable authorization denials from the exact Wrench installation-repository endpoint inside the reviewed ten-slot, 30-second monotonic operational window before the exact ref post-read. Require canonical GitHub `Date` headers strictly before the minted `expires_at` on that DELETE 204 and every accepted 200 or 401. In the sanitized receipt, `propagationObserved=false` means the first two probes were the stable 401 pair with no observed 200; `propagationObserved=true` means at least one exact 200 preceded the final two stable 401s. Bind that exact bounded object as `releaseAppRevocation` in every advanced `wrench-provider-promotion-v2` receipt, and bind `null` on the separate no-write `already-exact` path. Treat the window as a fail-closed ceiling, not a GitHub propagation SLA; reject a denial that returns to authorization, nonconvergence, indeterminate timing or transport, and any malformed or unexpected response. Never retry the action, retain concurrent operation and revocation failures, and cap the App path at fourteen REST requests. Require bounded read-only jobs to bracket promotion with authenticated GitHub server time, fingerprint the complete current state and `latestStatus` of at most 500 Production deployments, and exhaustively audit only the pinned candidate's REST status history. Reject any retained failure, error, or inactive candidate status even after success. Bind the REST deployment's lowercase commit `.ref` and `.sha` to the verified release while GraphQL reports a null `ref` and the same `commitOid`. Keep 20 observation slots at absolute minute offsets zero through 19 inside one injected monotonic 20-minute `[start, deadline)` interval and a separate 30-minute read-only job. Charge API latency to that window without sliding later slots, and never start a provider read at the deadline. Bind one exact successful Vercel Production deployment plus stable terminal tag, Release, Latest, workflow source, ref, inventory, status, and canonical-host readbacks before promotion succeeds. A verified Production build emits one exact seven-key `/.well-known/wrench-release.json` after its site build, binding the verifier-proven local HEAD and release tag to the strict unique Vercel deployment URL. The provider baseline reads it twice; only exact v0.16.5 may begin from 404. Outcome requires that deployment URL to equal the pinned status URLs, permits only baseline-to-target movement, and finishes with two stable apex marker/health snapshots plus one exact no-follow `www` 308 in each snapshot. Preview and local builds emit no marker. Do not make correctness depend on bypassing Vercel's static cache, and do not make the global receipt depend on previous deployment statuses that GitHub deletes after 90 days; GitHub preserves the current status on the deployment.
- - Before every stable tag push, a signed-in administrator must freshly prove both immutable Releases enabled and one exact active repository tag ruleset targeting only `refs/tags/v*`, with no bypass actors and exact deletion plus update rules while creation remains allowed. Current ruleset `19989752` / `Immutable version tags` is retained evidence; its semantics, not its ID or name, are authority. The Release workflow must not receive Administration permission or call ruleset endpoints. The only manual branch-create exception is the documented one-time Vercel bootstrap at the exact current immutable Latest Release commit. After it, a missing production branch is a hard failure. Live ruleset `21832074` supplies no-bypass creation, deletion, and non-fast-forward protection to the production and persistent canary refs. Live ruleset `21887484` supplies the sole update restriction and exact App `4783991` `Integration` bypass with `bypass_mode=always`; no other actor may update either ref. Incident freeze ruleset `22182820` was removed by captured numeric ID during the audited v0.16.4 production promotion and is historical, not a live control. 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 `website-production`; keep exact project `prj_TZbDZ38ABPan158IqnczgsuTu6Ue`, team `team_UAd1iD2XogJlbFg4h14mRaPM`, GitHub repository ID `1316443113`, `link.productionBranch=website-production`, `autoExposeSystemEnvs=true`, and persistent `autoAssignCustomDomains=true`. False may stage without moving the canonical domains and is never a release-time toggle. Require exact setting-only before/after readback for first enablement and the full persistent project/target/domain preflight thereafter. Ambiguity is readback-only; recovery never blindly reruns, rewrites the ref, or individually aliases a candidate. `main` and pull requests are preview sources, never production website sources.
+ - Follow `docs/publishing.md` for the interactive npm bootstrap and later stage-only trusted publishing. A monotonically greater stable version reaching `main` must automatically enter exact candidate verification and upload one uniquely named package artifact; an unchanged version must no-op, and default workflow dispatch remains the current-`main` candidate recovery path. A push or default `workflow_dispatch` must never enter the GitHub environment, request an OIDC token, or mutate npm. Only an explicit owner-authorized current-`main` dispatch with boolean `publish_to_npm=true` may pass the already verified stable artifact to the minimal OIDC job behind the main-only `npm-stage` environment with no required GitHub deployment reviewers; an agent acting under standing repository delivery authority may make that dispatch without adding a separate human approval gate. Bind npm trust to that exact environment and stage-only action; never authorize direct OIDC publication for this dual-use package. Bind the staged artifact to source commit `C`; protected `main` may advance only by proven linear ancestry while the long gate runs, and the terminal job must observe two equal combined main-plus-tag-absence advertisements around that ancestry proof immediately before staging. Human inspection and two-factor approval of the npm stage remain mandatory before the version becomes public. Verify that exact public artifact before creating its tag. Treat a raw `v*` tag as a release request, not a completed release; completed immutable Releases define ordering. Keep the requested tag as a direct lightweight tag on package commit `C`, with protected linear `main` equal to or descended from `C`; the read-only release gate must rebuild and compare the public npm tarball before its sole `contents: write` job creates or verifies the immutable Latest GitHub Release with `make_latest=legacy`. Immediately before tag dispatch, require signed-in administrator readback that immutable Releases are enabled; do not grant Administration to the workflow, and treat the residual setting-toggle window as a trusted control-plane boundary. The Release workflow must never read, create, or update `website-production`, receive the release App key, or wait for Vercel. Load the separate production-promotion workflow from reviewed main source `W`; prove release `C<=W<=M` for protected current main `M`, allowing only linear descendant movement after dispatch; bind its automatic `workflow_run` to Wrench repository ID `1316443113` and Release workflow ID `323493609` plus the exact path, tag-push event, first attempt, success, head repository, tag, peeled immutable release SHA, and payload run ID. Manual recovery on that same main-origin workflow accepts only an untrusted stable-tag input and carries no upstream SHA, run ID, or attempt. Derive the authoritative run ID from the Release's sampled exact Actions receipt. In the initial verify job, 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. Manual recovery requires a positive current attempt. 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 exact `wrench-provider-baseline-v4` and `wrench-provider-promotion-v3` receipts and every later authority, promotion, and outcome check. Grant `actions: read` only to the initial verify job. Record the complete bounded Vercel Production baseline before any key-environment wait. An already-exact ref must take a separate read-only path with no environment, App variable, private key, token mint, or Git push.
+ - 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-stage` environment fail closed: administrator bypass disabled, no reviewers, no secrets, sole protection rule `branch_policy`, and sole selected deployment branch `main` with policy type `branch`. Any drift blocks npm staging; do not weaken the environment or npm's separate 2FA promotion gate to recover a run.
+ - A required fast-forward must enter `production-ref-writer-key` with `deployment: false`, reviewer `0thernet`, `prevent_self_review=false`, and no administrator bypass; revalidate source and immutable release authority after approval; and authenticate one private Hraness App. The App registration and every minted token must close to exactly `metadata:read`, `contents:write`, and `workflows:write`, with no Administration or other permission. Workflows write is required because an admitted fast-forward may introduce reviewed `.github/workflows` changes. Runtime must request and validate a token narrowed to Wrench repository ID `1316443113`; privileged setup must separately enumerate the installation-wide selected-repository set and prove it contains only Wrench before key admission. The writer's retained admission proof is workflow run `33691443614`: an ordinary `P` to `C` update was denied, the dedicated App performed the only leased fast-forward, the stale lease was rejected, and token revocation converged to two stable authorization denials. Retain persistent canary `refs/heads/website-production-canary` at exact `C=0bf88a064233635e0c5485c61f9c533974a7dca4`; never reset, delete, or repurpose it. Keep the production lifecycle and App-only update rules mirrored on that ref, keep the single-use canary source removed, and retain the exact run, ref, ruleset, rule-suite, denial, and token-revocation evidence. Keep the production helper hard-bound to `website-production`. Never broaden permissions silently. Scrub every `WRENCH_RELEASE_APP_*` value from read-only `gh` children. Fetch only the exact verified tag through the private askpass token, peel it locally to the independently verified SHA without executing tagged code, and then push that admitted object through the same ephemeral credential boundary with explicit `--force-with-lease=refs/heads/website-production:<expected-old>`. Mask the installation token around that exact fetch and one leased push, then send exactly one empty-204 revocation request and require two stable authorization denials from the exact Wrench installation-repository endpoint inside the reviewed ten-slot, 30-second monotonic operational window before the exact ref post-read. Require canonical GitHub `Date` headers strictly before the minted `expires_at` on that DELETE 204 and every accepted 200 or 401. In the sanitized receipt, `propagationObserved=false` means the first two probes were the stable 401 pair with no observed 200; `propagationObserved=true` means at least one exact 200 preceded the final two stable 401s. Bind that exact bounded object as `releaseAppRevocation` in every advanced `wrench-provider-promotion-v3` receipt, and bind `null` on the separate no-write `already-exact` path. Treat the window as a fail-closed ceiling, not a GitHub propagation SLA; reject a denial that returns to authorization, nonconvergence, indeterminate timing or transport, and any malformed or unexpected response. Never retry the action, retain concurrent operation and revocation failures, and cap the App path at fourteen REST requests. Require bounded read-only jobs to bracket promotion with authenticated GitHub server time, fingerprint the complete current state and `latestStatus` of at most 500 Production deployments, and exhaustively audit only the pinned candidate's REST status history. Reject any retained failure, error, or inactive candidate status even after success. Bind the REST deployment's lowercase commit `.ref` and `.sha` to the verified release while GraphQL reports a null `ref` and the same `commitOid`. Keep 20 observation slots at absolute minute offsets zero through 19 inside one injected monotonic 20-minute `[start, deadline)` interval and a separate 30-minute read-only job. Charge API latency to that window without sliding later slots, and never start a provider read at the deadline. Bind one exact successful Vercel Production deployment plus stable terminal tag, Release, Latest, workflow source, ref, inventory, status, and canonical-host readbacks before promotion succeeds. A verified Production build emits one exact seven-key `/.well-known/wrench-release.json` after its site build, binding the verifier-proven local HEAD and release tag to the strict unique Vercel deployment URL. The provider baseline reads it twice; only exact v0.16.5 may begin from 404. Outcome requires that deployment URL to equal the pinned status URLs, permits only baseline-to-target movement, and finishes with two stable apex marker/health snapshots plus one exact no-follow `www` 308 in each snapshot. Preview and local builds emit no marker. Do not make correctness depend on bypassing Vercel's static cache, and do not make the global receipt depend on previous deployment statuses that GitHub deletes after 90 days; GitHub preserves the current status on the deployment.
+ - Before every stable tag push, a signed-in administrator must freshly prove immutable Releases enabled and two exact active repository tag rulesets targeting only `refs/tags/v*`. The creation-only ruleset must have exact rule `creation` and sole always-bypass User `894119`; 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. Current rulesets `22311815` / `Release tag creation` and `19989752` / `Immutable version tags` are retained evidence; their split semantics, not their IDs or names, are authority. Never give GitHub Actions or another Integration a release-tag bypass. The Release workflow must not receive Administration permission or call ruleset endpoints. The only manual branch-create exception is the documented one-time Vercel bootstrap at the exact current immutable Latest Release commit. After it, a missing production branch is a hard failure. Live ruleset `21832074` supplies no-bypass creation, deletion, and non-fast-forward protection to the production and persistent canary refs. Live ruleset `21887484` supplies the sole update restriction and exact App `4783991` `Integration` bypass with `bypass_mode=always`; no other actor may update either ref. Incident freeze ruleset `22182820` was removed by captured numeric ID during the audited v0.16.4 production promotion and is historical, not a live control. 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 `website-production`; keep exact project `prj_TZbDZ38ABPan158IqnczgsuTu6Ue`, team `team_UAd1iD2XogJlbFg4h14mRaPM`, GitHub repository ID `1316443113`, `link.productionBranch=website-production`, `autoExposeSystemEnvs=true`, and persistent `autoAssignCustomDomains=true`. False may stage without moving the canonical domains and is never a release-time toggle. Require exact setting-only before/after readback for first enablement and the full persistent project/target/domain preflight thereafter. Ambiguity is readback-only; recovery never blindly reruns, rewrites the ref, or individually aliases a candidate. `main` and pull requests are preview sources, never production website sources.
- The retained proof is evidence, not standing mutation authority. Before every required fast-forward, fresh administrator readback must reconfirm the permanent rulesets and target refs; the sole App `4783991` `Integration` bypass; the exact App permission set; installation `158077029` selects only Wrench repository ID `1316443113`; and the main-only, reviewer-gated `production-ref-writer-key` environment with no administrator bypass, `prevent_self_review=false`, exactly four App identity variables and the one private-key secret. Any drift leaves production unchanged. The audited v0.16.4 removal of incident freeze `22182820` does not authorize changing either permanent rule or silently weakening a future incident freeze.
+
+ - Bind every Release run at entry to a protected tag-push event and embedded sender owned by User `894119` in public Wrench 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 the stage-only job sets up npm or mints OIDC, bind its current attempt—including both `actor` and `triggering_actor`—to owner User `894119`, npm-stage workflow ID `344213783`, protected `main`, the exact source SHA, and public Wrench repository ID `1316443113`; delegated reruns must fail closed. Independently parse the downloaded 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. Name each stage job with its exact stable version and inspect the complete bounded retained workflow-dispatch history plus all attempts of the current run with `actions:read`; any queued or in-progress non-current run must fail closed. A successful version-bound `Record exclusive stable-stage intent` step immediately before the npm mutation is the durable reservation even when the enclosing job later fails or its write result is ambiguous; never use whole-job success as the lock. A retained intent newer than public npm `latest` blocks later staging. Only the empty-by-default owner-authorized `resolved_stage_version` recovery input may acknowledge the one exact stage already rejected through npm, and a successful exact-version resolution step must persist that clearance in Actions history. Scrub ambient tag variables and project, user, and global npm configuration; prove pinned npm's clean default tag is `latest`; re-read public `latest` at the terminal boundary; and call `npm stage publish` without `--tag` so npm's own monotonic default-tag guard remains active. Require the exact public version to be npm `dist-tags.latest` before creating its GitHub Release.
+
+ - A matching public tarball is insufficient release authority. Before GitHub Release mutation, require npm `dist-tags.latest` to equal the candidate and use pinned npm's signature audit to cryptographically verify the registry publish attestation and one SLSA v1 provenance statement bound to the exact tarball digest, Wrench npm-stage workflow/repository/main/event IDs, source commit, GitHub-hosted builder, and invocation. Read that invocation back from GitHub and require the exact completed successful owner-authorized stage attempt, version-bound stage job, and successful stable-stage intent step.
<!-- 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 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.
<!-- hra-local-efficiency:end -->