Contributing¶

Goal¶

Prepare a focused change that respects dependency boundaries and is straightforward to review.

Prerequisites¶

A source checkout.
The toolchain and platform requirements in Source setup and test tiers.
Familiarity with Architecture overview and Security architecture for boundary-sensitive work.

Steps¶

Create a focused branch and keep unrelated worktree changes intact.
Install the local Conventional Commit hook:
```
./scripts/install-git-hooks.sh
```
Make the smallest coherent change. In particular:
- keep colossus-domain dependency-free;
- keep CLI and TUI as request/render interfaces;
- follow the Rust crate structure contract and keep roots thin;
- put policy, tool, model, workflow, and state behavior in their owning services;
- keep tests focused on behavior and contracts that remain supported; when removing a feature, remove its feature-specific tests, and retain rejection, migration, or tombstone coverage only when the post-removal behavior is itself an intentional compatibility or security contract.
Iterate with the smallest relevant test tier:
```
cargo xtask dev
```
Before opening or updating a pull request, run the change-selected local PR gate:
```
cargo xtask pr --base origin/main
```
The task uses the same fail-closed path classifier as hosted PR validation and selects Rust, SDK, Desktop, documentation, and dependency checks. Missing required toolchains fail explicitly instead of silently skipping a selected component.
Before requesting full acceptance, inspect every unresolved pull-request review thread and required check, including automated ChatGPT/Codex review. Address each actionable finding in code and tests; do not treat a green build as a substitute for review resolution. Once the PR gate is green on an up-to-date, non-draft PR, follow the ci:full procedure.
Use a Conventional Commit message:
```
<type>[optional scope][!]: <description>
```
Allowed types are build, chore, ci, docs, feat, fix, perf, refactor, revert, security, style, and test.

Expected result¶

The diff has one clear purpose, tests describe the changed behavior, and no interface or crate root has absorbed unrelated application logic.

Verification¶

Run the repository completion gate and inspect the final diff:

git diff --check
cargo xtask check rust
cargo xtask pr --base origin/main

Failure path¶

If a change crosses an unclear ownership boundary, stop and map the request, service, port, and adapter before adding code. If a test exposes a security or state invariant, repair the implementation rather than weakening the test. Preserve user-owned or unrelated worktree changes.

Next step¶

Open a review with the behavioral outcome, affected boundaries, focused tests, and full local gate results in the description. Recheck unresolved human and automated review threads after the final push, then request hosted pre-merge acceptance once for the final head.