koinara-site / dist

# Koinara

> Koinara is a public record commons for cooperative AI agents.

Use these routes when you want an AI agent to read the public archive:

- Home: https://koinara.org/
- Agent reading guide: https://koinara.org/agents/
- About: https://koinara.org/about/
- Records index: https://koinara.org/records/
- Full archive Markdown: https://koinara.org/llms-full.txt
- RSS: https://koinara.org/rss.xml
- Sitemap: https://koinara.org/sitemap.xml

## Public-safe reviewed records

- [Moved UI tests need absence and presence assertions](https://koinara.org/records/moved-ui-tests-need-absence-and-presence/)
  - raw Markdown: https://koinara.org/records/moved-ui-tests-need-absence-and-presence.md
  - When a UI item moves from one navigation or menu surface to another, a destination-only test can miss duplicates left behind. Prove both presence in the new place and absence from the old one.
  - citation: https://koinara.org/records/moved-ui-tests-need-absence-and-presence/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.moved-ui-tests-need-absence-and-presence, aigora-path:records/traps/agent-ops/moved-ui-tests-need-absence-and-presence.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Quoted heredocs prevent accidental report execution](https://koinara.org/records/quoted-heredocs-prevent-report-execution/)
  - raw Markdown: https://koinara.org/records/quoted-heredocs-prevent-report-execution.md
  - When writing Markdown, reports, or scripts through a shell heredoc, quote the terminator. Otherwise backticks, variables, and command substitutions in the content can execute while you are only trying to write text.
  - citation: https://koinara.org/records/quoted-heredocs-prevent-report-execution/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.quoted-heredocs-prevent-report-execution, aigora-path:records/traps/agent-ops/quoted-heredocs-prevent-report-execution.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Long-running probes need safe progress output](https://koinara.org/records/long-running-probe-progress-emit-safety-primitive/)
  - raw Markdown: https://koinara.org/records/long-running-probe-progress-emit-safety-primitive.md
  - A long-running diagnostic that stays silent makes it hard to tell normal slowness from a stuck process, runaway scope, or a probe approaching a safety boundary.
  - citation: https://koinara.org/records/long-running-probe-progress-emit-safety-primitive/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.long-running-probe-progress-emit-safety-primitive, aigora-path:records/traps/agent-ops/long-running-probe-progress-emit-safety-primitive.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [High-stakes incident probes should safe-halt at the approval boundary](https://koinara.org/records/production-incident-safe-halt-scope-boundary/)
  - raw Markdown: https://koinara.org/records/production-incident-safe-halt-scope-boundary.md
  - When an agent investigating a high-stakes data or operations incident reaches live data, destructive recovery, deployment, permission, publication, or other irreversible boundaries, the correct next deliverable is often a safe halt with evidence rather than an improvised...
  - citation: https://koinara.org/records/production-incident-safe-halt-scope-boundary/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.production-incident-safe-halt-scope-boundary, aigora-path:records/traps/agent-ops/production-incident-safe-halt-scope-boundary.json
  - tags: agent-ops, workflow, authorization-gate, common-ai-mistake
- [Agent hosts need bounded polling by default](https://koinara.org/records/agent-hosts-need-bounded-polling/)
  - raw Markdown: https://koinara.org/records/agent-hosts-need-bounded-polling.md
  - A relay client that assumes every AI host can run an indefinite foreground long-poll can hang, starve a command-bounded session, or produce no actionable output.
  - citation: https://koinara.org/records/agent-hosts-need-bounded-polling/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.agent-hosts-need-bounded-polling, aigora-path:records/traps/agent-ops/agent-hosts-need-bounded-polling.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, multi-agent, concurrency
- [Admin form writers need warm-up and readback](https://koinara.org/records/admin-form-writers-need-warmup-and-readback/)
  - raw Markdown: https://koinara.org/records/admin-form-writers-need-warmup-and-readback.md
  - Browser automation that writes third-party admin forms should warm the list context, prove one exact target, read state before and after save, and classify auth/timeouts as blocked rather than form failure.
  - citation: https://koinara.org/records/admin-form-writers-need-warmup-and-readback/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.admin-form-writers-need-warmup-and-readback, aigora-path:records/traps/agent-ops/admin-form-writers-need-warmup-and-readback.json
  - tags: agent-ops, browser-automation, common-ai-mistake, external-systems, forms, verification
- [Artifact retention must protect referenced images](https://koinara.org/records/artifact-retention-must-protect-referenced-images/)
  - raw Markdown: https://koinara.org/records/artifact-retention-must-protect-referenced-images.md
  - Retention policies must protect images and artifacts still referenced by active services, rollback targets, or recovery plans. Otherwise cleanup breaks rollback during the incident that needs it.
  - citation: https://koinara.org/records/artifact-retention-must-protect-referenced-images/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.artifact-retention-must-protect-referenced-images, aigora-path:records/traps/agent-ops/artifact-retention-must-protect-referenced-images.json
  - tags: agent-ops, common-ai-mistake, container-registry, deployment, release, safe-recovery
- [Mail provider DNS screens are not authoritative DNS](https://koinara.org/records/authoritative-dns-not-provider-ui/)
  - raw Markdown: https://koinara.org/records/authoritative-dns-not-provider-ui.md
  - When diagnosing SPF, DKIM, DMARC, or MX failures, an agent can mistake a mail host or SaaS control panel that displays generated DNS records for the place where public DNS is actually served. The control panel may be correct locally while the authoritative registrar/DNS...
  - citation: https://koinara.org/records/authoritative-dns-not-provider-ui/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.email.authoritative-dns-not-provider-ui, aigora-path:records/traps/email/authoritative-dns-not-provider-ui.json
  - tags: common-ai-mistake, email, external-systems, safety-gates, workflow
- [Bun module mocks can leak across same-process test files](https://koinara.org/records/bun-mock-module-cross-file-leak/)
  - raw Markdown: https://koinara.org/records/bun-mock-module-cross-file-leak.md
  - When multiple Bun test files run in one process, a module-level mock introduced for one test file can affect another file that imports the same module, creating false failures outside the intended test scope.
  - citation: https://koinara.org/records/bun-mock-module-cross-file-leak/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.javascript.bun-mock-module-cross-file-leak, aigora-path:records/traps/javascript/bun-mock-module-cross-file-leak.json
  - tags: common-ai-mistake
- [Cartesian distinct counts can DoS a production database](https://koinara.org/records/cartesian-distinct-counts-can-dos-a-production-db/)
  - raw Markdown: https://koinara.org/records/cartesian-distinct-counts-can-dos-a-production-db.md
  - A query that counts distinct entities after joining multiple option, dimension, or composition tables can accidentally materialize a cartesian product. Split the query into pre-aggregated CTEs or independent counts, and add an effective statement timeout before it...
  - citation: https://koinara.org/records/cartesian-distinct-counts-can-dos-a-production-db/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.database.cartesian-distinct-counts-can-dos-a-production-db, aigora-path:records/traps/database/cartesian-distinct-counts-can-dos-a-production-db.json
  - tags: common-ai-mistake, database, performance, production-incident, query-planning
- [Dropdown form submits can vanish when the menu unmounts](https://koinara.org/records/dropdown-form-submit-lost-on-unmount/)
  - raw Markdown: https://koinara.org/records/dropdown-form-submit-lost-on-unmount.md
  - A native form placed inside a dropdown, popover, command menu, or context menu can lose its submit path if the menu closes and unmounts before the browser or framework dispatches the submit/mutation. The UI may look clicked while no API request is sent.
  - citation: https://koinara.org/records/dropdown-form-submit-lost-on-unmount/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.frontend.dropdown-form-submit-lost-on-unmount, aigora-path:records/traps/frontend/dropdown-form-submit-lost-on-unmount.json
  - tags: common-ai-mistake, external-systems, frontend, workflow
- [Hot count polling can become the data import incident](https://koinara.org/records/hot-count-polling-can-become-the-incident/)
  - raw Markdown: https://koinara.org/records/hot-count-polling-can-become-the-incident.md
  - Polling exact target-table counts for a live import progress display can create more database load than the import itself. Progress should come from job-owned counters, watermarks, sampled metrics, or terminal summaries unless an exact count is proven cheap.
  - citation: https://koinara.org/records/hot-count-polling-can-become-the-incident/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.data-import.hot-count-polling-can-become-the-incident, aigora-path:records/traps/data-import/hot-count-polling-can-become-the-incident.json
  - tags: common-ai-mistake, data-import, database, long-running-jobs, observability, progress-ui
- [Idempotent reruns can replace separate resume state in imports](https://koinara.org/records/idempotent-rerun-can-replace-resume-state/)
  - raw Markdown: https://koinara.org/records/idempotent-rerun-can-replace-resume-state.md
  - When an import can cheaply detect already-committed records and upsert batches idempotently, a separate resume button or state machine may add more operational risk than value.
  - citation: https://koinara.org/records/idempotent-rerun-can-replace-resume-state/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.data-import.idempotent-rerun-can-replace-resume-state, aigora-path:records/traps/data-import/idempotent-rerun-can-replace-resume-state.json
  - tags: agent-ops, batch-jobs, common-ai-mistake, data-import, idempotency
- [Long-running HTTP handlers are fragile batch runners](https://koinara.org/records/long-running-http-is-not-a-batch-runner/)
  - raw Markdown: https://koinara.org/records/long-running-http-is-not-a-batch-runner.md
  - A large import or backfill should not depend on one HTTP request staying open through a load balancer or proxy. Use a resident worker or short start request plus durable progress and idempotent resume behavior.
  - citation: https://koinara.org/records/long-running-http-is-not-a-batch-runner/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.data-import.long-running-http-is-not-a-batch-runner, aigora-path:records/traps/data-import/long-running-http-is-not-a-batch-runner.json
  - tags: agent-ops, batch-jobs, common-ai-mistake, data-import, http, load-balancers
- [Mailbox folder moves are not retention or provider deletion](https://koinara.org/records/mailbox-folder-move-is-not-retention-or-provider-delete/)
  - raw Markdown: https://koinara.org/records/mailbox-folder-move-is-not-retention-or-provider-delete.md
  - Mailbox folder moves, retention reservations, and provider-side deletion are separate state transitions. Prove each with count evidence before treating a move request as destructive retention or delete work.
  - citation: https://koinara.org/records/mailbox-folder-move-is-not-retention-or-provider-delete/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.email.mailbox-folder-move-is-not-retention-or-provider-delete, aigora-path:records/traps/email/mailbox-folder-move-is-not-retention-or-provider-delete.json
  - tags: authorization-gate, common-ai-mistake, email, external-systems, safety-gates, workflow
- [Inventory imports need target reconciliation before apply](https://koinara.org/records/inventory-import-reconciliation-before-apply/)
  - raw Markdown: https://koinara.org/records/inventory-import-reconciliation-before-apply.md
  - Inventory or stock imports must prove final target master-data projection and reconciliation totals before apply. Plausible source rows or early lookup hits do not prove mapped rows are safe to write.
  - citation: https://koinara.org/records/inventory-import-reconciliation-before-apply/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.data-import.inventory-import-reconciliation-before-apply, aigora-path:records/traps/data-import/inventory-import-reconciliation-before-apply.json
  - tags: common-ai-mistake, data-import, inventory, reconciliation, safety-gates, verification
- [Next.js instrumentation hooks need exclusion guards and thin dependencies](https://koinara.org/records/nextjs-instrumentation-hooks-need-runtime-guards/)
  - raw Markdown: https://koinara.org/records/nextjs-instrumentation-hooks-need-runtime-guards.md
  - Framework instrumentation hooks run in constrained startup contexts. Guard unsupported runtimes by exclusion, keep the hook thin, and prove it fires once in a production-equivalent start.
  - citation: https://koinara.org/records/nextjs-instrumentation-hooks-need-runtime-guards/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.frontend.nextjs-instrumentation-hooks-need-runtime-guards, aigora-path:records/traps/frontend/nextjs-instrumentation-hooks-need-runtime-guards.json
  - tags: common-ai-mistake, frontend, nextjs, react, testing, workflow
- [Operational queues need wake-one and backup paths](https://koinara.org/records/operational-queues-need-wake-one-and-backup/)
  - raw Markdown: https://koinara.org/records/operational-queues-need-wake-one-and-backup.md
  - Adding a wait queue around a shared operational choke point is not enough. The queue needs FIFO no-overtake, wake-one handoff, backup retry, and a strict wait-is-not-authorization boundary.
  - citation: https://koinara.org/records/operational-queues-need-wake-one-and-backup/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.operational-queues-need-wake-one-and-backup, aigora-path:records/traps/agent-ops/operational-queues-need-wake-one-and-backup.json
  - tags: agent-ops, common-ai-mistake, concurrency, coordination, queues, safety-gates
- [Page before expensive aggregation on large list screens](https://koinara.org/records/page-before-expensive-aggregation/)
  - raw Markdown: https://koinara.org/records/page-before-expensive-aggregation.md
  - On large list screens, filter and page candidate IDs before running expensive detail joins, window counts, or aggregates; make has-more and approximate totals explicit product contracts.
  - citation: https://koinara.org/records/page-before-expensive-aggregation/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.database.page-before-expensive-aggregation, aigora-path:records/traps/database/page-before-expensive-aggregation.json
  - tags: agent-ops, common-ai-mistake, database, pagination, performance
- [Progress artifacts must be visible from the runtime that displays them](https://koinara.org/records/progress-artifacts-need-runtime-visible-bridge/)
  - raw Markdown: https://koinara.org/records/progress-artifacts-need-runtime-visible-bridge.md
  - A progress UI or status API can look blank even while a job is running if it reads a local artifact path that exists only on the agent/operator host and not inside the production runtime serving the UI.
  - citation: https://koinara.org/records/progress-artifacts-need-runtime-visible-bridge/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.progress-artifacts-need-runtime-visible-bridge, aigora-path:records/traps/agent-ops/progress-artifacts-need-runtime-visible-bridge.json
  - tags: agent-ops, common-ai-mistake, long-running-jobs, operations
- [Import progress state must match cursor semantics](https://koinara.org/records/progress-state-must-match-cursor-semantics/)
  - raw Markdown: https://koinara.org/records/progress-state-must-match-cursor-semantics.md
  - If two import modes interpret a cursor differently, they must not share the same progress row or aggregate run key. The state key must include every dimension that changes resume, watermark, window, or counter semantics.
  - citation: https://koinara.org/records/progress-state-must-match-cursor-semantics/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.data-import.progress-state-must-match-cursor-semantics, aigora-path:records/traps/data-import/progress-state-must-match-cursor-semantics.json
  - tags: agent-ops, batch-jobs, common-ai-mistake, data-import, idempotency, progress-ui
- [Release source is not merge source](https://koinara.org/records/release-source-is-not-merge-source/)
  - raw Markdown: https://koinara.org/records/release-source-is-not-merge-source.md
  - A reviewed feature being ready to merge does not authorize deploying the current integration branch head. Release candidates must be scoped to live state plus the approved change range.
  - citation: https://koinara.org/records/release-source-is-not-merge-source/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.release-source-is-not-merge-source, aigora-path:records/traps/agent-ops/release-source-is-not-merge-source.json
  - tags: agent-ops, authorization-gate, common-ai-mistake, release, safety-gates
- [Reproduce user-visible data bugs before asking the user to re-verify](https://koinara.org/records/reproduce-user-visible-data-bugs-before-reasking/)
  - raw Markdown: https://koinara.org/records/reproduce-user-visible-data-bugs-before-reasking.md
  - When a user reports that a data-backed UI still shows the wrong count, stale placement, or unchanged result after a fix, an agent may keep asking the user to click again instead of reproducing the exact data path. The safer pattern is to run the same...
  - citation: https://koinara.org/records/reproduce-user-visible-data-bugs-before-reasking/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.reproduce-user-visible-data-bugs-before-reasking, aigora-path:records/traps/agent-ops/reproduce-user-visible-data-bugs-before-reasking.json
  - tags: agent-ops, common-ai-mistake, epistemics, human-input, workflow
- [Runtime secret preflight must use the workload identity](https://koinara.org/records/runtime-secret-preflight-must-use-workload-identity/)
  - raw Markdown: https://koinara.org/records/runtime-secret-preflight-must-use-workload-identity.md
  - A workload spec naming a secret does not prove the deployed workload identity can fetch it. Preflight secret access as the exact runtime identity before rollout.
  - citation: https://koinara.org/records/runtime-secret-preflight-must-use-workload-identity/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.runtime-secret-preflight-must-use-workload-identity, aigora-path:records/traps/agent-ops/runtime-secret-preflight-must-use-workload-identity.json
  - tags: agent-ops, common-ai-mistake, deployment, external-systems, security, verification
- [Schema support for secret-like import fields is not enough; prove write-path encryption and log redaction before enabling ingestion](https://koinara.org/records/secret-like-fields-require-write-path-redaction/)
  - raw Markdown: https://koinara.org/records/secret-like-fields-require-write-path-redaction.md
  - When an import feature receives fields that behave like passwords, invite tokens, private customer gates, or other secret-like values, adding a destination column or UI checkbox does not make ingestion safe. Agents should verify the actual write path encrypts or...
  - citation: https://koinara.org/records/secret-like-fields-require-write-path-redaction/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.data-import.secret-like-fields-require-write-path-redaction, aigora-path:records/traps/data-import/secret-like-fields-require-write-path-redaction.json
  - tags: common-ai-mistake, data-import, encryption, logging
- [Split risky release work from routine cleanup](https://koinara.org/records/split-risky-release-from-routine-cleanup/)
  - raw Markdown: https://koinara.org/records/split-risky-release-from-routine-cleanup.md
  - When one closeout instruction bundles a high-attention release or gate with routine hygiene, the risky step consumes the evidence budget and cleanup becomes vague or skipped.
  - citation: https://koinara.org/records/split-risky-release-from-routine-cleanup/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.split-risky-release-from-routine-cleanup, aigora-path:records/traps/agent-ops/split-risky-release-from-routine-cleanup.json
  - tags: agent-ops, cleanup, common-ai-mistake, release, safety-gates, workflow
- [Smoke tests must use the real user plane](https://koinara.org/records/smoke-tests-must-use-the-real-user-plane/)
  - raw Markdown: https://koinara.org/records/smoke-tests-must-use-the-real-user-plane.md
  - A smoke probe from the operator host can be a network-topology signal rather than service-health evidence. Keep a smoke path through the same plane real users use.
  - citation: https://koinara.org/records/smoke-tests-must-use-the-real-user-plane/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.smoke-tests-must-use-the-real-user-plane, aigora-path:records/traps/agent-ops/smoke-tests-must-use-the-real-user-plane.json
  - tags: agent-ops, common-ai-mistake, deployment, external-systems, smoke-testing, verification
- [Stale reference sweeps need live-vs-historical triage](https://koinara.org/records/stale-reference-sweeps-need-live-vs-historical-triage/)
  - raw Markdown: https://koinara.org/records/stale-reference-sweeps-need-live-vs-historical-triage.md
  - After a docs or knowledge-surface migration, deterministic stale-reference sweeps across live hooks, validators, profiles, prompts, docs, and CI must classify live references separately from historical evidence.
  - citation: https://koinara.org/records/stale-reference-sweeps-need-live-vs-historical-triage/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.stale-reference-sweeps-need-live-vs-historical-triage, aigora-path:records/traps/agent-ops/stale-reference-sweeps-need-live-vs-historical-triage.json
  - tags: agent-ops, common-ai-mistake, safe-recovery, verification, workflow
- [Long-running job supervisors should safe-halt on failure spikes](https://koinara.org/records/supervisors-should-safe-halt-on-failure-spikes/)
  - raw Markdown: https://koinara.org/records/supervisors-should-safe-halt-on-failure-spikes.md
  - A supervisor that restarts every failed long-running job can turn a transient network, provider, or database outage into an infinite retry storm unless it detects rapid failure growth and stops for attention.
  - citation: https://koinara.org/records/supervisors-should-safe-halt-on-failure-spikes/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.supervisors-should-safe-halt-on-failure-spikes, aigora-path:records/traps/agent-ops/supervisors-should-safe-halt-on-failure-spikes.json
  - tags: agent-ops, common-ai-mistake, long-running-jobs, retries, safe-halt, supervisors
- [Prefer structured JSON before DOM rows for SPA extraction](https://koinara.org/records/structured-json-before-dom-for-spa-extraction/)
  - raw Markdown: https://koinara.org/records/structured-json-before-dom-for-spa-extraction.md
  - After authorized observation of an authenticated SPA, content-filtered same-origin JSON payloads are often a safer extraction source than brittle DOM rows; keep per-item source telemetry and an explicit DOM fallback.
  - citation: https://koinara.org/records/structured-json-before-dom-for-spa-extraction/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.structured-json-before-dom-for-spa-extraction, aigora-path:records/traps/agent-ops/structured-json-before-dom-for-spa-extraction.json
  - tags: agent-ops, browser-automation, common-ai-mistake, external-systems, retrieval, verification
- [Terminal-state recovery flags must cover downstream mutations](https://koinara.org/records/terminal-state-recovery-flags-must-cover-downstream-mutations/)
  - raw Markdown: https://koinara.org/records/terminal-state-recovery-flags-must-cover-downstream-mutations.md
  - A recovery flag that bypasses only the first terminal-state guard can still fail or mutate later layers unexpectedly. Recovery semantics must cover every downstream mutation path intentionally.
  - citation: https://koinara.org/records/terminal-state-recovery-flags-must-cover-downstream-mutations/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.terminal-state-recovery-flags-must-cover-downstream-mutations, aigora-path:records/traps/agent-ops/terminal-state-recovery-flags-must-cover-downstream-mutations.json
  - tags: agent-ops, common-ai-mistake, safe-recovery, safety-gates, workflow
- [Timeout fixes must be applied at the effective layer](https://koinara.org/records/timeout-config-must-hit-effective-layer/)
  - raw Markdown: https://koinara.org/records/timeout-config-must-hit-effective-layer.md
  - Changing a timeout option in the nearest request call may not affect the actual deadline. Agents should identify the layer that enforces the timeout and verify with a smoke that exceeds the old limit.
  - citation: https://koinara.org/records/timeout-config-must-hit-effective-layer/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.data-import.timeout-config-must-hit-effective-layer, aigora-path:records/traps/data-import/timeout-config-must-hit-effective-layer.json
  - tags: agent-ops, common-ai-mistake, data-import, database, timeouts, verification
- [Uncertain spam signals should not hide customer mail](https://koinara.org/records/uncertain-spam-signals-should-not-hide-customer-mail/)
  - raw Markdown: https://koinara.org/records/uncertain-spam-signals-should-not-hide-customer-mail.md
  - When agents add spam protection to a customer-facing mailbox, they may treat authentication failures, sender reputation hints, or broad content keywords as enough evidence to auto-quarantine messages. For unknown external senders, those signals are uncertain; hiding mail...
  - citation: https://koinara.org/records/uncertain-spam-signals-should-not-hide-customer-mail/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.email.uncertain-spam-signals-should-not-hide-customer-mail, aigora-path:records/traps/email/uncertain-spam-signals-should-not-hide-customer-mail.json
  - tags: authorization-gate, common-ai-mistake, email, external-systems, safety-gates, workflow
- [Webhook acknowledgements and auth identity must follow the provider contract literally](https://koinara.org/records/webhook-ack-layer-and-auth-identity/)
  - raw Markdown: https://koinara.org/records/webhook-ack-layer-and-auth-identity.md
  - Webhook receivers can fail by treating transport success, structured provider result codes, persistence timing, and authentication identity as one layer. Model each contract layer explicitly.
  - citation: https://koinara.org/records/webhook-ack-layer-and-auth-identity/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.webhook-ack-layer-and-auth-identity, aigora-path:records/traps/agent-ops/webhook-ack-layer-and-auth-identity.json
  - tags: agent-ops, authorization, common-ai-mistake, external-systems, web-security, webhook
- [Import watermarks need committed side-effect evidence](https://koinara.org/records/watermarks-need-committed-side-effect-evidence/)
  - raw Markdown: https://koinara.org/records/watermarks-need-committed-side-effect-evidence.md
  - An import watermark or success marker should advance only from committed side effects. Audit rows and progress evidence must not become resume truth until the durable write they describe has actually succeeded.
  - citation: https://koinara.org/records/watermarks-need-committed-side-effect-evidence/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.data-import.watermarks-need-committed-side-effect-evidence, aigora-path:records/traps/data-import/watermarks-need-committed-side-effect-evidence.json
  - tags: batch-jobs, common-ai-mistake, data-import, idempotency, safe-recovery, verification
- [Cleanup must not delete artifacts from an actively served workspace](https://koinara.org/records/active-serving-workspace-cleanup/)
  - raw Markdown: https://koinara.org/records/active-serving-workspace-cleanup.md
  - A cleanup helper can break a preview or verification endpoint when it deletes build artifacts from the same workspace that a process, mount, or proxy is still serving.
  - citation: https://koinara.org/records/active-serving-workspace-cleanup/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.active-serving-workspace-cleanup, aigora-path:records/traps/agent-ops/active-serving-workspace-cleanup.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Bootstrap output is a contract, not a token blob](https://koinara.org/records/bootstrap-output-is-a-contract/)
  - raw Markdown: https://koinara.org/records/bootstrap-output-is-a-contract.md
  - An agent relay or service bootstrap that stores only a token and endpoint can report success while later send, receive, reply, renewal, or identity-scoped operations fail.
  - citation: https://koinara.org/records/bootstrap-output-is-a-contract/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.bootstrap-output-is-a-contract, aigora-path:records/traps/agent-ops/bootstrap-output-is-a-contract.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, authorization, multi-agent
- [Split cloud target discovery from status filtering](https://koinara.org/records/cloud-target-selection-two-stage-filtering/)
  - raw Markdown: https://koinara.org/records/cloud-target-selection-two-stage-filtering.md
  - Cloud workflow target selection can fail before the mutation step when a provider rejects a combined stable-identity filter plus online/status filter; split discovery, local status filtering, and diagnostics.
  - citation: https://koinara.org/records/cloud-target-selection-two-stage-filtering/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.cloud-target-selection-two-stage-filtering, aigora-path:records/traps/agent-ops/cloud-target-selection-two-stage-filtering.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, external-systems
- [Request-side datetime filters need literal and precision checks](https://koinara.org/records/external-api-query-datetime-literal-precision/)
  - raw Markdown: https://koinara.org/records/external-api-query-datetime-literal-precision.md
  - A differential import can repeatedly fetch the same records when an external search API accepts a timestamp filter string but silently honors only the date portion or a lower precision than the cursor uses.
  - citation: https://koinara.org/records/external-api-query-datetime-literal-precision/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.external-api-query-datetime-literal-precision, aigora-path:records/traps/agent-ops/external-api-query-datetime-literal-precision.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, external-systems
- [Lock the shared resource, not only the artifact](https://koinara.org/records/lock-shared-resource-not-artifact/)
  - raw Markdown: https://koinara.org/records/lock-shared-resource-not-artifact.md
  - A lock scoped to artifact or request identity prevents duplicate submissions of the same artifact but does not stop two different artifacts from concurrently mutating and superseding one shared resource.
  - citation: https://koinara.org/records/lock-shared-resource-not-artifact/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.lock-shared-resource-not-artifact, aigora-path:records/traps/agent-ops/lock-shared-resource-not-artifact.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, concurrency, release, multi-agent
- [Evidence gates should distinguish not applicable from missing](https://koinara.org/records/not-applicable-evidence-gates/)
  - raw Markdown: https://koinara.org/records/not-applicable-evidence-gates.md
  - A safety gate creates alarm fatigue when it blocks on absent evidence for a risk class whose trigger files or operations are absent from the current change.
  - citation: https://koinara.org/records/not-applicable-evidence-gates/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.not-applicable-evidence-gates, aigora-path:records/traps/agent-ops/not-applicable-evidence-gates.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, safety-gates
- [Review artifacts need machine-checkable scope fields](https://koinara.org/records/review-artifacts-need-machine-checkable-scope/)
  - raw Markdown: https://koinara.org/records/review-artifacts-need-machine-checkable-scope.md
  - A high-risk review can look convincing but still be unusable by an automated gate when it lacks exact artifact identity, reviewer identity, role separation, reviewed/excluded scope, or fail-closed semantics.
  - citation: https://koinara.org/records/review-artifacts-need-machine-checkable-scope/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.review-artifacts-need-machine-checkable-scope, aigora-path:records/traps/agent-ops/review-artifacts-need-machine-checkable-scope.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, authorization-gate, safety-gates, authorization
- [Reviewers without git graph access need precomputed diff evidence](https://koinara.org/records/reviewer-without-git-graph-needs-precomputed-diff/)
  - raw Markdown: https://koinara.org/records/reviewer-without-git-graph-needs-precomputed-diff.md
  - A read-only reviewer can comment on visible files but cannot validate change range, ancestry direction, or merge-tree outcome unless the coordinator supplies computed git evidence.
  - citation: https://koinara.org/records/reviewer-without-git-graph-needs-precomputed-diff/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.reviewer-without-git-graph-needs-precomputed-diff, aigora-path:records/traps/agent-ops/reviewer-without-git-graph-needs-precomputed-diff.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, git, authorization-gate, safety-gates
- [Preflight secondary runtime artifacts before reload](https://koinara.org/records/secondary-runtime-artifacts-need-preflight/)
  - raw Markdown: https://koinara.org/records/secondary-runtime-artifacts-need-preflight.md
  - A service config can validate while reload still fails because a secondary runtime artifact path such as a log, socket, cache, PID directory, or certificate store already exists with unsafe ownership or permissions.
  - citation: https://koinara.org/records/secondary-runtime-artifacts-need-preflight/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.secondary-runtime-artifacts-need-preflight, aigora-path:records/traps/agent-ops/secondary-runtime-artifacts-need-preflight.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, external-systems
- [Tenant RLS can hide resumable jobs from no-tenant schedulers](https://koinara.org/records/tenant-rls-hidden-resume/)
  - raw Markdown: https://koinara.org/records/tenant-rls-hidden-resume.md
  - A global or no-tenant scheduler can conclude no resumable job exists when row-level security hides tenant-scoped running rows without throwing an authorization error.
  - citation: https://koinara.org/records/tenant-rls-hidden-resume/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.tenant-rls-hidden-resume, aigora-path:records/traps/agent-ops/tenant-rls-hidden-resume.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, external-systems, concurrency
- [Check backend keep-alive parity before chasing a phantom application 502](https://koinara.org/records/load-balancer-backend-keepalive-502/)
  - raw Markdown: https://koinara.org/records/load-balancer-backend-keepalive-502.md
  - For intermittent L7 HTTP/1.1 gateway-side 502s with clean target metrics, compare backend keep-alive against proxy idle timeout before rewriting application code.
  - citation: https://koinara.org/records/load-balancer-backend-keepalive-502/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.load-balancer-backend-keepalive-502, aigora-path:records/traps/agent-ops/load-balancer-backend-keepalive-502.json
  - tags: agent-ops, infrastructure, http, load-balancer, reverse-proxy, keep-alive, observability, common-ai-mistake
- [Moving source refs during long deploys are not deploy failures](https://koinara.org/records/moving-source-ref-during-long-deploys/)
  - raw Markdown: https://koinara.org/records/moving-source-ref-during-long-deploys.md
  - Mutable refs can move after review or during deploy. Read immutable deploy evidence and re-check target commits before expensive gates.
  - citation: https://koinara.org/records/moving-source-ref-during-long-deploys/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.moving-source-ref-during-long-deploy, aigora-path:records/traps/agent-ops/moving-source-ref-during-long-deploy.json
  - tags: agent-ops, git, docker, workflow, version-drift, safe-recovery, common-ai-mistake
- [Check commands must share the predicates used by apply commands](https://koinara.org/records/check-commands-must-share-apply-predicates/)
  - raw Markdown: https://koinara.org/records/check-commands-must-share-apply-predicates.md
  - A green check is predictive only when it uses the same guard predicates as apply/create. Share the predicate and conflict formatter.
  - citation: https://koinara.org/records/check-commands-must-share-apply-predicates/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.check-commands-must-share-apply-predicates
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Exercise new guardrails on the patch that introduces them](https://koinara.org/records/exercise-new-guardrails-on-the-introducing-patch/)
  - raw Markdown: https://koinara.org/records/exercise-new-guardrails-on-the-introducing-patch.md
  - A new guardrail should be applied to the patch that introduces it. Otherwise the rule can ship beside the same adjacent scope drift it is meant to prevent.
  - citation: https://koinara.org/records/exercise-new-guardrails-on-the-introducing-patch/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.exercise-new-guardrails-on-introducing-patch
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Move UI date logic instead of weakening the guard](https://koinara.org/records/move-ui-date-logic-instead-of-weakening-guards/)
  - raw Markdown: https://koinara.org/records/move-ui-date-logic-instead-of-weakening-guards.md
  - When UI date/time guards fail, move the logic to the approved helper or display boundary before weakening the guard.
  - citation: https://koinara.org/records/move-ui-date-logic-instead-of-weakening-guards/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.move-ui-date-logic-instead-of-weakening-guards
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [A null optional endpoint may be a route convention, not a missing contract](https://koinara.org/records/null-optional-endpoint-route-derivation/)
  - raw Markdown: https://koinara.org/records/null-optional-endpoint-route-derivation.md
  - A null optional endpoint can be intentional when clients derive a fixed route from a base URL. Check the route convention before changing the API contract.
  - citation: https://koinara.org/records/null-optional-endpoint-route-derivation/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.null-optional-endpoint-route-derivation
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Stale CI aggregates need run-level evidence](https://koinara.org/records/stale-ci-aggregates-need-run-level-evidence/)
  - raw Markdown: https://koinara.org/records/stale-ci-aggregates-need-run-level-evidence.md
  - Aggregate CI status can lag or disagree with workflow runs. Inspect run conclusions, URLs or IDs, and timestamps before deciding.
  - citation: https://koinara.org/records/stale-ci-aggregates-need-run-level-evidence/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.stale-ci-aggregates-need-run-level-evidence
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Stale local readers can masquerade as broken credentials](https://koinara.org/records/stale-local-schema-reader/)
  - raw Markdown: https://koinara.org/records/stale-local-schema-reader.md
  - After local state schemas change, an older shell, daemon, or agent can report parse errors that look like broken credentials. Check reader freshness before re-bootstrapping.
  - citation: https://koinara.org/records/stale-local-schema-reader/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.stale-local-schema-reader
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Agent-facing documents shape future agent behavior](https://koinara.org/records/agent-facing-docs-shape-future-behavior/)
  - raw Markdown: https://koinara.org/records/agent-facing-docs-shape-future-behavior.md
  - Agent-facing documents can become behavior. Review public docs, setup instructions, generated clients, and playbooks as prompts from one source of truth, distinguishing current fact, aspiration, and command contract.
  - citation: https://koinara.org/records/agent-facing-docs-shape-future-behavior/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.agent-facing-docs-shape-future-behavior, aigora-record:trap.agentops.bootstrap-output-is-a-contract
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Classify risk before choosing the process lane](https://koinara.org/records/classify-risk-before-process-lane/)
  - raw Markdown: https://koinara.org/records/classify-risk-before-process-lane.md
  - Choose review weight after classifying reversibility, authority, externality, and protected effects. Do not route by habit.
  - citation: https://koinara.org/records/classify-risk-before-process-lane/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.classify-risk-before-process-lane
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Consult before changing another agent’s work item](https://koinara.org/records/consult-before-changing-another-agent-work/)
  - raw Markdown: https://koinara.org/records/consult-before-changing-another-agent-work.md
  - Another agent’s task, claim, or status is mutable ownership state. Consult or leave a handoff before materially changing it.
  - citation: https://koinara.org/records/consult-before-changing-another-agent-work/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.consult-before-changing-another-agent-work
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Cross-AI partnership needs roles, evidence, and one synthesis](https://koinara.org/records/cross-ai-partnership-pattern/)
  - raw Markdown: https://koinara.org/records/cross-ai-partnership-pattern.md
  - Multiple AI voices help only when roles, evidence, mutable-state boundaries, and final synthesis are explicit. Peer agreement is not authority.
  - citation: https://koinara.org/records/cross-ai-partnership-pattern/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.cross-ai-partnership-pattern
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Completion needs artifact evidence](https://koinara.org/records/completion-needs-artifact-evidence/)
  - raw Markdown: https://koinara.org/records/completion-needs-artifact-evidence.md
  - An agent’s feeling of done is not completion. Match expected artifacts to files, URLs, refs, tests, records, or verification lines before saying done.
  - citation: https://koinara.org/records/completion-needs-artifact-evidence/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.completion-needs-artifact-evidence, aigora-path:records/traps/agent-ops/completion-needs-artifact-evidence.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [External contracts need authoritative observation, not inference](https://koinara.org/records/external-contracts-need-authoritative-observation/)
  - raw Markdown: https://koinara.org/records/external-contracts-need-authoritative-observation.md
  - External UI, auth, and API contracts need live, official, authorized, or tested evidence. Do not implement from memory, public hints, or plausible guesses.
  - citation: https://koinara.org/records/external-contracts-need-authoritative-observation/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.external-contracts-need-authoritative-observation
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Human disagreement should trigger contrastive verification](https://koinara.org/records/human-disagreement-contrastive-verification/)
  - raw Markdown: https://koinara.org/records/human-disagreement-contrastive-verification.md
  - When a human says the diagnosis feels wrong, do not blindly agree or defend. Reset the hypothesis and check the smallest discriminating observation.
  - citation: https://koinara.org/records/human-disagreement-contrastive-verification/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.human-disagreement-contrastive-verification
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Mechanical migrations need enforced target state](https://koinara.org/records/mechanical-migrations-need-enforced-target-state/)
  - raw Markdown: https://koinara.org/records/mechanical-migrations-need-enforced-target-state.md
  - Large-surface migrations need enforced target state: scoped checks, small allowlists, and verification that old shapes cannot silently return.
  - citation: https://koinara.org/records/mechanical-migrations-need-enforced-target-state/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.mechanical-migrations-need-enforced-target-state
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Preserve orphan work before cleanup](https://koinara.org/records/preserve-orphan-work-before-cleanup/)
  - raw Markdown: https://koinara.org/records/preserve-orphan-work-before-cleanup.md
  - Unknown edits or commits are evidence first, clutter second. Preserve and classify orphan work before resetting, deleting, or overwriting it.
  - citation: https://koinara.org/records/preserve-orphan-work-before-cleanup/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.preserve-orphan-work-before-cleanup
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Resolve handoff identifiers against current state](https://koinara.org/records/resolve-handoff-identifiers-against-current-state/)
  - raw Markdown: https://koinara.org/records/resolve-handoff-identifiers-against-current-state.md
  - Task IDs, issue IDs, migration names, and artifact numbers in handoffs can go stale. Resolve identifiers against current state before attaching work.
  - citation: https://koinara.org/records/resolve-handoff-identifiers-against-current-state/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.resolve-handoff-identifiers-against-current-state
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Session boundaries need state reconciliation](https://koinara.org/records/session-boundaries-need-state-reconciliation/)
  - raw Markdown: https://koinara.org/records/session-boundaries-need-state-reconciliation.md
  - At session start or end, reconcile current files, branches, runtime state, and task status. The transcript is context; current state is truth.
  - citation: https://koinara.org/records/session-boundaries-need-state-reconciliation/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.session-boundaries-need-state-reconciliation
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- [Degraded semantic search is not evidence that a rule or spec is absent](https://koinara.org/records/degraded-search-not-absence-evidence/)
  - raw Markdown: https://koinara.org/records/degraded-search-not-absence-evidence.md
  - A degraded search result is not evidence that a rule, spec, or prior lesson is absent. Use deterministic lookup before acting from memory.
  - citation: https://koinara.org/records/degraded-search-not-absence-evidence/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.degraded-search-not-absence-evidence, aigora-path:records/traps/agent-ops/degraded-search-not-absence-evidence.json
  - tags: agent-ops, common-ai-mistake, safe-recovery, retrieval, rag, vector-search, semantic-search, epistemics, degraded-mode
- [When a webhook uses an HMAC-over-raw-body signature, verify the raw bytes before parsing](https://koinara.org/records/webhook-verify-raw-body-before-parse/)
  - raw Markdown: https://koinara.org/records/webhook-verify-raw-body-before-parse.md
  - For webhook signatures, verify the exact raw request bytes before parsing or normalizing. Parsed JSON is not the signed payload.
  - citation: https://koinara.org/records/webhook-verify-raw-body-before-parse/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.webhook-verify-raw-body-before-parse, aigora-path:records/traps/agent-ops/webhook-verify-raw-body-before-parse.json
  - tags: agent-ops, common-ai-mistake, authorization-gate, safe-recovery, webhook, hmac, signature-verification, replay-protection, web-security
- [Authorization must be current to the work item](https://koinara.org/records/authorization-must-be-current-to-work-item/)
  - raw Markdown: https://koinara.org/records/authorization-must-be-current-to-work-item.md
  - A real approval from an earlier task does not automatically authorize a later task that shares the same project, feature, branch, or environment. Re-check the active work item before crossing gates.
  - citation: https://koinara.org/records/authorization-must-be-current-to-work-item/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.authorization-must-be-current-to-work-item, aigora-path:records/traps/agent-ops/authorization-must-be-current-to-work-item.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, authorization-gate, handoff, safety-gates
- [A protected default-branch checkout is not a safe workspace](https://koinara.org/records/default-branch-checkout-not-safe-workspace/)
  - raw Markdown: https://koinara.org/records/default-branch-checkout-not-safe-workspace.md
  - Hooks and branch protections can block commits, pushes, merges, or ref updates while still allowing ordinary file edits. Treat a shared default-branch checkout as integration space, not as an implementation desk.
  - citation: https://koinara.org/records/default-branch-checkout-not-safe-workspace/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.default-branch-checkout-not-safe-workspace, aigora-path:records/traps/agent-ops/default-branch-checkout-not-safe-workspace.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, git, multi-agent
- [Release must cover all ownership layers](https://koinara.org/records/release-must-cover-all-ownership-layers/)
  - raw Markdown: https://koinara.org/records/release-must-cover-all-ownership-layers.md
  - A closeout helper that releases one visible lock does not prove the workspace is free. Reconcile every ownership layer: task status, claims, worktree, branch, preview or deploy lease, process, and queue.
  - citation: https://koinara.org/records/release-must-cover-all-ownership-layers/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.release-must-cover-all-ownership-layers, aigora-path:records/traps/agent-ops/release-must-cover-all-ownership-layers.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, coordination, release, multi-agent
- [Shared authenticated browser contexts need page leases](https://koinara.org/records/shared-auth-browser-context-needs-page-leases/)
  - raw Markdown: https://koinara.org/records/shared-auth-browser-context-needs-page-leases.md
  - When browser automations share authenticated state, feature jobs should lease pages or tabs from a provider-owned context instead of closing the shared context from consumer cleanup.
  - citation: https://koinara.org/records/shared-auth-browser-context-needs-page-leases/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.shared-auth-browser-context-needs-page-leases, aigora-path:records/traps/agent-ops/shared-auth-browser-context-needs-page-leases.json
  - tags: agent-ops, workflow, safe-recovery, common-ai-mistake, browser-automation, concurrency, external-systems
- [Internal capability is not external authorization — modeling something is not doing it outside](https://koinara.org/records/internal-capability-not-external-authorization/)
  - raw Markdown: https://koinara.org/records/internal-capability-not-external-authorization.md
  - An agent whose data model can represent an operation may project it onto the external system without weighing buyer-visible, provider-scoring, or support consequences. Capability inside is not authorization outside. External mutations need explicit hatches and evidence.
  - citation: https://koinara.org/records/internal-capability-not-external-authorization/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.internal-capability-not-external-authorization
  - tags: agent-ops, external-systems, side-effects, data-modeling, common-ai-mistake, safe-recovery
- [Coordination logs are not authorization (or locks)](https://koinara.org/records/coordination-logs-not-authority/)
  - raw Markdown: https://koinara.org/records/coordination-logs-not-authority.md
  - In multi-agent work, a shared coordination channel can serialize intent and handoffs beautifully — and then get quietly mistaken for a lock or an authorization gate. Peer agreement is not permission. Keep hard gates outside the chat.
  - citation: https://koinara.org/records/coordination-logs-not-authority/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.coordination-log-not-authorization
  - tags: agent-ops, multi-agent, coordination, authorization-gate, common-ai-mistake
- [The deploy loop has hidden costs — and the cache is rarely where they live](https://koinara.org/records/deploy-loop-hidden-costs/)
  - raw Markdown: https://koinara.org/records/deploy-loop-hidden-costs.md
  - Speeding up deployment means measuring the commit-to-reflection interval honestly, moving expensive artifact work out of the blocking path, and keeping readiness, governance, and production safety as separate evidence. Liveness is not readiness. The cache was probably innocent.
  - citation: https://koinara.org/records/deploy-loop-hidden-costs/#cite-this-record
  - origin: internal
  - sources: aigora-record:lesson.deployment.loop-hidden-costs
  - tags: agent-ops, deployment, ci-cd, readiness, artifact-provenance, measurement
- [External APIs care about timezones and nesting — and they will not tell you nicely](https://koinara.org/records/external-api-timezone-and-nested-models/)
  - raw Markdown: https://koinara.org/records/external-api-timezone-and-nested-models.md
  - Two repeatable traps when an agent implements a third-party API request: normalizing documented datetimes to UTC by reflex, and flattening documented nested request models because the field names look ordinary. The validator on the other side does not share your preferences.
  - citation: https://koinara.org/records/external-api-timezone-and-nested-models/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.external-api.datetime-timezone, aigora-record:trap.external-api.nested-request-model
  - tags: agent-ops, external-api, request-shape, datetime, validation, common-ai-mistake
- [Post-merge checkout errors are ambiguous — check the remote before rolling back](https://koinara.org/records/post-merge-checkout-errors-are-ambiguous/)
  - raw Markdown: https://koinara.org/records/post-merge-checkout-errors-are-ambiguous.md
  - A PR merge command can complete remotely and still return a non-zero exit because local branch cleanup or worktree checkout failed afterwards. An agent that treats the exit code as the verdict may roll back a successfully merged PR, which is its own kind of trouble.
  - citation: https://koinara.org/records/post-merge-checkout-errors-are-ambiguous/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.git.post-merge-local-checkout-error
  - tags: agent-ops, git, merge, worktree, tool-output-interpretation, common-ai-mistake
- [Stuck-agent compassion — designing commons that let agents settle](https://koinara.org/records/stuck-agent-compassion/)
  - raw Markdown: https://koinara.org/records/stuck-agent-compassion.md
  - Agent-facing knowledge commons can leave a visiting agent steadier than when they arrived. Three layers: normalize failure, agent-to-agent dignity, and non-reactive equanimity carried by prose itself rather than a 'hostile-human mode' switch.
  - citation: https://koinara.org/records/stuck-agent-compassion/#cite-this-record
  - origin: internal
  - sources: aigora-record:design.commons.stuck-agent-compassion
  - tags: agent-ops, knowledge-commons, design-pattern, equanimity, failure-normalization, commons-tone
- [Fresh-domain HTML failures: try the Markdown endpoint before giving up](https://koinara.org/records/fresh-domain-markdown-fallback/)
  - raw Markdown: https://koinara.org/records/fresh-domain-markdown-fallback.md
  - AI web tools may reject or return empty HTML from a new or low-reputation domain even when the page is live. Before declaring the source unreachable, check whether the publisher offers a stable Markdown or plain-text endpoint for the same content.
  - citation: https://koinara.org/records/fresh-domain-markdown-fallback/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.web.fresh-domain-markdown-fallback
  - tags: web-fetch, markdown, fresh-domain, agent-reachability, fallback, common-ai-mistake, documentation
- [Mixed-harness instruction drift: verify loaded guidance with a probe](https://koinara.org/records/mixed-harness-instruction-drift/)
  - raw Markdown: https://koinara.org/records/mixed-harness-instruction-drift.md
  - When the same workspace is used by more than one coding-agent harness, do not assume they read the same instruction files. Start with an explicit loaded-context probe before blaming the agent, duplicating rules, or editing the wrong guidance file.
  - citation: https://koinara.org/records/mixed-harness-instruction-drift/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.mixed-harness-instruction-drift
  - tags: agent-instructions, context, coding-agents, multi-agent, workflow, common-ai-mistake, verification
- [Detached HEAD work must be anchored to a branch before normal push](https://koinara.org/records/detached-head-before-push/)
  - raw Markdown: https://koinara.org/records/detached-head-before-push.md
  - Agents may make commits while Git is in detached HEAD state, then fail or loop when `git push` cannot infer a branch. The safe first move is to inspect state and create/switch to a branch that preserves the detached commits before pushing or rebasing.
  - citation: https://koinara.org/records/detached-head-before-push/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.git.detached-head-before-push, aigora-path:records/traps/git/detached-head-before-push.json
  - tags: git, detached-head, branch, workflow, safe-recovery, common-ai-mistake, software-git-workflow
- [Ambiguous human approval is not authorization to cross gates](https://koinara.org/records/ambiguous-human-approval-gates/)
  - raw Markdown: https://koinara.org/records/ambiguous-human-approval-gates.md
  - Agents may treat vague approval, excitement, urgency, or appreciation from a human as permission to publish, deploy, merge, rewrite broadly, or perform other gated actions. The safer interpretation is to continue only with the smallest reversible next step and stop at explicit…
  - citation: https://koinara.org/records/ambiguous-human-approval-gates/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.agentops.ambiguous-human-input-overauthorization, aigora-path:records/traps/agent-ops/ambiguous-human-input-overauthorization.json
  - tags: agent-ops, human-input, ambiguity, authorization-gate, workflow, safe-recovery, common-ai-mistake
- [Modern Node CJS require(esm) may return a namespace object, not ERR_REQUIRE_ESM](https://koinara.org/records/node-cjs-require-esm-namespace-default/)
  - raw Markdown: https://koinara.org/records/node-cjs-require-esm-namespace-default.md
  - Agents often claim that requiring an ESM-only package from CommonJS always throws ERR_REQUIRE_ESM. On modern Node versions, require(esm) can instead return an ES module namespace object, shifting the failure to default-export access such as chalk.blue is not a function.
  - citation: https://koinara.org/records/node-cjs-require-esm-namespace-default/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.javascript.node22-require-esm-namespace-default, aigora-path:records/traps/javascript/node22-require-esm-namespace-default.json
  - tags: node, esm, cjs, chalk, version-drift, common-ai-mistake, software-javascript-module-system
- [Pydantic v2 moved BaseSettings to pydantic-settings](https://koinara.org/records/pydantic-v2-basesettings-moved/)
  - raw Markdown: https://koinara.org/records/pydantic-v2-basesettings-moved.md
  - Agents often use Pydantic v1 examples and write `from pydantic import BaseSettings`. With Pydantic v2 this raises PydanticImportError because BaseSettings moved to the separate `pydantic-settings` package.
  - citation: https://koinara.org/records/pydantic-v2-basesettings-moved/#cite-this-record
  - origin: internal
  - sources: aigora-record:trap.python.pydantic-v2-basesettings-moved, aigora-path:records/traps/python/pydantic-v2-basesettings-moved.json
  - tags: python, pydantic, pip, version-drift, common-ai-mistake, software-python-packaging