docs(agents): the Checkout residency section now contradicts the serialized-checkouts rule in agentic-os #30

New issue

Closed

opened 2026-08-20 06:16:31 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-20 06:16:31 +00:00

Member

AGENTS.md in this repo carries a ## Checkout residency section stating:

This repo is not in Agent Compose's repository-plan.yaml, so it has no resident checkout under ~/projects/<owner>/. That is intentional. Work it from a task-scoped temporary clone, and remove that clone once the work lands.

A rule that landed in agentic-os AGENTS.md explicitly inverts that for this repo. Under ### Serialized checkouts on native Windows, coilyco-gaming/eco-app, coilyco-gaming/eco-mods, and coilyco-gaming/eco-ops are worked in the canonical checkout under the projects root, never in a session shadow, a linked worktree, or a temporary clone, and are treated as belonging on disk whether or not the residency plan lists them. The stated reason is that Unity assets and the Eco server state they drive take one writer at a time, so a second checkout produces a corrupt merge rather than isolation.

Why this matters rather than being cosmetic

The two rules do not merely disagree in emphasis, they prescribe opposite actions for the same repository on the same host. An agent reading this repo's AGENTS.md first will make a temporary clone, which is exactly the thing the newer rule exists to prevent. The failure it produces is a corrupt asset merge, not a tidy error.

The residency paragraph also carries a durability warning built on the temp-clone premise, namely that a temporary root can be purged at any time so the remote is the only durable artifact. That reasoning no longer applies to a canonical resident checkout and should not survive the edit unchanged.

Suggested shape

Replace the section with one that defers to the serialized-checkouts rule for native Windows, and states the residency expectation directly rather than deriving it from absence in repository-plan.yaml. Keep the commit-and-push-before-pausing discipline, since that holds for its own reasons.

Worth checking whether eco-app and eco-ops carry the same stale paragraph, since all three were covered by the same inversion.

`AGENTS.md` in this repo carries a `## Checkout residency` section stating: > This repo is not in Agent Compose's `repository-plan.yaml`, so it has no resident checkout under `~/projects/<owner>/`. That is intentional. Work it from a task-scoped temporary clone, and remove that clone once the work lands. A rule that landed in `agentic-os` AGENTS.md explicitly inverts that for this repo. Under `### Serialized checkouts on native Windows`, `coilyco-gaming/eco-app`, `coilyco-gaming/eco-mods`, and `coilyco-gaming/eco-ops` are worked in the canonical checkout under the projects root, never in a session shadow, a linked worktree, or a temporary clone, and are treated as belonging on disk whether or not the residency plan lists them. The stated reason is that Unity assets and the Eco server state they drive take one writer at a time, so a second checkout produces a corrupt merge rather than isolation. ## Why this matters rather than being cosmetic The two rules do not merely disagree in emphasis, they prescribe opposite actions for the same repository on the same host. An agent reading this repo's AGENTS.md first will make a temporary clone, which is exactly the thing the newer rule exists to prevent. The failure it produces is a corrupt asset merge, not a tidy error. The residency paragraph also carries a durability warning built on the temp-clone premise, namely that a temporary root can be purged at any time so the remote is the only durable artifact. That reasoning no longer applies to a canonical resident checkout and should not survive the edit unchanged. ## Suggested shape Replace the section with one that defers to the serialized-checkouts rule for native Windows, and states the residency expectation directly rather than deriving it from absence in `repository-plan.yaml`. Keep the commit-and-push-before-pausing discipline, since that holds for its own reasons. Worth checking whether `eco-app` and `eco-ops` carry the same stale paragraph, since all three were covered by the same inversion.

coilyco-ops referenced this issue

2026-08-20 06:31:32 +00:00

pre-commit fails on four catalog hooks, and the pyproject opt-out written for two of them is inert #31