# Contributing

Thanks for improving `dsh-gpt56-ptc`.

## Principles

- Keep the preset cache-stable: no automatic model switching, presentation switching, or per-turn SDK trimming.
- Keep Host concerns out of the preset: routing, credentials, sandbox, approvals, persistence, and cross-session registries remain Host-owned.
- Keep the Bundle installer narrow: it may create and validate one user preset, but must not become a router, updater, or security-policy layer.
- Treat the installed copy as user-owned immediately after successful creation.
- Prefer deleting or tightening prompt text over adding generic instructions.
- Tie every behavioral rule to a reproducible failure and an acceptance metric.
- Preserve the official Code preset structure unless a DSH compatibility change requires a documented rebase.

## Workflow

1. Create an issue describing the observed task, model, reasoning effort, Provider, DSH version, prompt stack, and repository conditions. If Issues are unavailable, include the same record in the pull request.
2. Add or update installer, failure-injection, composition, or documentation tests for every changed contract.
3. Run `node --test` and inspect `npm pack --dry-run`.
4. Install through `dsh plugin --profile web add .` in a disposable DSH home, restart, and run the standing-mount check.
5. For Bundle changes, install a real packed tarball and verify first install, collision preservation, rollback, repeat activation, and uninstall persistence.
6. For prompt changes, run the behavioral task against both the official `code` preset and this preset.
7. Report task success, scope changes, turns, tool programs, repeated tests, and completion evidence.
8. Update `CHANGELOG.md` for user-visible changes.

## Prompt changes

Edit `src/persona.md` first, then make the identical change to the YAML literal block in `presets/gpt56-ptc/agent.cordis.yml`. The synchronization test must pass.

Avoid large batches of prompt changes. One change should target one measured regression so its effect can be attributed.

## Composition changes

A row that publishes a Service must live in the correct isolated realm. Do not move Host registries or security boundaries into the preset. Validate every changed composition with a real DSH standing mount before requesting review.

The packaged directory is an installation template and must remain self-contained. Do not add paths back into this package unless removal-persistence semantics are deliberately changed and documented.

## Installer changes

Changes to `lib/index.js` must preserve these invariants:

- every existing final id stops before any write;
- creation uses official `copy()` twice: official Code → random staging → fixed final id;
- all edits occur only after exact first-user-root path and realpath containment checks on staging;
- staging is mount-validated before final publication;
- no marker authorizes adoption, overwrite, repair, or final-id deletion;
- a staging or final copy race never removes the winner;
- cleanup can target only the random staging id carrying this invocation's token;
- the fixed final id is never automatically removed after publication;
- final `installed` state is written only after final standing validation;
- repeat activation and package updates preserve user files byte-for-byte;
- Bundle disposal and uninstall never delete the custom preset;
- readonly roots are never mutated.

Tests must include staging/final copy races, out-of-root resolution, write and both-mount failures, staging cleanup failure, Windows replacement, malformed/forged markers, user edits, and uninstall persistence. A multi-file transaction claim is not acceptable: replacement is atomic per staging file, while official whole-directory `copy()` publishes the final id.

## Pull requests

A pull request should include:

- motivation and linked issue;
- exact files and behavior changed;
- automated test output;
- package payload inspection;
- DSH version used for native install and mount validation;
- clean-home collision and removal-persistence evidence;
- representative Sol, Terra, or Luna trace summary when behavior changes;
- known tradeoffs and explicit rollback instructions.