# Contributing to MinerOps

## Workflow

```text
Product decision
  -> Task specification
    -> Implementation
      -> Architecture review
        -> Focused review and fixes
          -> Commit
            -> Push
```

Substantial work should begin from an approved specification in `docs/tasks/`.

## Before Starting

1. Confirm repository, branch, working tree, and expected latest commit.
2. Read the architecture, product, decisions, coding standards, task
   specification, and relevant release planning document when one exists.
3. Confirm the current Alembic head.
4. Report material conflicts before deviating.

## Scope

Each task should implement one coherent feature. Adjacent ideas belong in later tasks rather than being bundled into the current change.

## Branches and Commits

Do not force-push, rebase shared branches, amend approved commits, or mix unrelated work without explicit approval.

Use concise conventional commit messages, for example:

```text
feat: add begin repair workflow
feat: add repair timeline read APIs
fix: restore lifecycle during repair downgrade
docs: add MinerOps coding standards
```

Commit only after implementation, validation, review, and file-set confirmation.

## Completion Report

Report files created and modified, migrations, routes, permissions, domain behavior, test counts, validation results, risks, and final `git status --short`.

## Architecture

Follow `docs/CODING_STANDARDS.md` and preserve:

```text
Router -> Service -> Repository -> PostgreSQL
```

Use explicit operational APIs and immutable history.

## Migrations

Validate previous head to new head, downgrade, re-upgrade, empty database through head, constraints, indexes, permission assignments, and transactional failure behavior.

## Review

Review for scope creep, hidden CRUD, incorrect transactions, application-only invariants, unsafe downgrades, route shadowing, permission regressions, loss of history, N+1 queries, concurrency gaps, and accidental sensitive files.

## AI-Assisted Work

AI tools must inspect the repository, follow the task, preserve conventions, report conflicts, run validation, avoid commits and pushes unless instructed, and provide a complete report. Human approval is still required.