diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 30fe988..05ed9d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -76,16 +76,24 @@ useful than an optimistic ⏳. 1. Branch from `main`. 2. Run `node scripts/validate-package.mjs` and make it pass. -3. Add a `CHANGELOG.md` entry under `## Unreleased`. +3. Add a `CHANGELOG.md` entry under `## Unreleased`, creating that section above the newest + released version if it does not exist. 4. Use [Conventional Commits](https://www.conventionalcommits.org/) — `feat:`, `fix:`, `docs:`, `chore:`, `ci:`. 5. Describe the behavior change, not just the diff. CI blocks: invalid manifests, invalid skill frontmatter, unsafe paths or symlinks, credential -patterns, broken links, and release-archive drift. +patterns, broken links, and release-archive drift. `main` requires a pull request, requires +those checks to pass, and forbids force pushes and deletions. -Skill, `mcp.json`, release workflow, and security documentation changes require CODEOWNERS -review. +`CODEOWNERS` assigns reviewers for skills, `plugin.json`, `mcp.json`, release workflows, and +security documentation. **Their approval is not currently enforced.** Required approvals are +set to zero because `@flowcore-io/usable-maintainers` has a single member, and requiring +code-owner approval on a one-person team would make the repository unmergeable. Reviewer +assignment is therefore advisory today. + +This is a known gap, not a design choice. When a second maintainer joins, raise required +approvals to at least one and enable code-owner reviews. ## Versioning diff --git a/docs/threat-model.md b/docs/threat-model.md index a5503ee..e174720 100644 --- a/docs/threat-model.md +++ b/docs/threat-model.md @@ -60,18 +60,24 @@ Read-only scopes are what actually bound the damage. Mitigations: `mcp.json` is URL-only by design and documented as such; CI fails on credential patterns in `mcp.json`, `plugin.json`, and skills; GitHub secret scanning with push -protection; the release archive is built from a path allowlist; CODEOWNERS review on MCP -config. +protection is enabled; the release archive is built from a path allowlist. + +Residual: `CODEOWNERS` assigns reviewers for MCP configuration but approval is not enforced — +required approvals are zero while the maintainer team has one member. The automated checks +above are the real control here; human review is currently advisory. See `CONTRIBUTING.md`. ### T3 — Supply chain compromise of a release **Risk: high impact, low likelihood.** -Mitigations: releases only from protected tags; manifest version must equal the tag; -third-party Actions pinned to commit SHAs; SHA-256 checksums published; no publishing from -fork or pull-request contexts; revocation procedure in `SECURITY.md`. +Mitigations: releases publish only from tags on this repository; the manifest version must +equal the tag; Actions are pinned to commit SHAs; SHA-256 checksums are published; no +publishing from fork or pull-request contexts; `main` forbids force pushes and deletions; +revocation procedure in `SECURITY.md`. -Residual: no signed attestations yet — [open decision #7](../README.md#open-decisions). +Residual: no signed attestations yet — [open decision #7](../README.md#open-decisions). Tags +themselves are not protected, so a maintainer could move one; releases are immutable once +published, and checksums are the artifact-level guarantee. ### T4 — Over-broad scope grant