ai-safe2-framework

safe2 CLI 1.0 migration and compatibility

Upgrade to 1.1.0

Publication status (verified 2026-10-16): 1.1.0 is a source candidate; 1.0.1 is the latest PyPI release. Use a reviewed clone with python -m pip install ".[all]" to try 1.1.0 now. The package-index upgrade command below applies only after 1.1.0 is published.

1.1.0 adds the backward-compatible safe2 start guided onboarding command and two additive contracts: safe2.onboarding-plan.v1 and safe2.onboarding-result.v1. Existing 1.0 commands and evidence schemas remain available. The new command is preview-only unless --execute is supplied; an interactive confirmation or explicit --yes is also required. It never overwrites configuration or evidence.

python -m pip install --upgrade "ai-safe2[all]==1.1.0"
safe2 self-check --strict
safe2 start .

Review the plan before adding --execute. Existing automation does not need to migrate unless it chooses the guided workflow. Rollback means using a fresh environment with 1.0.1; retain 1.1.0 evidence with its producing version.

Upgrade to 1.0.1

1.0.1 is the first 1.0 build on PyPI; 1.0.0 was published on GitHub only. Commands and schemas are unchanged from 1.0.0. Scores and gate results can change: self-attested MCP controls no longer add points, detected tool-schema poisoning caps the score and fails safe2 gate mcp, the skill trust gate blocks more hostile patterns, and a CRITICAL finding caps the project gate. Re-run gates rather than reusing 1.0.0 or 0.9.x results. DEP findings now report CP.5.MCP control MCP-4 (was MCP-3), matching the v3.1 control map.

python -m pip install --upgrade "ai-safe2[all]==1.0.1"
safe2 --version
safe2 self-check --strict

Upgrade from 0.9.9 to 1.0.0

CLI 1.0.0 promotes the hardened 0.9.9 command and schema surface without renaming public safe2 commands. Upgrade in a new virtual environment when possible, retain evidence with the CLI version that produced it, and run:

python -m pip install --upgrade "ai-safe2[all]==1.0.0"
safe2 --version
safe2 self-check --strict
safe2 acceptance run ./safe2-1.0-acceptance --strict
safe2 acceptance verify ./safe2-1.0-acceptance

1.0.0 never reached PyPI. To reproduce 1.0.0 evidence exactly, install its release tag: python -m pip install "ai-safe2[all] @ git+https://github.com/CyberStrategyInstitute/ai-safe2-framework@2026-10-5_CLI_1.0.0".

Do not overwrite an earlier acceptance directory. To roll back, create a fresh environment with the previously trusted package version and replay artifacts using their producing version. A package downgrade does not migrate or rewrite evidence.

The legacy mcp-score, mcp-scan, and mcp-safe-wrap entry points remain deprecated compatibility aliases for 1.0. New automation must use safe2. See CLI stability policy for the supported contract and deprecation rules.

Verify upgrades in the 0.9.x series

After installing or upgrading, run safe2 self-check --strict. The command is offline and distinguishes an unsupported runtime or missing dependency (fail) from an installation whose metadata or newer Python version is not yet qualified (hold). It also verifies that every packaged evidence contract can be loaded and fingerprints the catalog. See Installation Self-Check.

Existing mcp-score, mcp-scan, and mcp-safe-wrap aliases remain available, but new automation should use the safe2 command surface. New 0.9.x evidence commands are additive and do not silently rewrite prior artifacts; retain the CLI version recorded by each artifact and use its producing version for replay.

PART 3 diagnosis: “Two failed release rounds. Parallel half-builds compete with each other.” This is that consolidation. Before this change, four CLI-shaped security tools existed in this repo, none installable from the repo root, none aware of each other:

