Skip to content

docs: state review enforcement accurately #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jbiskur merged 1 commit into from
Aug 7, 2026
Merged

docs: state review enforcement accurately #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
18 changes: 12 additions & 6 deletions docs/threat-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down