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.