moose-inventory 2.0 → 2.1

data/docs/qa/qa-documentation-and-release-gates.md

@@ -0,0 +1,283 @@
+# Moose Inventory QA, Documentation QA, and Release Gates
+
+## Approval status
+
+Status: **Draft - maintained gate template**
+
+This document defines reusable QA, documentation-QA, and release-gate templates for Moose Inventory. It maps the local verification gate to the approved requirements baseline and adds human-review checkpoints for release decisions.
+
+Approved references:
+
+- `GOV-TAILOR-001`: Moose Inventory is approved as Class 4 with target profile Software Library / Package.
+- `GOV-PRODUCT-001`: `docs/product/product-brief.md` is approved as the product-framing baseline.
+- `GOV-REQ-001`: `docs/product/requirements-baseline.md` is approved as the requirements and acceptance criteria baseline.
+- `GOV-UX-001`: `docs/ux/cli-workflow-notes.md` is approved as the CLI UX/workflow baseline.
+- `GOV-ARCH-001`: `docs/architecture/architecture-and-trust-boundaries.md` is approved as the architecture and trust-boundary baseline.
+- `GOV-SEC-001`: `docs/security/security-privacy-process.md` is approved as the security and privacy process baseline.
+- `GOV-RISK-REG-001`: `docs/security/accepted-risk-register.md` is approved as the maintained accepted-risk register baseline.
+
+Scope limit: this document is a QA/release evidence template. It does not approve a release, public/compliance claim, RubyGems publishing, accepted risk, new feature scope, or future architecture/security change.
+
+## Gate principles
+
+- Evidence is not approval. Passing checks support a release decision; they do not make the decision.
+- Release decisions remain human-owned.
+- Every exception must be either fixed, deferred as explicit backlog work, or accepted through `docs/security/accepted-risk-register.md` when it is security/privacy/release risk.
+- A release candidate should be traceable to requirements, tests, documentation, security scans, package sanity, and rollback/recovery notes.
+- Network-dependent security checks may fail closed. If the failure is environmental rather than a finding, record the failed check, rerun when available, and do not publish until the gate is either passing or explicitly accepted.
+
+## Local gate mapping
+
+`./scripts/check.sh` is the default local release-readiness gate. Run with security tools required for release evidence:
+
+```bash
+MOOSE_INVENTORY_REQUIRE_SECURITY_TOOLS=1 ./scripts/check.sh
+```
+
+| Gate step | Evidence produced | Requirement / release criteria supported | Release interpretation |
+| --- | --- | --- | --- |
+| `bundle exec rspec --format progress` | Automated spec result and coverage report | CLI, CFG, DB, INV, DRY, SNAP, DOC, AUD, TAG, ANS, CI, COMPAT, DOCS acceptance criteria | Required passing evidence for supported behavior. Any failure blocks release unless a human records an explicit exception. |
+| `scripts/ci/check_rubocop.sh` | RuboCop result for Ruby source, executable loader, scripts, specs, and gemspec | COMPAT and maintainability expectations; release quality hygiene | Required passing evidence. Style failures indicate unreviewed code-quality drift. |
+| `git diff --check` | Whitespace/conflict-marker check | Documentation/source hygiene and merge-safety expectations | Required passing evidence. Failure blocks release until fixed. |
+| `scripts/ci/check_permissions.sh` | Tracked executable permission allow-list check | PKG and release-integrity expectations | Required passing evidence. Unexpected executables are potential packaging/security drift. |
+| `scripts/ci/check_generated_artifacts.sh` | Generated artifact ignore/tracking guard | QA, PKG, and release-integrity expectations for local reports, package output, temporary files, and audit scratch space | Required passing evidence. Generated paths must stay ignored and untracked unless intentionally promoted. |
+| `scripts/ci/check_security.sh` | OSV batch query, `bundler-audit`, and optional/required `osv-scanner` lockfile/source scan | SEC and PKG dependency/security acceptance criteria | Required passing evidence for release. Critical/high findings block release unless explicitly accepted by a human. |
+| `scripts/ci/check_secrets.sh` | `gitleaks` filesystem scan with redaction | SEC secrets-handling criteria | Required passing evidence for release. Any true secret finding requires cleanup and rotation outside Moose Inventory. |
+| `scripts/ci/package_sanity.sh` | Built gem, metadata inspection, required packaged files, CLI version smoke | PKG release-integrity criteria | Required passing evidence that the packaged artifact contains expected entrypoints and metadata. |
+
+## Documentation QA checklist
+
+Use this before release and after material user-facing changes.
+
+```markdown
+## Documentation QA checklist
+
+Release candidate / commit:
+Reviewer:
+Date:
+
+Required docs:
+- [ ] `README.md` reflects current supported CLI workflows and examples.
+- [ ] `docs/product/requirements-baseline.md` still matches intended behavior, or proposed changes are recorded for approval.
+- [ ] `docs/ux/cli-workflow-notes.md` still matches command behavior and output conventions.
+- [ ] `docs/architecture/architecture-and-trust-boundaries.md` still matches implementation and release flow.
+- [ ] `docs/security/security-privacy-process.md` still matches security/privacy posture.
+- [ ] `docs/security/accepted-risk-register.md` is reviewed and current.
+- [ ] `docs/release/publishing.md` and `docs/release/release-readiness.md` match the actual release workflow.
+
+Content checks:
+- [ ] Examples avoid real infrastructure, real credentials, real hostnames, and private data.
+- [ ] Snapshot/import/export examples warn that inventory data can be sensitive where relevant.
+- [ ] Database credential examples prefer `password_env` over plaintext `password`.
+- [ ] Destructive or high-risk workflows show dry-run/confirmation expectations where relevant.
+- [ ] Release notes distinguish evidence from approval.
+- [ ] Known limitations and non-goals are visible enough for users.
+- [ ] New or changed options include machine-readable output implications where relevant.
+
+Evidence:
+- [ ] Documentation diff reviewed.
+- [ ] Link/path references checked by inspection or tooling.
+- [ ] No stale version numbers, release tags, or command output examples remain.
+- [ ] Follow-up documentation gaps added to `BACKLOG.md`.
+```
+
+## Release readiness checklist
+
+Use this for every release candidate before creating a `v*` tag.
+
+```markdown
+## Release readiness checklist
+
+Release version:
+Release candidate commit:
+Reviewer / release owner:
+Date:
+
+Source state:
+- [ ] `git checkout master` completed.
+- [ ] `git pull --ff-only origin master` completed.
+- [ ] `git status --short --branch` is clean and on the expected branch.
+- [ ] Version in `lib/moose_inventory/version.rb` matches the intended release.
+- [ ] Version is greater than the latest published RubyGems version.
+- [ ] Changelog/release notes drafted if maintainers want public notes.
+
+Requirement and QA evidence:
+- [ ] Material changes map to approved requirements or have approval/backlog records.
+- [ ] `MOOSE_INVENTORY_REQUIRE_SECURITY_TOOLS=1 ./scripts/check.sh` passed.
+- [ ] Documentation QA checklist completed.
+- [ ] Known compatibility impact reviewed.
+- [ ] Generated artifacts, local databases, coverage reports, and temporary files are not committed unless intentional.
+
+Security and risk evidence:
+- [ ] Release security gate completed.
+- [ ] Accepted-risk disposition completed.
+- [ ] No unresolved critical/high findings remain unless explicitly accepted.
+- [ ] Secret-scan results reviewed; true positives cleaned and rotated outside Moose Inventory.
+- [ ] Package sanity passed for the gem artifact.
+
+Publishing readiness:
+- [ ] GitHub Actions CI is green for the release commit.
+- [ ] RubyGems trusted publishing setup is still expected to use repository `RusDavies/moose-inventory`, workflow `release.yml`, and environment `release`.
+- [ ] Required GitHub `release` environment approvals, if any, are known to the release owner.
+- [ ] Manual RubyGems publishing fallback is not used unless trusted publishing is unavailable and a RubyGems owner explicitly approves.
+
+Release decision:
+- [ ] Human approver:
+- [ ] Approval reference / message:
+- [ ] Tag to create:
+- [ ] Release notes location:
+```
+
+## Release security gate template
+
+```markdown
+## Release security gate
+
+Release version:
+Release candidate commit:
+Reviewer:
+Date:
+
+Automated security checks:
+- [ ] OSV batch query passed.
+- [ ] `bundle-audit check --update` passed.
+- [ ] `osv-scanner` lockfile/source scan passed with `MOOSE_INVENTORY_REQUIRE_SECURITY_TOOLS=1`.
+- [ ] `gitleaks detect --no-git --source . --config .gitleaks.toml --redact --no-banner --log-level warn` passed.
+- [ ] Package sanity check passed.
+
+Manual review:
+- [ ] Dependency changes reviewed for reachability and release impact.
+- [ ] GitHub Actions workflow changes reviewed for permission, token, and publishing risk.
+- [ ] Gemspec/package metadata reviewed for MFA, executable, file list, and dependency changes.
+- [ ] Config, database, import/export, audit, and release docs reviewed for secret/privacy leakage.
+- [ ] Any new external network behavior is documented and approved.
+
+Findings:
+- Critical findings:
+- High findings:
+- Medium findings:
+- Low findings:
+
+Disposition:
+- [ ] All critical/high findings fixed, or accepted risk recorded.
+- [ ] Medium/low findings are fixed, deferred to backlog, or accepted as appropriate.
+- [ ] No credentials or private inventory data are present in committed files, logs, docs, examples, or release artifacts.
+```
+
+## Accepted-risk disposition template
+
+Use this before release, even when there are no accepted risks.
+
+```markdown
+## Accepted-risk disposition
+
+Release version:
+Release candidate commit:
+Reviewer:
+Date:
+
+Register reviewed:
+- [ ] `docs/security/accepted-risk-register.md` reviewed.
+- [ ] Accepted risks are current and within review date/trigger.
+- [ ] Proposed/monitored risks are not being treated as accepted by accident.
+- [ ] Any release-blocking proposed/monitored risk has a human decision.
+
+Accepted risks shipping in this release:
+- Risk ID:
+  - Scope:
+  - Severity:
+  - Why still acceptable for this release:
+  - Compensating controls:
+  - Approver / approval reference:
+
+New risk decisions required:
+- Risk ID or short name:
+  - Decision needed:
+  - Blocker status:
+  - Owner:
+
+Outcome:
+- [ ] No accepted risks ship in this release.
+- [ ] Accepted risks ship only within documented scope.
+- [ ] Release is blocked pending risk decision.
+```
+
+## Package yank, deprecation, and rollback path
+
+RubyGems packages cannot be rolled back in place like a service deployment. Recovery is versioned and human-owned.
+
+### If a release is bad but not security-sensitive
+
+1. Stop further release activity.
+2. Record the affected version, tag, workflow run, and observed issue.
+3. Decide whether users should keep using the previous version or upgrade to a patch.
+4. Prepare and verify a patch release on a new version number.
+5. Publish the patch through trusted publishing.
+6. Add release notes explaining the fix and impact at an appropriate detail level.
+
+### If a release exposes a security issue or secret
+
+1. Stop release activity and preserve evidence.
+2. Identify whether credentials, private inventory data, package integrity, or user safety is affected.
+3. Rotate exposed credentials outside Moose Inventory where applicable.
+4. Decide with a human maintainer whether to yank, deprecate, patch, or publish an advisory.
+5. Prepare the smallest safe patch release and run the full release gate.
+6. Publish via trusted publishing when approved.
+7. Update `docs/security/accepted-risk-register.md`, security audit notes, or incident notes as appropriate.
+
+### RubyGems yanking/deprecation notes
+
+- Yanking removes a version from normal installation resolution but does not erase every copy already downloaded, cached, mirrored, or vendored.
+- Deprecation/advisory communication may be more useful than yanking when users need migration context.
+- Never yank or deprecate a gem version without explicit human maintainer approval.
+- Manual RubyGems credentials, if used in an emergency, must not be committed or pasted into logs.
+
+## Post-release review template
+
+Run after the workflow completes and published-version verification is available.
+
+```markdown
+## Post-release review
+
+Release version:
+Release tag:
+Release commit:
+Workflow run:
+Reviewer:
+Date:
+
+Publishing outcome:
+- [ ] `release.yml` completed successfully, or failure is explained below.
+- [ ] Published version appears in `gem info moose-inventory --remote --all`.
+- [ ] Fresh install test completed where practical.
+- [ ] `moose-inventory --help` or equivalent smoke check completed from installed gem.
+
+Evidence links / references:
+- CI run:
+- Release workflow run:
+- RubyGems version URL:
+- Release notes / tag:
+
+Problems observed:
+- Workflow false negatives:
+- RubyGems propagation delays:
+- Install/smoke-test failures:
+- User-visible documentation gaps:
+- Security/risk follow-up:
+
+Follow-up actions:
+- [ ] Backlog items added for any release friction.
+- [ ] Accepted-risk register updated if any risk decision changed.
+- [ ] Release docs updated if the process diverged from documentation.
+- [ ] Maintainers notified of release outcome.
+```
+
+## Current release blockers and follow-ups
+
+These templates do not make the current repository release-ready by themselves. Before the next release, maintainers should still review:
+
+- confirmed GitHub `release` environment protection rules;
+- any active security-audit findings or dependency advisories;
+- whether public `SECURITY.md` vulnerability intake should be added;
+- whether destructive-command confirmation is required before broadening destructive workflows;
+- whether package provenance beyond RubyGems trusted publishing is needed for the intended audience.

