# Contributing to portfolio-optimiser-commons

Thank you for your interest. Please read this first — the workflow here is deliberately
narrower than most repositories, and knowing that up front saves you wasted effort.

## Code of Conduct

Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).

## Pull requests are not accepted

The pull-request tab is **switched off** on this forge, across every repository in the
organisation. That is a published position, not an oversight: this project is solo-maintained,
and an enabled-but-permanently-empty PR queue would promise a review capacity that does not
exist.

Use **issues** instead. A well-argued issue carries the same information as a patch and costs
you less to write.

## What belongs here, and what does not

This repository is the framework-neutral core. Before opening an issue, check which side of the
boundary your point falls on:

| Your point is about | Raise it in |
|---|---|
| The normative specs, the example bundles, the golden fixtures | **here** |
| Behaviour of the MAF implementation | [`portfolio-optimiser`](https://git.fromaitochitta.com/open/portfolio-optimiser) |
| Behaviour of the Claude Agent SDK implementation | [`portfolio-optimiser-claude`](https://git.fromaitochitta.com/open/portfolio-optimiser-claude) |

A change that is true of only one of the two stacks does not belong here, however correct it
is — that is the whole point of the shared core. See the Non-goals in the [README](README.md).

## Reporting an issue

Useful issues on a specification repository look different from bug reports on code. The most
valuable ones name a specific place in the text:

- **Quote the section and the sentence**, not just a line number. Line numbers here go stale
  quickly; a section heading plus the wording you are reading survives an edit above it.
- Say which of the two things you are claiming: that the specification is **internally
  inconsistent**, or that it is **inconsistent with an implementation**. They have different
  remedies, and conflating them is the most common way a report stalls.
- For a fixture, state the input, the output you expected, and the output you got.

## If you are maintaining a consuming repository

Sync is **pull-only**, and all edits land here first:

```sh
git subtree pull --prefix=shared commons main --squash
```

**Never run `git subtree push` from a consuming repository.** The reason, and what it cost the
one time it happened, is documented in the [README](README.md).

## Conventions

Commits follow [Conventional Commits](https://www.conventionalcommits.org/)
(`type(scope): description`). Changes to normative text are ratified before they land; the
reasoning behind each ruling is recorded in [`docs/plan/`](docs/plan/), including for the
rulings that were later reversed.

## Questions?

Open an issue.