fix(mcp-runtime): harden scenario runtime and cockpit feedback

.github/workflows/ci.yml

@@ -43,7 +43,7 @@ jobs:
       - name: Pre-commit
         run: pre-commit run --all-files
       - name: Type check
-        run: mypy src/vaner/__init__.py src/vaner/server src/vaner/cli/main.py
+        run: mypy src/vaner/__init__.py src/vaner/server.py src/vaner/cli/main.py
       - name: Tests
         run: pytest tests -m "not slow and not integration" --cov=src/vaner --cov-fail-under=70
       - name: Upload coverage

CONTRIBUTING.md

@@ -11,7 +11,18 @@ pip install -e ".[dev]"
 pre-commit install
 ```
 
-Run checks before opening a PR:
+## Testing Policy
+
+Major behavior changes must add or update automated tests in `tests/`.
+"Major" includes any change that modifies public CLI behavior, routing behavior,
+context selection outcomes, config parsing, security/privacy behavior, or
+release/build behavior.
+
+When in doubt, add or update a test and document the expected behavior in the PR.
+
+## Running Tests (Local and CI)
+
+Local contributor checks:
 
 ```bash
 ruff check .
@@ -21,12 +32,54 @@ pytest
 pre-commit run --all-files
 ```
 
-If dependency ranges change, regenerate hash-locked workflow/runtime dependency files:
+CI checks on pull requests and pushes:
+
+- Lint and formatting checks
+- Type checking
+- Automated test suite (`pytest`)
+- Pre-commit hooks
+- Security checks such as `pip-audit`
+
+Pull requests are expected to pass required CI checks before merge.
+
+## Dependency and Supply-Chain Hygiene
+
+Direct dependencies are declared in `pyproject.toml`.
+Hash-locked dependency sets used by CI/release/runtime live under `requirements/*.txt`.
+
+If dependency ranges change, regenerate lockfiles:
 
 ```bash
 make lockfiles
 ```
 
+Dependency updates must preserve reproducible installs and keep hashes pinned in
+the generated requirements files.
+
+Security and license issues in dependencies must be triaged before release.
+See `SECURITY.md` for remediation policy details.
+
+## Artifact and Binary Commit Policy
+
+Do not commit generated executable artifacts or unreviewable binary artifacts
+to source control.
+
+Allowed binary assets are limited to reviewable project resources such as
+documentation images and similar non-executable assets.
+
+Release artifacts must be generated by release workflows and attached to
+releases; they must not be committed to the repository.
+
+Run checks before opening a PR:
+
+```bash
+ruff check .
+ruff format --check .
+mypy src
+pytest
+pre-commit run --all-files
+```
+
 ## Pull Requests
 
 - Keep PRs focused and reviewable.
@@ -52,6 +105,12 @@ git commit -s -m "your message"
 
 This adds a `Signed-off-by:` trailer to the commit.
 
+Repository setting note:
+
+- GitHub web-based commits currently require sign-off.
+- For CLI-based commits, contributors are still responsible for adding DCO
+  sign-off using `-s`.
+
 ## Scope Guidance
 
 - Keep core focused on predictive context middleware.

GOVERNANCE.md

@@ -14,6 +14,53 @@ This repository follows a stewarded open-source model.
 - Keep CI, release, and security hygiene in good standing.
 - Enforce contribution and code-of-conduct policies.
 
+## Sensitive Resource Access
+
+Sensitive resources include:
+
+- repository admin and branch/ruleset configuration
+- release publishing channels (GitHub Releases, package registries, container registries)
+- CI/CD secrets and deployment credentials
+- security disclosure handling channels
+
+Access to sensitive resources follows least-privilege principles and should be
+limited to maintainers with a clear operational need.
+
+## GitHub Enforcement Snapshot
+
+Current GitHub configuration relevant to access control and change control:
+
+- Organization default repository permission is `read`.
+- Branch protection on `main` enforces required checks and review gates.
+- GitHub Actions default workflow token permission is `read`.
+
+Current limitation:
+
+- Organization-wide mandatory 2FA is not yet enabled.
+  Until this is enabled, maintainer accounts are expected to use strong MFA
+  individually and to keep session/device hygiene strict.
+
+## Elevated Permission Grant Policy
+
+Before granting elevated permissions to a collaborator, maintainers should:
+
+1. confirm a sustained record of constructive contributions
+2. confirm identity and communication channels sufficient for coordinated response
+3. document the requested access scope and rationale
+4. grant the minimum required permission set
+5. record who approved the grant and when
+
+Where feasible, at least one existing maintainer other than the requestor should
+review and approve the grant.
+
+## Elevated Permission Review and Revocation
+
+- Access grants should be reviewed periodically and reduced when no longer needed.
+- Elevated access must be revoked promptly after role changes, inactivity, or
+  suspected compromise.
+- Security-relevant access changes should be traceable through repository/org
+  audit records.
+
 ## Future evolution
 
 As the maintainer group grows, this file can evolve into a formal voting and RFC process.

MAINTAINERS.md

@@ -9,3 +9,27 @@ Scope:
 - Review pull requests and maintain issue hygiene
 - Keep release workflows healthy
 - Maintain community and contribution standards
+
+## Sensitive Resource Roles
+
+Current sensitive-resource operator assignments:
+
+- Repository administration and branch/ruleset management: `@abolsen`
+- Release management (GitHub Releases, package/container publishing): `@abolsen`
+- CI/CD and repository secret administration: `@abolsen`
+- Security triage and advisory publication: `@abolsen`
+
+## Access Model
+
+Vaner currently operates as a single-maintainer project.
+This creates unavoidable cases where self-approval or admin override may be
+required to keep releases and security fixes moving.
+
+Compensating controls include:
+
+- required CI and security automation checks on pull requests and main branch
+- public change history and release artifacts
+- documented security disclosure and advisory process in `SECURITY.md`
+
+As additional maintainers are onboarded, Vaner will move toward dual-control for
+sensitive operations (review and approval by a second maintainer).

README.md

@@ -71,6 +71,8 @@ Most documentation lives at [docs.vaner.ai](https://docs.vaner.ai):
 
 - Contributing guide: `CONTRIBUTING.md`
 - Security policy: `SECURITY.md`
+- Governance model: `GOVERNANCE.md`
+- Maintainer roles and sensitive-resource ownership: `MAINTAINERS.md`
 - Code of conduct: `CODE_OF_CONDUCT.md`
 - Support channels: `SUPPORT.md`
 - Examples: `examples/`

SECURITY.md

@@ -2,7 +2,17 @@
 
 ## Supported Versions
 
-Security fixes are applied to the latest release line.
+Security fixes are applied to the latest stable release line.
+Pre-release or experimental builds may receive best-effort fixes but are not
+guaranteed a patch window.
+
+Current support intent:
+
+- Latest stable release line: receives security fixes.
+- Older release lines: may be closed to security fixes after a newer stable line
+  is published.
+- End-of-support for an older line is communicated through release notes and/or
+  GitHub Security Advisories.
 
 ## Reporting a Vulnerability
 
@@ -20,25 +30,137 @@ For encrypted disclosure channels and additional process details, also see [docs
 - Triage and severity assessment within 7 days
 - Coordinated disclosure target within 90 days from initial report, unless a different disclosure window is agreed with the reporter
 
+## Public Vulnerability Publication
+
+Vaner uses GitHub Security Advisories as the canonical public disclosure channel
+for confirmed vulnerabilities.
+
+Advisories should include, when available:
+
+- affected version ranges
+- fixed version(s)
+- mitigation or workaround guidance
+- severity and impact notes
+
 ## Code Review & Branch Protection
 
-The `main` branch is protected with linear history, admin enforcement, strict status checks, and pull-request review gates.
-Required status checks include `verify (ubuntu-latest, 3.12)`, `examples-smoke`, `no-moat-paths`, and `actionlint`.
+The `main` branch is protected with:
+
+- linear history enforcement
+- admin enforcement
+- strict required status checks
+- required pull-request review gates
+- required conversation resolution
+- disabled force-pushes and branch deletion
+
+Configured required status checks currently include:
+
+- `verify (ubuntu-latest, 3.12)`
+- `examples-smoke`
+- `no-moat-paths`
+- `actionlint`
+
+Configured review requirements currently include:
+
+- code owner review required
+- last-push approval required
+- two approving reviews required
 
 Vaner is currently maintained by a single maintainer. Self-merges run through CI, CodeQL, actionlint, and zizmor checks and may use GitHub admin override when review requirements cannot be satisfied by a second maintainer.
 
 The OpenSSF Scorecard `Code-Review` signal can remain low in this solo-maintainer period until additional reviewers are onboarded.
 
+## GitHub Security Features (Current)
+
+The repository currently has these GitHub security features enabled:
+
+- Security policy
+- Security advisories
+- Dependabot alerts and security updates
+- Code scanning alerts
+- Secret scanning alerts
+- Secret scanning push protection
+
+Current notable settings:
+
+- Private vulnerability reporting in GitHub is disabled; private disclosure is
+  handled via `security@vaner.ai`.
+- GitHub Actions default workflow token permissions are set to read-only.
+
 ## Disclosure Process
 
 After a vulnerability report is received, Vaner maintainers validate impact, assign severity, and coordinate remediation before public disclosure.
 Coordinated vulnerability disclosure is used for all confirmed issues to reduce risk to users.
 
+## Secrets and Credentials Policy
+
+Vaner must not store plaintext production secrets in version control.
+This includes API keys, long-lived tokens, signing keys, private certificates,
+passwords, and credential dumps.
+
+Required controls:
+
+- Keep secrets in GitHub Secrets, environment variables, or equivalent secret
+  stores; never hardcode them in committed source.
+- Restrict secret access to maintainers who need operational access.
+- Rotate credentials after suspected exposure, maintainer offboarding, or
+  provider-initiated compromise events.
+- Revoke and replace leaked credentials immediately, then document remediation in
+  the incident/advisory record as appropriate.
+
+Repository scanning:
+
+- GitHub Secret Scanning alerts are enabled.
+- Contributors are expected to review diffs and avoid committing sensitive files.
+
+## SCA (Dependency Vulnerability and License) Policy
+
+Vaner uses software composition analysis (SCA) checks, including `pip-audit`, to
+surface dependency risk.
+
+Remediation thresholds:
+
+- Critical or High vulnerabilities in runtime dependencies must be remediated or
+  formally risk-accepted before release.
+- Medium vulnerabilities must be triaged before release with either remediation
+  or explicit risk acceptance and timeline.
+- License issues that conflict with project licensing/distribution requirements
+  must be resolved before release.
+
+Suppression policy:
+
+- Temporary suppressions require maintainer approval, a written rationale, and
+  an expiration/revisit date.
+- Suppressions must be removed when an upstream fix becomes available and is
+  compatible.
+
+## SAST Policy
+
+Vaner uses static analysis tooling (including CodeQL) to detect code-level
+security weaknesses.
+
+Remediation thresholds:
+
+- Critical or High findings in changed code must be remediated or formally
+  risk-accepted before merge.
+- Findings affecting release artifacts must be remediated or risk-accepted before
+  release.
+
+Suppression policy:
+
+- Suppression requires maintainer approval with documented justification.
+- Suppressions should be narrowly scoped and periodically reviewed.
+
 ## Security Documentation
 
 Public-facing security and privacy guidance is published at
 [docs.vaner.ai/security](https://docs.vaner.ai/security).
 
+Additional repository security artifacts:
+
+- `docs/threat-model.md`
+- `docs/security-assessment.md`
+
 ## Verify Release Integrity
 
 Verify container image signatures (keyless OIDC via GitHub Actions):

SUPPORT.md

@@ -4,6 +4,22 @@
 
 - Start with [docs.vaner.ai](https://docs.vaner.ai) for usage, architecture, and CLI guides.
 
+## Release Support Scope
+
+Vaner support currently follows a latest-line support model:
+
+- The latest stable release line receives bug and security fixes.
+- Older release lines may be placed into maintenance-only or end-of-support
+  status after a newer stable line is published.
+- Security support commitments are documented in `SECURITY.md`.
+
+Support scope by release phase:
+
+- Alpha/pre-1.0: best-effort compatibility and faster iteration; breaking
+  changes may occur between minor releases.
+- Stable release lines: stronger compatibility expectations and prioritized
+  fix response for regressions/security issues.
+
 ## Questions and feature ideas
 
 - Open a GitHub Discussion in the `Borgels/Vaner` repository.
@@ -17,3 +33,4 @@
 
 - Report vulnerabilities privately via `security@vaner.ai`.
 - Do not open public issues for security disclosures.
+- Public vulnerability disclosures are published via GitHub Security Advisories.