Old location What it did New home
scanner/ (no console entry point at all) 161-control static project audit safe2 scan project / safe2 gate project / safe2 score project
scripts/skill_trust_gate.py (loose script, no package) Skill package trust gate safe2 scan skill / safe2 gate skill
examples/mcp-security-toolkit/ (filed as an example; mcp-score, mcp-scan, mcp-safe-wrap, 134 tests) MCP server static/remote scanning + runtime wrapping safe2 scan mcp / safe2 score mcp / safe2 gate mcp / safe2 mcp wrap-stdio / safe2 mcp wrap-proxy
gateway/ (separate ai-safe2-gateway package) Runtime enforcement proxy safe2 serve (thin launcher; still its own package, now reachable through one entry point)

One package now, ai-safe2, one console script, safe2, with operational groups for scanning, gating, scoring, reporting, MCP protection, attributed evidence collection, AISM decision support, and executable examples.

Agent-facing AISM and evidence additions

AI SAFE² remains 161 controls and CP.1 through CP.10. UAS is identified as the UAS-1.0 regulatory profile extension with 27 profile requirements; it does not increase the core control count or create CP.11 as a core Cross-Pillar control.

Ship criterion (met)

git clone <repo>
cd ai-safe2-framework
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all,dev]"
pytest tests/ scanner/tests/

The consolidated suite includes the original 214 tests plus AISM, UAS profile, NEXUS evidence, SkillSpector adapter, and executable-example tests. Run it rather than relying on a fixed historical count:

pytest tests/ scanner/tests/

The suite includes tests/test_cli_smoke.py and tests/test_skill_gate_engine.py, the original scanner/tests/, and the original MCP toolkit suite (tests/mcp_toolkit/, moved unchanged from examples/mcp-security-toolkit/tests/ except for five path-resolution fixes — see below).

What actually changed in the code, vs. what’s just new glue

Exit-code contract (new — see safe2/commands/gate.py)

The three old tools each had their own gate semantics: skill_trust_gate.py returned bare 0/2, mcp-scan --ci and mcp-score --ci-fail-below both used bare 0/1, and scanner/cli.py’s tier logic was a fourth variant. safe2 gate * now uses one contract everywhere: 0 pass, 1 fail/reject, 2 hold for review (skill gate only), 3 input error. Update any CI pipeline that was shell-scripted against the old bare 0/1 assumptions.

Backward compatibility

pip install ai-safe2 still installs mcp-score, mcp-scan, and mcp-safe-wrap as console scripts (pointed at the same underlying code), so the old README’s pip install aisafe2-mcp-tools instructions don’t break anyone already using them. They’re marked deprecated in favor of safe2 scan mcp / safe2 score mcp / safe2 mcp wrap-*.

Deliberately out of scope this pass

To finish the migration in the real repo

This was built and tested in a local clone; nothing has been pushed. Once reviewed:

git add safe2/ aisafe2_mcp_tools/ pyproject.toml MIGRATION.md \
        scripts/skill_trust_gate.py examples/mcp-security-toolkit/README.md \
        tests/
git commit -m "Consolidate scanner, skill trust gate, and MCP toolkit into one safe2 CLI"

Leave examples/mcp-security-toolkit/src and scripts/skill_trust_gate.py in place until you’re satisfied the new paths are solid in production, then git rm -r examples/mcp-security-toolkit/src (keep its README’s redirect notice, or remove the whole directory) and the deprecated script.

Done 2026-10-07: the duplicate src/, tests/, examples/ and pyproject.toml under examples/mcp-security-toolkit/ were removed; only the redirect README remains. The duplicate still carried the pre-fix remote scorer.

Known pre-existing scanner limitation (not introduced by this change)

Running safe2 scan project against safe2/ itself surfaces false positives from the 161-control heuristics — e.g. it flags subprocess.call(["uvicorn", ...]) in safe2/cli.py as “LLM API call without logging context.” The pattern-matching is keying on generic subprocess/call shapes, not actual LLM API usage. This is an existing characteristic of scanner/rules/’s heuristics, unchanged by this consolidation — worth a follow-up pass on the P4/P5 rule precision, flagged here rather than silently left for someone to rediscover.