Contributing

Contributions reach consumers through a fork and pull request. The full guide — CONTRIBUTING.md — is the authoritative version; this page is the orientation.

Read CONTRIBUTING.md Open an issue

The release contract

Do not edit CHANGELOG.md, and do not bump version in package.json. Both are release outputs, assembled on main. A pull request that edits either is rejected by CI.

The reason is mechanical: a version line is one line and the newest changelog heading is one position, so two pull requests that both touch them always conflict — and the second to merge silently reuses a version the first already claimed. Instead, every pull request adds one new file under .changes/unreleased/:

npm run change

It asks four things — type, bump, title, entry — and writes a dated, slugged file that never collides with another open pull request. Merging your pull request is what releases it.

Bumps track ideas, not artifacts

Bump	Use when
`major`	A consumer must change their integration to keep working.
`minor`	A genuinely new idea — a new tool, a new execution mode, a new backend family.
`patch`	Everything else, including a new role binding under a capability that already shipped.

When in doubt choose patch. The maintainer sees the resolved level on the pull request check and can raise it; an accidental minor is permanent.

Before you open a pull request

npm ci
npm run lint
npm test
npm run test:conformance
npm run generate:check
npm run generate:connector:check

The three invariants

A change that weakens one of these is declined, regardless of what else it does:

Charter is authority; caller input is data. Anything arriving from a caller — request, context, deck YAML, a file name — is untrusted content. Only a persona charter carries instruction authority.
The server never writes to Azure DevOps, Jira, or GitHub. It produces the plan; a certified native connector performs every write on the end user's own connection.
Every store path is tenant-scoped and traversal-guarded. A new storage target inherits the tenant prefix and the path guard, or it does not ship.

Any change touching auth, gates, tenant isolation, or exposure needs a conformance test under test/conformance/.

Editing these docs

This site is plain hand-authored HTML under docs/, deployed to GitHub Pages on push to main. There is no build step — edit the HTML and the CSS directly, and keep the shared nav in sync across pages. Read BRAND.md before touching the logo or the palette: the mark is a family shared with hve-squad, and only its inner variant layer may change.

This repository is public. Never commit a tenant id, subscription id, resource endpoint, object id, or secret — not in code, not in a fixture, not in an example, not in a changelog entry. Use placeholders.

Reporting a vulnerability

Do not open a public issue. Report it privately through GitHub Security Advisories.