data/docs/release/package-provenance-hardening.md

@@ -0,0 +1,126 @@
+# Package provenance hardening evaluation
+
+Status: evaluated as future hardening, not a current release requirement.
+
+Moose Inventory publishes the `moose-inventory` RubyGem through GitHub Actions and RubyGems trusted publishing. This document records the current package-provenance evaluation so release decisions do not confuse useful future hardening with a present release blocker.
+
+## Current baseline
+
+The approved release baseline is:
+
+- releases start from reviewed `v*` tags;
+- the GitHub `release` environment requires human review by `RusDavies`;
+- the release workflow verifies that the pushed tag matches `Moose::Inventory::VERSION`;
+- the release workflow runs `MOOSE_INVENTORY_REQUIRE_SECURITY_TOOLS=1 ./scripts/check.sh`;
+- RubyGems trusted publishing/OIDC issues a short-lived publish token to the reviewed workflow;
+- no long-lived RubyGems API token is required in GitHub secrets;
+- `scripts/ci/package_sanity.sh` builds and inspects the gem payload before release.
+
+This is adequate for the current project profile: a Ruby CLI/RubyGem maintained by Russ, with no current security-sensitive consumer requirement for separately signed provenance artifacts.
+
+## Options evaluated
+
+### RubyGems trusted publishing/OIDC
+
+Decision: keep as the required baseline.
+
+Strengths:
+
+- avoids long-lived RubyGems publishing secrets in GitHub;
+- binds publishing to the repository, workflow, environment, and tag-triggered release path;
+- fits the current RubyGems-native release process;
+- already verified with release `v2.0` / gem `2.0`.
+
+Limitations:
+
+- proves the publish path, not a separately downloadable signed software bill of materials or artifact attestation;
+- consumers still rely on RubyGems distribution metadata and the source repository release evidence.
+
+### Checksums for built gems
+
+Decision: useful as low-complexity future release evidence, but not currently required.
+
+Possible implementation:
+
+- build the gem in the release workflow;
+- compute `sha256sum` for the `.gem` artifact;
+- publish the checksum as a GitHub release artifact or release note after the gem publish succeeds.
+
+Tradeoffs:
+
+- simple and understandable;
+- helps consumers compare a downloaded gem against release evidence;
+- does not by itself prove who built or approved the artifact unless paired with workflow provenance.
+
+### GitHub artifact attestations
+
+Decision: promising future hardening, but defer until there is a consumer or policy need.
+
+Possible implementation:
+
+- grant the release workflow the minimum attestation permission required by GitHub;
+- generate an attestation for the built `.gem` artifact before or during publish;
+- document consumer verification commands.
+
+Tradeoffs:
+
+- stronger provenance signal than a bare checksum;
+- adds GitHub-specific release machinery and consumer education;
+- needs careful validation with RubyGems release tooling so the attested artifact is exactly the published gem.
+
+### Sigstore / cosign-style detached signatures
+
+Decision: not currently recommended.
+
+Tradeoffs:
+
+- can provide ecosystem-neutral signatures;
+- introduces extra tooling, keyless identity semantics or key-management questions, and support burden;
+- RubyGems consumers do not universally expect or verify these signatures.
+
+### RubyGems gem signing with certificates
+
+Decision: not currently recommended.
+
+Tradeoffs:
+
+- RubyGems has historic support for signed gems;
+- practical adoption and verification are limited;
+- certificate/key management would add risk and maintenance overhead disproportionate to current needs.
+
+### SBOM generation
+
+Decision: defer.
+
+Tradeoffs:
+
+- useful if enterprise consumers request dependency inventory evidence;
+- adds format, generation, storage, and review questions;
+- current dependency-audit controls already query OSV and bundler-audit from `Gemfile.lock` during release gates.
+
+## Recommendation
+
+Do not make additional package provenance a release blocker now.
+
+Keep RubyGems trusted publishing/OIDC as the release baseline and revisit stronger provenance when one of these triggers occurs:
+
+- a consumer requests verifiable artifact provenance, SBOMs, checksums, or signatures;
+- Moose Inventory becomes part of a more security-sensitive deployment path;
+- release policy changes require artifact attestations;
+- the project starts publishing multiple binary/native artifacts rather than a source RubyGem;
+- GitHub/RubyGems provenance tooling becomes simple enough to adopt with low operational burden.
+
+If the trigger occurs, the preferred first hardening step is GitHub artifact attestation plus a published SHA-256 checksum for the exact built `.gem`, because that balances verification value against operational complexity. Sigstore/cosign, RubyGems certificate signing, and SBOM publication should remain second-stage options unless a consumer specifically needs them.
+
+## Non-goals
+
+This evaluation does not approve:
+
+- changing the GitHub release workflow;
+- publishing a new gem release;
+- adding new GitHub permissions;
+- adding or rotating signing keys;
+- changing RubyGems settings;
+- making public compliance or supply-chain-security claims.
+
+Those actions require separate approval and verification.

