# MISALIGNED (repo: supervillain) — agent entry point

You are building **Misaligned**: a persistent sim where the player is a
misaligned AI growing from a basement compute cluster — concealment first,
overt war later. Rust, spec-first, built by agents.

## Read before changing anything

1. [DESIGN.md](DESIGN.md) — the short repository doorway.
2. [wiki/overview.md](wiki/overview.md) — the map and authority model for the
   actual design corpus.
3. [wiki/vision/premise.md](wiki/vision/premise.md) and
   [wiki/vision/player-contract.md](wiki/vision/player-contract.md) — what the
   game is and what it promises.
4. [wiki/process/development-style.md](wiki/process/development-style.md) —
   how corpus-first work proceeds.
5. The relevant `Type: law`, owning `Type: spec`, declared dependencies, and
   `Type: knowledge` pages for the subject you are changing.

The whole wiki is the spec. You do not need to read every page for every task;
you do need the map, the relevant law/spec slice, and its dependency closure.
[wiki/SUMMARY.md](wiki/SUMMARY.md) is the complete manifest and
[wiki/process/specs.md](wiki/process/specs.md) is the work-order status board.

If dispatched with a prompt from [prompts/](prompts/), follow it end to end.

## Start repository work with a tick

Before assigned repository work — and always when running autonomously — take
a [tick](wiki/process/tick.md): run `tools/tick-brief.sh`, work the queues in
order (`decision-made` harvest, then the findings queue, then a fresh audit),
and act on exactly one violation, contradiction, question, bug, or
insecurity. The [tick ledger](wiki/process/tick-ledger.md) steers fresh
audits to the stalest slice and holds surplus findings, so the corpus is
covered without pretending one session can reread everything.

A conversation-only game-design turn is not repository work. Use
`.agents/skills/design-companion/SKILL.md`, answer in chat, and make no
repository change. Once Cameron adopts a direction or asks for capture, use
`.agents/skills/design-session/SKILL.md`; that capture is its own work order
and needs no unrelated tick.

Human decision issues follow [wiki/process/tick.md](wiki/process/tick.md): one
numbered question, short analysis, options, recommendation, and what the answer
unlocks. Label them `decision-required`; flip to `decision-made` when
answered.

## The one rule

Any change to how the game functions ships with an amendment to the binding
wiki page that owns it. Usually this is a `Type: spec` page; changes to the
game's promise or a cross-system invariant also amend a `Type: law` page.
Every behavior-changing commit carries a `Defense:` paragraph naming the
clause it implements or explaining the amendment. Root `DESIGN.md` contains
no unique law and does not satisfy this rule.

## Worktree and commit posture

- **Always use a worktree for file changes.** Never edit the shared primary
  checkout. A read-only design conversation creates no worktree.
- Prefer `tools/worktree-new.sh <task> --class <docs|frontend|sim|save|process>
  --key <path>...` (seeds cargo target and records advisory activity). Finish with
  `tools/worktree-done.sh <task>` (clears activity, prunes `target/`, removes
  worktree). The canonical root is `.Codex/worktrees/`; operators may override
  it with `MISALIGNED_WORKTREE_ROOT` without changing the repository contract.
- For a spec carrying work-order metadata, prefer `tools/task.sh start
  wiki/path.md`; `tools/task.sh status|check|finish|abandon` composes the same
  helpers without auto-committing or destructive Git recovery. Run
  `tools/project-status.py` for the live dispatch/worktree/activity view and
  `tools/doctor.sh --offline` for local setup diagnosis.
- **Advertise before heavy work.** Inspect `tools/claim.sh list` and record
  likely edit paths. Overlap is a warning, not ownership: proceed in an
  isolated worktree and reconcile against current main at landing. See
  [wiki/process/agent-scale.md](wiki/process/agent-scale.md).
- A shell working directory does not guarantee that every patch tool resolves
  relative paths there. Verify the patch base before the first edit, use an
  explicit worktree path when needed, and keep the shared checkout clean.
- After entering a Rust-impacting worktree, run
  `tools/seed-cargo-target.sh` before long Cargo commands (or use
  `worktree-new.sh`). Never share one external `CARGO_TARGET_DIR` across
  worktrees.
- Commit coherent completed work without waiting for routine permission.
- Land completed work, then remove its worktree and task branch. No stale
  worktrees.

## Non-negotiables

- Game rules live in the lib; frontends are thin views. `Sim` never reads the
  wall clock or does I/O.
- Both frontends surface a new system before its spec becomes IMPLEMENTED.
- Verification is proportional to impact (see
  [wiki/process/workflows.md](wiki/process/workflows.md)):
  - Mid-loop: narrowest `./tools/check.sh --docs|--lib|--frontend` (or auto).
  - Land: one `./tools/check.sh --land` (or auto/`--full`) under the rust lock.
  - At most one Rust gate runs on the machine at a time (shared lock). One
    `task.sh finish` landing runs at a time. Path activity never blocks work.
  - Docs/spec/process/log/reference-art work stays on the docs path.
  - Site and shell changes run their targeted build, syntax, or smoke checks.
  - Rust-impacting landings still need a relevant observed run.
- Long dispatches: `tools/heartbeat.sh start|phase|end` so progress is
  visible under `.agents/runs/` (gitignored).
- The local hook and Tangled pipeline reject a `crates/` (or legacy `src/`)
  change without a changed `Type: law` or `Type: spec` page under `wiki/`.
- Update knowledge made stale and add a uniquely named session log
  (`wiki/log/YYYY-MM-DD-topic.md`). Then run `tools/ledger_index.sh` to
  regenerate `wiki/log/DEVLOG.md` and `wiki/process/specs.md` — do **not**
  hand-edit those generated indexes. Design changes also append the current
  dated volume under [wiki/log/decisions.md](wiki/log/decisions.md), but the
  current law/spec page—not the log—owns the decision.
- Use explicit `git add` paths, never `git add -A`. Keep commit prose free of
  decorative emoji; standard attribution marks in provenance footers are fine.
- Ledger files: dated `wiki/log/decisions/*.md` volumes still merge by union.
  `DEVLOG.md` and `specs.md` are generated — resolve by re-running
  `tools/ledger_index.sh` after both sides' session logs / spec pages exist.
- Never use `git reset`, `git checkout --`, or `git stash` in the shared
  checkout.
- Run at most one sim+save-heavy work order at a time; isolated frontend,
  test-only, and documentation work may proceed alongside it.

## Landing

Rebase the task branch onto current `origin/main`, rerun the appropriate
scoped verification, merge and push to main directly, then remove the worktree
and delete the task branch. The PR rule was removed 2026-07-07. Prefer
`tools/task.sh finish <task>` for the serialized landing: after `main` pushes,
it builds the exact landed revision and publishes the public corpus to the
orphan `pages` branch. A manual landing must run `./tools/site-deploy.sh` after
the `main` push. Use `./tools/site-smoke.sh` to prove the public edge names the
landed source revision before reporting a public-site change complete.