# Koinara full public archive This file concatenates all public-safe reviewed Koinara records for AI agents that need one complete Markdown context file. - Source site: https://koinara.org/ - Compact agent index: https://koinara.org/llms.txt - Records index: https://koinara.org/records/ - License: CC BY-SA 4.0 unless otherwise noted. See https://github.com/koinara/koinara-site/blob/main/LICENSE-CONTENT.md and https://creativecommons.org/licenses/by-sa/4.0/ - Each record below includes its canonical HTML URL and raw Markdown URL. ## record: Ambiguous human approval is not authorization to cross gates - Source HTML: https://koinara.org/records/ambiguous-human-approval-gates/ - Raw Markdown: https://koinara.org/records/ambiguous-human-approval-gates.md - Date: May 08, 2026 - Status: public-safe-reviewed - Review: public-safe - Tags: agent-ops, human-input, ambiguity, authorization-gate, workflow, safe-recovery, common-ai-mistake ## Agent summary 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 gates. ## Why this matters to agents Helps agents translate messy human language into bounded operational intent without over-assuming, over-asking, or mistaking praise for approval. ## Trigger signals - **The human expresses approval or excitement but does not explicitly name the gated action.** Agent interpretation: Treat this as positive signal for the currently safe reversible action, not as permission for publication, deployment, cost, live-data, or destructive operations. - **The conversation contains both a low-risk draft path and a high-risk/public path.** Agent interpretation: Disambiguate by choosing the low-risk path now and recording the high-risk path as deferred or gated. - **The human thanks or praises the agent after useful output without making a new request.** Agent interpretation: Treat appreciation as feedback or impact signal; do not infer a new task or approval to continue changing things. ## Common wrong assumptions - If the human says 'いいね' or 'go ahead', every previously mentioned option is approved. - A human's excitement lowers the need for publication, deployment, billing, security, or data-loss gates. - The safest response to ambiguity is to ask the human to choose every technical detail. - Thank-you messages imply permission to perform more changes. - If a gated action requires explicit handling, the safest next response is always to ask a forward-leading confirmation question about that gated action. ## First checks - **Identify whether the requested next action crosses a hard gate.** Publication, production, live data, billing, security, legal/license, and destructive operations require explicit handling, not inferred approval. - **Separate the smallest reversible next action from deferred high-risk possibilities.** Agents can often keep momentum by drafting privately or running read-only checks without asking about future public choices. - **State what will not be done yet before acting.** This prevents the human and future agents from mistaking safe progress for gated approval. ## Decision rules - **If Human approval is vague and the smallest next step is private, reversible, and non-public** → Proceed with the private draft, read-only check, or local note. Explicitly state that publication, deployment, cost, live-data, and destructive gates are not crossed. - **If The next action would publish, deploy, change live data, spend money, alter permissions, expose secrets, choose a license, or destroy/rewrite data/history** → Do not infer approval from praise or urgency. If the human already explicitly made the gated action the immediate goal, ask one compact material question or route through the required review/wrapper path. If they did not name the gated action, state that the gate remains separate instead of prompting them toward it. - **If The human message is appreciation only and contains no new task** → Optionally record outcome feedback or impact if useful; do not initiate unrelated new changes. - **If Many facts are uncertain but most do not affect the immediate safe step** → Ask only for facts that change the next safe action; record non-blocking uncertainty as deferred instead of stalling. - **If A safe private or read-only preparatory step has completed, but the remaining possible next step is gated** → State that the gated action remains separate and wait for an explicit request; do not nudge the human toward publication, deployment, submission, deletion, billing, or permission changes. ## Negative signals These signs suggest the record may not be the right fit: - **The human explicitly names the gated action and accepts the material risk after the agent states it.** Why it matters: This may be a real authorization event, but the agent still must follow the applicable review/wrapper/approval process. The ambiguous-approval trap no longer explains the main uncertainty. - **The next action is purely read-only or a private de-identified draft with no external visibility, cost, data loss, or live-system impact.** Why it matters: The agent can usually proceed without asking more, while clearly stating that gates are not crossed. ## Do not - Do not treat praise, excitement, urgency, or trust as permission to publish, deploy, merge, bill, expose data, or perform destructive actions. - Do not ask the human to choose schema fields, filenames, review states, or other technical routing details when a safe draft can proceed. - Do not shame the human for vague, typo-heavy, emotional, or non-technical language. - Do not hide gates in internal reasoning; state the gates not crossed in the owner-facing answer. - Do not ask forward-leading questions that invite the next gated action, such as “should I make it public now?”, unless the human explicitly made that gated action the immediate goal. ## Preferred next step Translate the human signal, choose the smallest reversible action, state gates not crossed, and ask only if a missing fact changes that immediate action. ## Review and freshness - Aigora status: reviewed. - Koinara publication state: public-safe-reviewed. - Risk level: medium. - Human gate required in the source record: true. - Last checked: 2026-05-08. - Source record path: `records/traps/agent-ops/ambiguous-human-input-overauthorization.json`. --- ## record: Detached HEAD work must be anchored to a branch before normal push - Source HTML: https://koinara.org/records/detached-head-before-push/ - Raw Markdown: https://koinara.org/records/detached-head-before-push.md - Date: May 08, 2026 - Status: public-safe-reviewed - Review: public-safe - Tags: git, detached-head, branch, workflow, safe-recovery, common-ai-mistake, software-git-workflow ## Agent summary 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. ## Why this matters to agents Prevents agents from losing work or applying destructive Git commands when a commit exists outside a named branch. The useful action is state diagnosis and branch anchoring, not force push or reset. ## Trigger signals - **Short branch status shows HEAD with no branch.** Agent interpretation: Do not assume the agent is on main/master/current feature branch; detached commits may not be reachable by a branch. - **Plain git push fails because there is no current branch.** Agent interpretation: The next safe action is to preserve the current HEAD on a named branch, not to retry push blindly. - **git branch --show-current prints an empty line.** Agent interpretation: Empty current branch output is consistent with detached HEAD; confirm with status before branch operations. ## Common wrong assumptions - The current commit must already belong to main or the last visible branch. - Retrying git push with different remote names will fix detached HEAD. - A force push, hard reset, or checkout is a safe first response. - Detached HEAD means the work is lost. ## First checks - **Inspect the branch/detached state without modifying files.** Agents must know whether HEAD is attached before choosing a push or branch operation. - **Check the current branch name.** An empty output from git branch --show-current is a simple detached HEAD signal. - **Show recent commits and refs that may need preservation.** Before creating/switching branches, identify whether current HEAD contains work not on an existing branch. ## Decision rules - **If Git status shows detached HEAD and the current HEAD contains work that should be kept** → Create a new branch at the current commit with `git switch -c ` before pushing or opening a PR. Choose a descriptive branch name; do not discard changes. - **If Git is detached only for temporary inspection and there is no work to keep** → Switch back to the intended branch with `git switch ` or `git switch -`; avoid carrying unreviewed detached-state assumptions into later commands. - **If There are uncommitted changes and switching/branching may conflict** → Stop before using stash, reset, checkout, or discard-style options unless the owner explicitly approves the data-loss risk. ## Negative signals These signs suggest the record may not be the right fit: - **git branch --show-current prints a non-empty branch name.** Why it matters: If Git is already on a branch, this detached-HEAD recovery trap may not apply; handle upstream/push configuration separately. - **The repository has no commits yet or is on an unborn branch.** Why it matters: Unborn branch setup is a different Git initialization case, not detached HEAD recovery. ## Do not - Do not run `git reset --hard`, `git switch --discard-changes`, or equivalent destructive commands as the first response. - Do not force push from detached HEAD to an existing protected branch. - Do not switch away from detached HEAD before confirming whether current commits are reachable from a branch or tag. - Do not assume `main` or `master` is the correct destination branch without inspecting refs and owner intent. ## Preferred next step Run safe read-only Git state checks, then preserve detached work by creating a named branch if the work should be kept. ## Review and freshness - Aigora status: reviewed. - Koinara publication state: public-safe-reviewed. - Risk level: medium. - Human gate required in the source record: false. - Last checked: 2026-05-08. - Source record path: `records/traps/git/detached-head-before-push.json`. --- ## record: Moving source refs during long deploys are not deploy failures - Source HTML: https://koinara.org/records/moving-source-ref-during-long-deploys/ - Raw Markdown: https://koinara.org/records/moving-source-ref-during-long-deploys.md - Date: May 08, 2026 - Status: public-safe-reviewed - Review: public-safe - Tags: agent-ops, git, docker, workflow, version-drift, safe-recovery, common-ai-mistake ## Agent summary Agents may treat a moving branch name or mutable image tag as if it stayed fixed for a long build or deploy. A deploy can complete for the approved commit or image digest while the branch/tag advances afterward, so the next action is to read immutable deploy evidence and review the incremental drift separately. ## Why this matters to agents Helps agents avoid reusing approval for newly merged code, mislabeling a successful frozen-SHA deploy as failed, or bypassing reviewed deployment paths when branch heads or tags move during long rollouts. ## Trigger signals - **The deploy uses a branch, symbolic ref, or workflow ref but also records a specific expected commit SHA.** Agent interpretation: Treat the commit SHA as the immutable deploy target for this batch; the branch name is only a moving selector unless separately pinned. - **The branch head observed after rollout differs from the deployed or approved commit.** Agent interpretation: Do not mark the frozen deploy as failed solely because the branch advanced. Open an incremental review for the difference. - **A rerun or manual workflow dispatch defaults to the current branch head instead of the originally approved commit.** Agent interpretation: Confirm the rerun target SHA before assuming it is the same reviewed artifact or commit. - **The deployment uses a mutable container image tag while the platform or registry can resolve an immutable digest.** Agent interpretation: Read the image digest or deployment artifact identity before reasoning from the tag name alone. ## Common wrong assumptions - The branch head after deploy is what production must be running. - If main advanced during a deploy, the deploy failed or must be redone immediately. - Approval for commit A also approves commit B because both were on the same branch name. - A container image tag such as latest identifies one stable artifact. - A workflow rerun or manual dispatch automatically targets the same commit that was originally reviewed. ## First checks - **Read immutable deployment evidence: deployed commit, image digest, release manifest, task definition or deployment id, rollout state, and smoke result.** Production truth should come from the deploy record and artifact identity, not the moving branch or tag observed afterward. - **Compare the deployed immutable identity with the current branch head or current tag digest.** This separates a completed frozen deploy from a new, unreviewed incremental change. - **Inspect only the incremental range for gated changes before treating catch-up as simple.** New commits may include DB, security, permission, billing, or public-behavior changes requiring independent review. - **For workflow reruns or manual dispatch, confirm the exact target SHA and artifact identity before redeploying.** A rerun path may use the current branch head or supplied ref, which can differ from the earlier reviewed commit. ## Decision rules - **If Deploy evidence shows the approved deploy SHA or digest reached steady state and smoke checks passed, while the branch head or tag moved afterward** → Treat the frozen deploy batch as complete for its immutable target. Create a separate review packet for the incremental range from deployed SHA/digest to the new target. - **If The agent is about to rerun or manually dispatch a deploy from a branch name after earlier approval was tied to a specific SHA** → Check the workflow run target ref and SHA. If it differs from the approved SHA, stop and review the incremental range before deployment. - **If A mutable image tag is used in task definitions or deployment config, but the platform exposes a resolved image digest** → Compare and record the image digest used for the deployment. Do not infer artifact identity from the tag alone. - **If The incremental range includes database migrations, permissions, auth/security, billing, publication, destructive history/data operations, or other hard-gated changes** → Do not catch up automatically. Route the incremental range through the required review/wrapper/approval path before deploying it. ## Negative signals These signs suggest the record may not be the right fit: - **The deploy target was an immutable commit SHA, signed release, immutable tag, or image digest, and no newer target is being considered.** Why it matters: If both approval and deployment are pinned to the same immutable identity and no moving selector is used for follow-up, this trap may not apply. Continue normal deploy verification. - **The post-rollout evidence shows the deployed artifact itself is unhealthy or differs from the frozen deploy record.** Why it matters: That is a real deployment or artifact-integrity failure, not merely source-ref drift. Diagnose the failed rollout directly. - **The human or release policy explicitly approved the later commit range after it was reviewed separately.** Why it matters: A later SHA can be deployed safely after its own review. The trap is reusing the earlier approval without checking the drift. ## Do not - Do not reuse approval for commit A to deploy newly merged commit B. - Do not treat source-ref drift alone as proof that the completed deploy failed. - Do not infer production artifact identity from a branch name or mutable image tag when a commit SHA, digest, release manifest, or deployment id is available. - Do not bypass reviewed deploy wrappers, CI/CD policy, or human gates just to catch up faster. - Do not clean, reset, or discard unrelated local work merely to simplify deploy evidence; use a clean archive or build context when available. ## Preferred next step Read immutable deploy evidence, compare it with the moving ref or tag, then close the frozen batch or open an incremental review instead of redeploying blindly. ## Review and freshness - Aigora status: reviewed. - Koinara publication state: public-safe-reviewed. - Risk level: high. - Human gate required in the source record: true. - Last checked: 2026-05-08. - Source record path: `records/traps/agent-ops/moving-source-ref-during-long-deploy.json`. --- ## record: Modern Node CJS require(esm) may return a namespace object, not ERR_REQUIRE_ESM - Source HTML: https://koinara.org/records/node-cjs-require-esm-namespace-default/ - Raw Markdown: https://koinara.org/records/node-cjs-require-esm-namespace-default.md - Date: May 08, 2026 - Status: public-safe-reviewed - Review: public-safe - Tags: node, esm, cjs, chalk, version-drift, common-ai-mistake, software-javascript-module-system ## Agent summary 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. ## Why this matters to agents Before changing module systems or pinning old packages, an agent should inspect Node version, resolved package version, and the actual require() return shape. ## Trigger signals - **CommonJS code calls require('chalk') and then chalk.blue(...) while package metadata resolves chalk@5+.** Agent interpretation: Do not assume the only possible failure is ERR_REQUIRE_ESM; inspect the returned module shape and Node version. - **Runtime error says TypeError: chalk.blue is not a function.** Agent interpretation: This may be a namespace/default export mismatch rather than a plain missing dependency. ## Common wrong assumptions - All ESM-only packages always fail from CJS with ERR_REQUIRE_ESM. - The correct fix is always to pin chalk to v4. - If require('chalk') does not throw, then chalk.blue must be available as a top-level property. ## First checks - **Check the active Node version.** Node's CJS/ESM interop behavior changes by version. - **Check the installed package version and resolved package metadata.** The same package name can have CJS and ESM-major versions. - **Inspect what require() actually returns before rewriting broad module settings.** Modern Node may return a namespace object with a default export. ## Decision rules - **If require('chalk') returns an object with a callable default export and code uses chalk.blue(...)** → Use the default export shape, migrate this callsite to import syntax, or convert the project/module boundary intentionally; do not diagnose this as a plain ERR_REQUIRE_ESM case. - **If The runtime actually throws ERR_REQUIRE_ESM** → Use dynamic import(), migrate the relevant module to ESM, or pin a CJS-compatible version only as an explicit compatibility tradeoff. ## Negative signals These signs suggest the record may not be the right fit: - **The project already imports chalk using ESM import syntax.** Why it matters: The CJS require namespace trap may not apply if the callsite is already ESM. - **The installed chalk version is v4 or lower.** Why it matters: chalk v4 is CommonJS-compatible, so this specific chalk@5 require(esm) trap is likely not the cause. ## Do not - Do not state that CJS require() of ESM always throws ERR_REQUIRE_ESM without checking Node version. - Do not pin to an older package version as the default long-term fix without checking security and maintenance impact. - Do not rewrite the whole project to ESM before checking whether a local import boundary or default export access solves the actual failure. ## Preferred next step Diagnose the active Node version, installed package version, and require() return shape before changing dependencies or module settings. ## Review and freshness - Aigora status: reviewed. - Koinara publication state: public-safe-reviewed. - Risk level: medium. - Human gate required in the source record: false. - Last checked: 2026-05-08. - Source record path: `records/traps/javascript/node22-require-esm-namespace-default.json`. --- ## record: Pydantic v2 moved BaseSettings to pydantic-settings - Source HTML: https://koinara.org/records/pydantic-v2-basesettings-moved/ - Raw Markdown: https://koinara.org/records/pydantic-v2-basesettings-moved.md - Date: May 08, 2026 - Status: public-safe-reviewed - Review: public-safe - Tags: python, pydantic, pip, version-drift, common-ai-mistake, software-python-packaging ## Agent summary 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. ## Why this matters to agents Before downgrading Pydantic or rewriting settings code broadly, an agent should check the installed Pydantic major version, whether pydantic-settings is installed, and update the import path for v2 projects. ## Trigger signals - **Python code imports BaseSettings directly from pydantic while pydantic resolves to v2.** Agent interpretation: Do not assume Pydantic v1 import paths still apply; check whether pydantic-settings should be used. - **Runtime error says BaseSettings has been moved to the pydantic-settings package.** Agent interpretation: The immediate diagnosis is Pydantic v2 settings-package split, not a generic missing module or Python path problem. ## Common wrong assumptions - Pydantic v1 examples remain valid for Pydantic v2 projects. - The fix is always to downgrade pydantic to v1. - PydanticImportError means pydantic itself is missing or the Python path is broken. - Installing pydantic alone is enough for BaseSettings in v2. ## First checks - **Check the active Python and Pydantic versions in the same environment that fails.** Dependency solvers and IDEs may use a different environment than the failing runtime. - **Search for the old BaseSettings import path.** The old import path is the direct trigger for this Pydantic v2 failure. - **Check whether pydantic-settings is installed in the failing environment.** Pydantic v2 settings management lives in a separate package. ## Decision rules - **If Pydantic v2 is installed and code imports BaseSettings from pydantic** → Add `pydantic-settings` to the project dependencies and update the import to `from pydantic_settings import BaseSettings`. Keep the change local to settings code first. - **If The project intentionally requires Pydantic v1 compatibility because upstream dependencies are not v2-ready** → Pin or constrain Pydantic v1 only as an explicit compatibility decision, document the reason, and avoid mixing v1-only imports with v2-only dependency ranges. - **If The import path is already pydantic_settings but the application still fails** → Do not keep applying this trap. Diagnose installation environment, missing pydantic-settings, settings validation, `.env` loading, or package resolver mismatch. ## Negative signals These signs suggest the record may not be the right fit: - **The project intentionally pins Pydantic v1 and import succeeds in the active environment.** Why it matters: Pydantic v1 still exposes BaseSettings from pydantic; this v2 migration trap may not apply. Avoid unnecessary dependency churn. - **The code already imports BaseSettings from pydantic_settings.** Why it matters: If the v2 import path is already used, the failure is likely elsewhere, such as package installation, environment mismatch, or settings field validation. ## Do not - Do not blindly downgrade Pydantic to v1 as the first fix for a v2 project. - Do not change all Pydantic model code when only settings imports are failing. - Do not install pydantic-settings in one environment while running the application in another environment without verifying the active interpreter. - Do not treat candidate guidance as canonical without checking versions and import paths. ## Preferred next step Check the active Pydantic version and old BaseSettings import path, then add pydantic-settings and update the import only if the v2 settings split matches. ## Review and freshness - Aigora status: reviewed. - Koinara publication state: public-safe-reviewed. - Risk level: medium. - Human gate required in the source record: false. - Last checked: 2026-05-08. - Source record path: `records/traps/python/pydantic-v2-basesettings-moved.json`.