Outcome

pipx, uv tool and repeated uvx installation acceptance, supported platforms, replacement CI, migration documentation and coordinated signed release.

OpenSpec change: code-review-20-external-installation-acceptance

Confirmed design

The owner approved the capsule hard cut on 2026-10-16, Europe/Berlin. Customers review trusted repositories. Dependency installation, build hooks, imports, and configured checks may execute locally. SpecFact stays outside the customer environment and respects customer dependencies, locks, coding standards, plugins, and entrypoints. No hostile-code containment is claimed.

This issue tracks future implementation. The current delivery creates architecture/specification artifacts and aligns GitHub metadata only. Implementation tasks remain unchecked. Planning validation is not runtime acceptance or RED/GREEN evidence.

Acceptance

• Preserve customer dependency declarations and locks; install no SpecFact dependencies into customer environments.
• Report unavailable required checks as incomplete, with actionable diagnostics.
• Keep actual findings, source identity, analyzer versions, and execution completeness distinct.
• Use spec -> tests -> genuine failing evidence -> implementation -> passing evidence in follow-up sessions.
• Pass applicable quality/security/signature gates and exact installed acceptance before claiming delivery.

Relationships

Parent: #163, within Epic #162.

Direct implementation blockers: #515, nold-ai/specfact-cli#769.

Canonical architecture: nold-ai/specfact-cli-modules/openspec/changes/code-review-17-project-runtime-bootstrap/design.md.

Capsule-only #460, #488, #495, #512 and modules PR #506, #509, #510 are superseded as recorded by the replacement plan. Preserve historical releases and independent signing/security work. C15 and protected C14 assurance remain separate; no local report is protected pr_range evidence. Optional preflight and architecture/requirements add-ons are future consumers, not prerequisites.

Planned requirement scenarios

ADDED Requirements

Requirement: External installation survives fresh invocations

Acceptance SHALL exercise clean pipx, uv tool and repeated uvx invocations with installed modules and independent customer Python. Module discovery and dependency availability SHALL not require installing SpecFact into the customer environment or mutating disposable tool environments through unmanaged pip operations.

Scenario: Fresh pipx and uv tool installations

• GIVEN the CLI and signed modules are installed outside a clean customer project
• WHEN the customer bootstraps and reviews through each persistent tool route
• THEN the command loads its modules, uses project Python, detects a seeded defect and leaves project declarations and existing environment package inventory unchanged

Scenario: Repeated uvx invocation

• GIVEN one uvx invocation installs or discovers user-scoped modules and a later fresh uvx invocation runs review
• WHEN the disposable controller environment differs
• THEN module loading and declared dependencies work through supported installation paths without relying on a previously mutated uvx environment

Requirement: Published compatibility follows installed evidence

The release SHALL validate Linux, macOS and Windows against the supported CLI Python matrix and record project-interpreter and analyzer capabilities separately. Manager support SHALL require faithful existing and cold project execution. Missing optional capability SHALL not become an unsupported blanket runtime claim.

Scenario: Manager and platform corpus

• GIVEN pip/pip-tools, detached Hatch, locked uv and Poetry projects have representative supported host cells
• WHEN installed acceptance runs
• THEN each advertised cell demonstrates imports, entrypoints, native dependencies, plugins, configured checks and seeded defect detection or remains explicitly unadvertised

Scenario: Independent Python support

• GIVEN a project interpreter differs from the CLI matrix and is admitted by its manager
• WHEN compatible project commands and supplemental checks run
• THEN their actual compatibility is recorded independently of the controller version and no capsule ABI allowlist rejects the whole project

Requirement: CI replacement preserves independent gates

Capsule-only CI, native build and release requirements SHALL be replaced with installed customer-workflow acceptance without weakening independent source, quality, security, signing or review checks. Producer and ordinary consumer compatibility SHALL be verified before stable downstream adoption.

Scenario: Capsule-specific job is retired

• GIVEN the local implementation and paired core consumer are ready for installed verification
• WHEN workflow requirements are updated through their own spec and tests
• THEN replacement customer acceptance remains required and unrelated signing/security obligations including module symlink rejection are preserved

Scenario: Required installed cell fails

• GIVEN a required clean-install or customer-workflow cell fails or times out
• WHEN release readiness is assessed
• THEN the release is not declared accepted and a passing component suite cannot substitute for that workflow

Requirement: Coordinated release and rollback are explicit

The release SHALL use a breaking major for Code Review and appropriate Codebase/core compatibility updates, normal module signing and canonical publication. Migration documentation SHALL state trusted-local execution, removed containment claims, report compatibility, installation routes, supported cells and rollback to an immutable compatible CLI/module pair.

Scenario: Release artifacts are immutable

• GIVEN new local-runtime artifacts are signed and published by normal reviewed tooling
• WHEN customers migrate
• THEN old signed capsules, modules and historical reports remain unchanged and do not inherit new local support claims

Scenario: Rollback after consumer incompatibility

• GIVEN installed acceptance finds an incompatible ordinary consumer
• WHEN the migration is rolled back
• THEN the previous compatible released CLI/module pair can be pinned without restoring a permanent alternate capsule backend in the new production runner

Implementation design

Design for external installation and customer acceptance

Canonical architecture

Change 17 design (nold-ai/specfact-cli-modules/openspec/changes/code-review-17-project-runtime-bootstrap/design.md) owns the architecture, API sketch, trust decisions, alternatives, acceptance matrix and synthesis. This document records only this change's implementation responsibility. No runtime implementation or supported distribution is established here.

Responsibility and data flow

Exercise exact signed installed distributions through pipx, uv tool and repeated uvx. Replace capsule-only CI, document the compatibility/trust migration and prepare a coordinated breaking release with rollback.

The acceptance subject is the exact installed compatible CLI/module pair, not a source checkout or candidate self-report. Test pipx and uv tool with user-scoped modules, then test a fresh repeated uvx invocation. Current module installation may assume sys.executable -m pip; a disposable tool environment may lack pip or must not be mutated unmanaged. Resolve this with the paired core ordinary-installation contract and supported declared/tool installation mechanisms, without installing anything into customer environments.

Exercise existing and cold manager contexts with project/controller Python differences, entrypoints, native extensions/libraries, generated modules, pytest plugins and project-specific standards. Preserve existing environment package inventory and lock/declaration bytes. Attribute ordinary trusted hook outputs separately. Required cell failure or timeout stays nonaccepting. Advertise only passing host/project/analyzer cells, recording capabilities separately from controller support.

Replace capsule-only customer jobs, native builds, publication/signing infrastructure and support docs with required local installed acceptance. Keep independent security, signing, quality and review gates. Modules #511 and core #718/#719 remain independent obligations. Optional preflight, architecture and requirements context do not block this release.

Release Code Review as a breaking major and make truthful Codebase/core compatibility changes. Update docs with existing modules.specfact.io permalinks, native help, tool installation routes, report trust/compatibility and rollback. Use normal canonical publication/signatures. Immutable old releases remain available. A planning PR publishes nothing and cannot satisfy release acceptance.

Implementation reconciliation and first step

All implementation remains pending. Accepted interface or responsibility deviations must update the canonical design and this delta before handoff. Start by adding scenario-mapped behavior tests and capturing actual failing evidence. Preserve existing applicable governance while implementing the approved replacement.

Risks and rollback

Wrong interpreter/source, dependency drift and overstated completion are the primary risks. Verify actual executable/source identities, native configuration and failure behavior. Keep an immutable compatible released pair for rollback. No permanent capsule backend remains in the replacement.