From 7daeac888d443da52e2d117f9163171d47b2661d Mon Sep 17 00:00:00 2001 From: jbiskur Date: Fri, 7 Aug 2026 14:09:28 +0100 Subject: [PATCH] docs: state review enforcement accurately MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Branch protection on main is now live: pull request required, the three Validate jobs required, strict up-to-date checks, no force pushes, no deletions, conversation resolution required. Required approvals are zero and code-owner reviews are off, because @flowcore-io/usable-maintainers currently has one member and enforcing code-owner approval on a one-person team would make the repository unmergeable. CONTRIBUTING and the threat model claimed CODEOWNERS review was required, which was not true — corrected to say reviewer assignment is advisory today, name it as a known gap, and state the condition for closing it. Also: - T2 now credits the automated checks as the real control, with human review listed as residual rather than as a mitigation. - T3 notes that tags are not themselves protected, so checksums are the artifact-level guarantee. - Fixed the contributor instruction to add changelog entries under "## Unreleased" — that section no longer exists after 0.1.0, so it now says to create it. Co-Authored-By: Oz --- CONTRIBUTING.md | 16 ++++++++++++---- docs/threat-model.md | 18 ++++++++++++------ 2 files changed, 24 insertions(+), 10 deletions(-) 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