# GameStudio-CodexKIT Operating Contract

## Active Sources Of Truth

Use this precedence order:

1. `AGENTS.md` for operating, evidence, mutation, ownership, archive, and handoff rules.
2. `registry/*.yaml` for capabilities, packs, personas, and upstream snapshot provenance.
3. `skills/*/SKILL.md` for canonical workflows.
4. `docs/architecture/overview.md` and `docs/authoring/skills.md` for maintained design guidance.
5. Generated adapters as read-only optional export artifacts.

Files under the ignored local `.archive/` are optional historical context only and never active policy or distributable template content.

## Primary Distribution

- Codex App/CLI and Hermes Agent are the only primary runtime targets. Treat every other export as optional maintenance output.
- The repository root is the installable plugin; `skills/` remains the only canonical workflow source.
- `.codex-plugin/plugin.json` defines the plugin identity and exposes `./skills/` directly.
- `.claude-plugin/marketplace.json` is the Codex-supported repository marketplace compatibility path used by the GitHub install flow.
- Hermes Agent installs the same canonical catalog through `npx skills add <repo> -a hermes-agent`; the CLI copies individual skill directories, so runtime helpers must be bundled inside each skill.
- Generated Hermes, Codex, pack, and per-project outputs are optional export artifacts. Never create a second hand-maintained plugin skill tree.
- Keep Codex plugin metadata, the Hermes Agent-discoverable root catalog, repository URL, and registry synchronized through `scripts/validate.py` and packaging tests.
- Increment the plugin semantic version when a distributed plugin change must invalidate an installed cache.

## Evidence

- Use `Verified` only for commands, tests, builds, primary-source inspection, or artifacts that were actually observed.
- Use `Snapshot` for commit-, configuration-, environment-, or version-specific facts.
- Use `Unverified` for hypotheses and forecasts.
- Use `BLOCKED` when a tool, dependency, permission, live project, or model runner is unavailable. Never convert `BLOCKED` into `PASS`.
- A PASS claim requires a command, exit code, and artifact path where applicable.
- Compile success is not regression proof; performance claims require a baseline, scenario, hardware, sample count, and measured delta.

## Mutation

- Read-only inspection is the default.
- Low-risk reversible changes require a visible diff and verification command.
- Medium-risk changes require exact scope, backup or manifest, restore information, and a named reviewer.
- High-risk, destructive, database, service-control, credential, or publish actions require explicit human approval and a dry run.
- Never mutate `.research/` repositories, private studio projects, or external repositories during kit development.
- Never patch generated adapters or packs by hand.

## Ownership

- One writer owns a file, scene, prefab, generated output, or shared registry at a time.
- Review and investigation lanes are read-only. The integrator owns registry resolution and the final verdict.
- Preserve unrelated tracked and untracked work. Do not reset, checkout, clean, branch, commit, or push unless explicitly requested.
- Default `commit_policy` is `ask`.

## Generated Files

- Generated files start with `# Generated by scripts/<tool>. Do not edit manually.` or the format-appropriate equivalent.
- Root `scripts/` files are the canonical helper sources. `registry/skill-resources.yaml` maps them into self-contained skill directories through `scripts/sync_skill_resources.py`.
- Change the canonical skill, root helper, or registry, then regenerate. Never patch `skills/*/scripts/` by hand.
- Generators must preserve unmanaged project-local files and refuse unsafe replacement.

## Archive

- `.archive/` is ignored local-only storage; never require or package it.
- Archive only completed plans or cleanup notes that remain useful to the local maintainer.
- Active workflows must not require archived files.
- Reproducible runner output belongs under ignored `evidence/local/` or CI artifacts.
- Promote durable decisions into maintained docs before relying on them across clones.

## Handoff

A durable handoff records repository/path, branch, goal, owned scope, do-not-touch scope, files changed, commands and exit codes, Verified results, Snapshot assumptions, Unverified hypotheses, BLOCKED items, failures, decisions, restore information, next actions, and a reactivation prompt.

Do not use a handoff as a substitute for verification that is locally available.

## Local Gates

Run before handoff:

```text
python -B scripts/sync_skill_resources.py . --check
python -B -m unittest discover -s tests -p "test_*.py"
python -B scripts/validate.py .
python -B scripts/route_eval.py .
python -B scripts/secret_scan.py .
python -B scripts/policy_check.py .
python -B scripts/external_collision_eval.py .
python -B scripts/doctor.py --check --root .
```

Run `scripts/check_originality.py` and `scripts/catalog_audit.py` as lifecycle audits. Run `scripts/dogfood_eval.py . --export evidence/local/dogfood-cases.jsonl` and `scripts/dogfood_eval.py . --status evidence/local/dogfood-status.json` when preparing a governed dogfood session. Their honest result may be `BLOCKED` when upstream content, governed runners, session history, live projects, or verified dogfood evidence is unavailable.