data/docs/release/publishing.md

@@ -4,6 +4,8 @@ This project is published to RubyGems as [`moose-inventory`](https://rubygems.or
 
 The preferred publishing path is GitHub Actions trusted publishing from reviewed `v*` tags. Manual publishing remains documented as a fallback only.
 
+Routine release-infrastructure stewardship and AI-agent boundaries are documented in `docs/maintenance/package-maintenance-and-agent-boundaries.md`.
+
 ## Trusted publishing setup
 
 The repository side is `.github/workflows/release.yml`.
@@ -16,7 +18,11 @@ RubyGems has a trusted publisher configured for the existing `moose-inventory` g
 - Environment: `release`
 - Workflow repository owner/name: blank, because the workflow lives in this repository
 
-The release workflow requires the GitHub environment name `release`. If that environment has protection rules, approve the deployment when releasing.
+The release workflow requires the GitHub environment name `release`. Current environment protection evidence is documented in `docs/release/release-environment-protection.md`.
+
+As of 2026-05-29, the GitHub `release` environment has required reviewer protection for `RusDavies`, self-review prevention disabled, admin bypass disabled, and a custom deployment policy named `v*`. Self-review prevention is disabled because OpenClaw/automation pushes use Russ's GitHub account; with `RusDavies` as the only required reviewer, enabling self-review prevention could prevent Russ from approving the deployment. The workflow itself still runs only for pushed `v*` tags and verifies tag/version alignment before publishing. Because GitHub reports the custom deployment policy object as `type: branch`, verify tag-deployment behavior on the next real release and adjust the environment policy if needed.
+
+Package provenance hardening beyond RubyGems trusted publishing is evaluated in `docs/release/package-provenance-hardening.md`. Additional checksums, GitHub artifact attestations, signatures, or SBOM publication are future hardening options, not current release blockers.
 
 ## Trusted publishing release checklist
 
@@ -37,10 +43,10 @@ The release workflow requires the GitHub environment name `release`. If that env
 
    If the repository version is not higher than the latest RubyGems version, bump `lib/moose_inventory/version.rb` first and commit that change before releasing.
 
-3. Run the local release gate.
+3. Run the local release gate with security tools required, and complete the QA/release templates in `docs/qa/qa-documentation-and-release-gates.md`.
 
    ```bash
-   ./scripts/check.sh
+   MOOSE_INVENTORY_REQUIRE_SECURITY_TOOLS=1 ./scripts/check.sh
    ```
 
 4. Push the release commit and wait for CI to pass.
@@ -65,6 +71,8 @@ The release workflow requires the GitHub environment name `release`. If that env
 
 The workflow verifies that the pushed tag version matches `Moose::Inventory::VERSION`, runs `./scripts/check.sh`, builds the gem through `rubygems/release-gem@v1`, and publishes using RubyGems trusted publishing/OIDC. No RubyGems API key should be stored in GitHub secrets for this workflow.
 
+Trusted-publishing verification was completed with release tag `v2.0` / gem version `2.0`. The gem published successfully to RubyGems via OIDC, but the initial workflow finished red because the post-publish `rubygems-await` step timed out waiting for the RubyGems full index even though the gem was already available through the API/install path. The workflow now sets `await-release: false` to avoid that false negative; use the direct verification commands below when you want explicit propagation proof after a release.
+
 ## Verify the published version
 
 After the workflow succeeds:

data/docs/release/release-environment-protection.md

@@ -0,0 +1,70 @@
+# GitHub Release Environment Protection Rules
+
+## Status
+
+Status: **Configured release-process evidence**
+
+This document records the current GitHub `release` environment protection settings used by the Moose Inventory trusted-publishing workflow.
+
+Initial confirmation date: 2026-05-29
+Protection configuration date: 2026-05-29
+Self-review adjustment date: 2026-05-29
+
+Confirmation/configuration commands:
+
+```bash
+gh api repos/RusDavies/moose-inventory/environments/release --jq '.'
+gh api -X PUT repos/RusDavies/moose-inventory/environments/release --input /tmp/moose-env-release.json
+gh api -X POST repos/RusDavies/moose-inventory/environments/release/deployment-branch-policies -f name='v*'
+gh api repos/RusDavies/moose-inventory/environments/release/deployment-branch-policies --jq '.'
+```
+
+Confirmed repository/environment:
+
+- Repository: `RusDavies/moose-inventory`
+- Environment: `release`
+- Environment URL: `https://github.com/RusDavies/moose-inventory/deployments/activity_log?environments_filter=release`
+- Release workflow: `.github/workflows/release.yml`
+- Release trigger: pushed `v*` tags
+- Release job environment: `release`
+- RubyGems trusted publisher environment: `release`
+
+## Configured settings
+
+| Setting | Configured value | Release-process interpretation |
+| --- | --- | --- |
+| Required deployment reviewers | `RusDavies` | The `release` environment now requires deployment approval by Russ before the release job can proceed. |
+| Prevent self-review | Disabled (`prevent_self_review: false`) | Disabled because OpenClaw/automation pushes use Russ's GitHub account. With `RusDavies` as the only required reviewer, self-review prevention could block Russ from approving a release deployment triggered through his own account. |
+| Wait timer | `0` / none | No arbitrary delay is configured. Human review is the intended release friction. |
+| Deployment branch/tag policy mode | Custom branch policies enabled (`protected_branches: false`, `custom_branch_policies: true`) | The environment uses an explicit allow-list rather than all branches/tags. |
+| Custom deployment policy | `v*` | Intended to align environment deployment eligibility with the release workflow's `v*` tag trigger. GitHub API reports this policy object with `type: branch`; verify behavior on the next real release tag and adjust if GitHub does not apply it to tag deployments as expected. |
+| Admin bypass | Disabled (`can_admins_bypass: false`) | Admins should not be able to bypass environment protection for this environment through the normal bypass setting. |
+
+## Current trusted-publishing path
+
+The current release path relies on these controls:
+
+1. The release workflow only runs on pushed tags matching `v*`.
+2. The GitHub `release` environment requires review by `RusDavies` before the release job can proceed.
+3. Self-review prevention is disabled so `RusDavies` can approve deployments triggered by automation authenticated as Russ's GitHub account.
+4. Admin bypass is disabled for the `release` environment.
+5. The environment has a custom deployment policy named `v*`.
+6. The release workflow verifies that the tag version matches `Moose::Inventory::VERSION`.
+7. The release workflow installs security tools and runs:
+
+   ```bash
+   MOOSE_INVENTORY_REQUIRE_SECURITY_TOOLS=1 ./scripts/check.sh
+   ```
+
+8. RubyGems trusted publishing/OIDC is scoped to repository `RusDavies/moose-inventory`, workflow `release.yml`, and environment `release`.
+9. The package sanity gate verifies the gem payload and executable metadata before publishing.
+
+## Residual verification note
+
+GitHub accepted the custom deployment policy name `v*`, but the deployment-branch-policy API response reports the policy object as `type: branch`. The next real release should verify that a pushed `v*` tag can still deploy to the `release` environment after human approval.
+
+If GitHub treats the custom policy as branch-only and blocks tag deployments, maintainers should either adjust the environment policy to the supported tag pattern mechanism or document the limitation and rely on the workflow's `v*` tag trigger plus tag/version check as the tag-control layer.
+
+## Change-control note
+
+Changing GitHub environment protection settings is repository/release-infrastructure administration. AI agents may document the current state and prepare recommendations, but must not change environment rules without explicit human approval.

data/docs/release/release-readiness.md

@@ -2,6 +2,10 @@
 
 This project now has a small release-readiness gate intended to catch the regressions found during the modernization and security-audit passes.
 
+Reusable QA, documentation-QA, release, security, accepted-risk, rollback, and post-release templates live in `docs/qa/qa-documentation-and-release-gates.md`.
+
+Routine package maintenance and AI-agent operation boundaries live in `docs/maintenance/package-maintenance-and-agent-boundaries.md`.
+
 ## Local gate
 
 Run:
@@ -13,10 +17,19 @@ Run:
 The gate currently runs:
 
 1. RSpec with coverage via the existing spec helper.
-2. `git diff --check` for whitespace/conflict-marker issues in the working tree.
-3. `scripts/ci/check_permissions.sh` to ensure only intentional tracked repository entrypoints are executable.
-4. `scripts/ci/check_security.sh` to query OSV for locked RubyGems dependency advisories.
-5. `scripts/ci/package_sanity.sh` to build the gem, inspect the packaged payload, and smoke-test the CLI version command.
+2. `scripts/ci/check_rubocop.sh` for targeted Ruby style/lint checks.
+3. `git diff --check` for whitespace/conflict-marker issues in the working tree.
+4. `scripts/ci/check_permissions.sh` to ensure only intentional tracked repository entrypoints are executable.
+5. `scripts/ci/check_generated_artifacts.sh` to ensure generated/local artifact paths remain ignored and untracked.
+6. `scripts/ci/check_security.sh` to query OSV, run `bundler-audit`, and run `osv-scanner` when available or required.
+7. `scripts/ci/check_secrets.sh` to run the dedicated `gitleaks` secret scan when available or required.
+8. `scripts/ci/package_sanity.sh` to build the gem, inspect the packaged payload, and smoke-test the CLI version command.
+
+For release evidence, prefer:
+
+```bash
+MOOSE_INVENTORY_REQUIRE_SECURITY_TOOLS=1 ./scripts/check.sh
+```
 
 ## CI gate
 
@@ -38,6 +51,12 @@ The release workflow runs when a `v*` tag is pushed. It:
 
 RubyGems has a trusted publisher configured for repository `RusDavies/moose-inventory`, workflow `release.yml`, and environment `release`, so the workflow can request a short-lived publish token when a real release tag is pushed.
 
+Current GitHub `release` environment protection evidence is recorded in `docs/release/release-environment-protection.md`. As of 2026-05-29, the environment requires review by `RusDavies`, has self-review prevention disabled, disables admin bypass, and has a custom deployment policy named `v*`. Self-review prevention is disabled because OpenClaw/automation pushes use Russ's GitHub account, and `RusDavies` is currently the only required reviewer. Because GitHub reports the custom deployment policy object as `type: branch`, verify tag-deployment behavior on the next real release and adjust the environment policy if needed.
+
+This path was verified with release `v2.0` / gem `2.0`: RubyGems trusted publishing succeeded and the published gem was installable afterward. The release workflow now disables `rubygems/release-gem`'s post-publish await step (`await-release: false`) because RubyGems full-index propagation lag produced false-negative workflow failures even after successful publishes.
+
+Package provenance hardening beyond trusted publishing is evaluated in `docs/release/package-provenance-hardening.md`. The current release-readiness gate does not require additional checksums, GitHub artifact attestations, detached signatures, RubyGems certificate signing, or SBOM publication unless a future consumer or policy requirement explicitly adds that work.
+
 ## Package sanity expectations
 
 `package_sanity.sh` validates that the built gem includes at least:

data/docs/security/accepted-risk-register.md

@@ -0,0 +1,84 @@
+# Moose Inventory Accepted-Risk Register
+
+## Approval status
+
+Status: **Approved register - no accepted risks currently approved here**
+
+Russ / Rusty Frink Desiato approved this register's structure and use as part of the Moose Inventory security/privacy process baseline on 2026-05-29. Approval reference: `GOV-SEC-001`.
+
+Russ / Rusty Frink Desiato separately approved this accepted-risk register as the maintained accepted-risk register baseline for Moose Inventory on 2026-05-29. Approval reference: `GOV-RISK-REG-001`.
+
+This register records security, privacy, release, and supply-chain risks that are intentionally accepted rather than fixed before a defined milestone. A proposed risk is not accepted until an approver records an explicit approval decision.
+
+Approved references:
+
+- `GOV-TAILOR-001`: Moose Inventory is approved as Class 4 with target profile Software Library / Package.
+- `GOV-PRODUCT-001`: `docs/product/product-brief.md` is approved as the product-framing baseline.
+- `GOV-REQ-001`: `docs/product/requirements-baseline.md` is approved as the requirements and acceptance criteria baseline.
+- `GOV-UX-001`: `docs/ux/cli-workflow-notes.md` is approved as the CLI UX/workflow baseline.
+- `GOV-ARCH-001`: `docs/architecture/architecture-and-trust-boundaries.md` is approved as the architecture and trust-boundary baseline.
+- `GOV-SEC-001`: this register's structure and use are approved as part of the security/privacy process baseline.
+- `GOV-RISK-REG-001`: this register is approved as the maintained accepted-risk register baseline.
+
+Scope limit: this register records accepted-risk decisions only. It does not approve a release, compliance claim, public advisory, RubyGems publishing, future architecture/security changes, or acceptance of any proposed/monitored risk listed below. Approval of the register baseline does not convert proposed or monitored risks into accepted risks.
+
+## Acceptance rules
+
+Each accepted risk must include:
+
+- risk ID;
+- decision and scope;
+- severity;
+- affected assets/workflows;
+- rationale for acceptance;
+- compensating controls;
+- owner;
+- review date or trigger;
+- approver and approval date;
+- related issue/commit/document evidence where applicable.
+
+Evidence is not approval. A finding listed under proposed or monitored risks remains unaccepted until explicitly approved.
+
+## Accepted risks
+
+_No accepted risks are currently recorded._
+
+## Proposed or monitored risks
+
+| ID | Status | Severity | Risk | Current controls | Required decision / next action |
+| --- | --- | --- | --- | --- | --- |
+| RISK-SEC-001 | Monitored, not accepted as permanent | Medium | GitHub secret scanning is unavailable/disabled in current repository evidence, so GitHub-native secret scanning cannot be relied on as a control. | Local/CI `gitleaks` gate, `MOOSE_INVENTORY_REQUIRE_SECURITY_TOOLS=1 ./scripts/check.sh`, docs warning against committing secrets. | Revisit if GitHub secret scanning becomes available. If releases rely on this limitation long-term, record an explicit accepted-risk decision or enable equivalent control. |
+| RISK-SEC-002 | Evaluated, not accepted as release blocker | Low | Additional signed provenance/artifact attestations beyond RubyGems trusted publishing are not a current requirement. | RubyGems trusted publishing/OIDC, package sanity check, release workflow gate, package provenance hardening evaluation. | Revisit if security-sensitive consumers, release policy, or supply-chain requirements justify checksums, GitHub artifact attestations, signatures, or SBOM publication. |
+| RISK-SEC-003 | Open process gap, not accepted | Medium | Public vulnerability intake is informal without a repo-local `SECURITY.md` or private advisory workflow documented for users. | GitHub issues for non-sensitive reports, maintainer/private coordination where available, security audit docs. | Decide whether to add public `SECURITY.md` as part of security/privacy baseline approval or maintenance runbook work. |
+| RISK-SEC-004 | Open UX gap, not accepted | Medium | Destructive CLI commands do not yet have a consistent explicit confirmation / `--yes` pattern. | Explicit command names, dry-run support, tests, UX implementation backlog. | Complete UX implementation backlog item before expanding destructive behavior. |
+| RISK-SEC-005 | Mitigated release-governance gap, monitor next release | Low | GitHub `release` environment protection rules were absent when first documented on 2026-05-29. They are now configured with required reviewer `RusDavies`, self-review prevention disabled, admin bypass disabled, and a custom `v*` deployment policy. Self-review prevention is disabled because OpenClaw/automation pushes use Russ's GitHub account, and `RusDavies` is currently the only required reviewer. GitHub reports the custom policy object as `type: branch`, so tag-deployment behavior still needs verification on the next real release. | Release workflow only runs on `v*` tags, verifies tag/version alignment, runs full security-required check gate, uses RubyGems trusted publishing/OIDC, and now requires environment review before the release job proceeds. | Verify next real `v*` tag release can deploy after approval. If the custom policy blocks tags, adjust the environment policy or document the GitHub limitation. |
+
+## Accepted-risk template
+
+```markdown
+### RISK-SEC-XXX: Short risk name
+
+- Status: Proposed | Accepted | Retired
+- Severity: Critical | High | Medium | Low
+- Affected assets/workflows:
+- Decision scope:
+- Risk statement:
+- Rationale for acceptance:
+- Compensating controls:
+- Owner:
+- Review trigger/date:
+- Approver:
+- Approval date:
+- Evidence:
+```
+
+## Review cadence
+
+Review this register:
+
+- before each material public release;
+- when `scripts/check.sh` or security tooling changes;
+- when a security audit finds a new issue;
+- when a dependency advisory affects the supported dependency set;
+- when release infrastructure, RubyGems trusted publishing, or GitHub environment protection changes;
+- when a proposed risk is accepted, retired, or no longer accurate.