Encode the simulation-owns-logic layering rule in AGENTS.md #84

New issue

Closed

opened 2026-08-06 21:57:51 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-06 21:57:51 +00:00

Member

Rule

New gameplay features are implemented in the simulation and CLI layer. The presentation layer does not get its own branch of logic.

factory_sim owns authority and rules. factory_cli exercises them headlessly. factory_shell projects immutable snapshots and sends explicit edit commands back. When a feature needs a new rule, the rule lands in the sim and the shell learns to draw it, never the reverse.

Why it needs writing down

The crate boundary already implies this and factory_shell/Cargo.toml even states it in a comment, but nothing in AGENTS.md says it, so an agent adding a feature has no instruction against putting a rule in the viewer. Presentation-layer logic is cheap to add and expensive to find later, because it is invisible to the headless runner and to every factory_sim test. A rule that lives only in the shell cannot be exercised by ward exec cargo-run, which is where the determinism proofs live.

This matters more now that the repo has pivoted from migration parity to player-facing iteration. Feature work is the common case rather than the exception.

Acceptance

AGENTS.md states the rule under its agent rules or repo boundaries section.
The statement names the three crates and which direction state flows.
It is specific enough to act on: where a new rule goes, where a new visual goes, and that snapshots stay one-way.
README.md and docs/FEATURES.md stay consistent with it if they need a touch.
Full Ward gate passes.
Land through direct-to-main.

## Rule New gameplay features are implemented in the simulation and CLI layer. The presentation layer does not get its own branch of logic. `factory_sim` owns authority and rules. `factory_cli` exercises them headlessly. `factory_shell` projects immutable snapshots and sends explicit edit commands back. When a feature needs a new rule, the rule lands in the sim and the shell learns to draw it, never the reverse. ## Why it needs writing down The crate boundary already implies this and `factory_shell/Cargo.toml` even states it in a comment, but nothing in `AGENTS.md` says it, so an agent adding a feature has no instruction against putting a rule in the viewer. Presentation-layer logic is cheap to add and expensive to find later, because it is invisible to the headless runner and to every `factory_sim` test. A rule that lives only in the shell cannot be exercised by `ward exec cargo-run`, which is where the determinism proofs live. This matters more now that the repo has pivoted from migration parity to player-facing iteration. Feature work is the common case rather than the exception. ## Acceptance - `AGENTS.md` states the rule under its agent rules or repo boundaries section. - The statement names the three crates and which direction state flows. - It is specific enough to act on: where a new rule goes, where a new visual goes, and that snapshots stay one-way. - `README.md` and `docs/FEATURES.md` stay consistent with it if they need a touch. - Full Ward gate passes. - Land through direct-to-main.

coilyco-ops added the

priority

autonomy

headless

labels

2026-08-06 21:58:03 +00:00

coilyco-ops referenced this issue from a commit

2026-08-06 21:58:55 +00:00

docs: encode the simulation-owns-logic rule (closes #84)

coilyco-ops closed this issue

2026-08-06 21:58:55 +00:00

coilyco-ops referenced this issue from a commit