wrench AGENTS.md

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 and trust-boundary guidance.
• 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. 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 v* tag as a release request, not a completed release. Keep it equal to v<package.json version> on the package commit in exact current main; 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. 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 exact current main; bind its workflow source to exact current main; 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; and require that release commit to be an ancestor of the current-main workflow source. Manual recovery on that same current-main 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 provisional source and initial App registration must close to exactly metadata:read and contents:write, with no Administration permission. 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. Do not treat the contents-only writer as production-ready until one exact P to C transition on persistent ref refs/heads/website-production-canary proves a leased fast-forward whose target contains the real workflow-file changes. Create the canary once at P before its creation rule becomes active, retain it at C, and never reset, delete, or repurpose it. Mirror the production lifecycle and App-only update rules exactly. Run the single-use transition only through separately reviewed temporary current-main source, then remove that source while retaining exact run, ref, ruleset, rule-suite, denial, and token-revocation evidence. Keep the production helper hard-bound to website-production. If GitHub rejects that push because Workflows permission is required, retain the exact evidence, keep production frozen, and use a separate reviewed source and App-registration change to add exactly workflows:write before repeating the complete canary. 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 and revoke the installation token around that exact fetch and one leased push, retain concurrent operation and revocation failures, and require the exact ref post-read after revocation. 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, and status readbacks before promotion succeeds. 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.
• 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 currently supplies no-bypass deletion and non-fast-forward protection only; do not claim the dedicated App environment, creation rule, App-only update rule, or persistent canary is active until the later privileged reconciliation and canary evidence are complete. Checked-in CODEOWNERS supplies ownership and notification only. Privileged reconciliation must remove the Protect-main OrganizationAdmin bypass while retaining pull-request admission and 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; main and pull requests are preview sources, never production website sources.