Outcome

Schema 2.0, explicit consumer dispatch, source-bound local execution, one public runner, and deletion of capsule execution.

OpenSpec change: code-review-19-local-report-and-cutover

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: #513, #514.

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: Versioned local evidence has explicit consumers

The producer SHALL emit schema 2.0 with local execution provenance, actual tool versions, effective configuration references, source and dependency identity, and per-check completion. Consumers SHALL dispatch explicitly by supported schema version. Historical schema 1.6 SHALL retain its original meaning without synthesized capsule fields.

Scenario: New major version is not legacy evidence

• GIVEN a schema 2.0 report reaches a helper that historically used a schema-at-least-1.6 test
• WHEN the updated consumer selects its interpretation
• THEN it selects the explicit local schema handler and does not invoke capsule-profile validation

Scenario: Unknown major or malformed required evidence

• GIVEN a report has an unsupported major version or malformed completion facts
• WHEN a consumer evaluates the report
• THEN it rejects or reports incomplete evidence and never falls back to score-based or fabricated legacy acceptance

Requirement: Findings and execution completeness are separate

A failed test or detected defect SHALL remain a completed check with findings. Preparation failure, timeout, malformed output and missing required checks SHALL remain incomplete. Existing changed, full and shadow selection semantics SHALL be retained subject to explicit local-schema handling, without introducing C15 calibration or waiver authority.

Scenario: Completed failing test

• GIVEN pytest collects and executes the selected test and its assertion fails
• WHEN the review aggregates results
• THEN the test failure remains observed evidence and is not relabeled as infrastructure uncertainty

Scenario: Incomplete required analysis in shadow

• GIVEN a required analyzer times out or cannot execute
• WHEN review runs in shadow and then in a non-shadow enforcement mode
• THEN both reports retain adverse truth and incomplete status while shadow may exit zero and non-shadow enforcement remains nonaccepting

Requirement: Execution binds the reviewed source

Worktree review SHALL verify relevant source stability during execution. Index and range execution SHALL prepare project context against the corresponding materialized source snapshots. Editable imports, generated code and native artifacts from another checkout SHALL not establish snapshot-bound evidence.

Scenario: Live editable import points outside snapshot

• GIVEN a range snapshot differs from the live checkout used by an existing editable installation
• WHEN a dynamic check is requested for the snapshot
• THEN review prepares faithful snapshot context or marks that check incomplete instead of reporting live-checkout execution as snapshot evidence

Scenario: Source changes during worktree review

• GIVEN a relevant input changes while checks execute
• WHEN review finalizes its source identity
• THEN it reports stale or incomplete evidence rather than attributing all results to one unchanged source

Requirement: Local evidence cannot grant protected authority

Local execution SHALL not emit effective protected pr_range authority. Immutable source selection, an installed signed module, or a caller-supplied PR context SHALL not manufacture capsule attestation or satisfy the existing protected C14 consumer contract.

Scenario: Caller supplies PR context

• GIVEN a local range invocation supplies matching base/head references and a claimed PR context
• WHEN the producer emits schema 2.0
• THEN the report remains local evidence and a protected consumer cannot promote it using the old capsule contract

Scenario: Historical differential behavior

• GIVEN compatible base and head local analyses use the same supported check and policy identities
• WHEN findings are compared
• THEN existing identity, multiplicity, differential and suppression semantics are preserved, and incompatible identities remain unknown

Requirement: Public cutover removes capsule execution

The public cutover SHALL route all review scopes through one local orchestrator and remove both native macOS and Linux OCI/Bubblewrap capsule paths and the parallel legacy host orchestrator. It SHALL remove callable capsule fallback switches while preserving module signatures, source integrity, bounded subprocess execution, and independent security gates.

Scenario: No capsule prerequisite or fallback

• GIVEN a customer invokes review on a supported ordinary host without a capsule, native broker or user namespaces
• WHEN the local release executes
• THEN it uses the selected project and analyzer contexts without acquiring or launching any capsule backend

Scenario: Capsule capability is removed without false completion

• GIVEN the replacement is implemented and integrated
• WHEN legacy catalogs, native builds, capsule-only release jobs and capability declarations are reconciled
• THEN obsolete guarantees are removed by the owning implementation deltas and historical signed artifacts remain immutable

Implementation design

Design for local review evidence and capsule removal

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

Introduce local schema 2.0 with explicit consumers and source-bound execution. Preserve useful scope/differential behavior and perform the single public cutover that deletes capsule execution and the legacy host orchestrator.

Create an explicit local report schema 2.0. Carry source/dependency/configuration/tool identities and per-check completion with findings independently. Update modules-side pre-commit/report helpers and compatibility fixtures together. The paired core change updates ordinary core consumers. Current major > 1 or ... >= 1.6 helpers must not choose the legacy handler for 2.0. Reject unknown major versions and malformed required evidence.

Keep worktree/index/range/full/explicit selection, source spans, identity/multiset/differential logic and suppression comparison where compatible. Match check/policy identities for comparisons. A worktree source change invalidates the result. Index/range preparations bind each source snapshot; a live editable import, generated file or native artifact from another checkout cannot supply snapshot execution evidence.

Completed failing tests remain findings. Missing required checks, failed preparation, malformed output and timeout remain incomplete and nonaccepting outside shadow. Shadow preserves adverse truth. Do not introduce C15 calibration, suppression approval authority, or schema 1.7 promises here.

Perform the public runner switch and production deletions in one cutover. Adapt useful pure helpers rather than redirecting to the existing SpecFact-specific host runner. Delete callable native macOS and Linux OCI/Bubblewrap paths, capsule acquisition, brokers, import policing, sealed dependency/native-library copying, catalogs and permanent fallback toggles. Later distribution cleanup may remove residue but cannot leave a callable old runtime. Preserve module signatures, source integrity, process timeouts and independent security gates.

The implementation delta must explicitly remove/replace applicable capsule requirements before archival. Neither local immutable scope nor caller PR context creates protected pr_range; existing core #680 remains a separate incompatible protected contract. Historical artifacts and report readers retain original semantics.

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.