Repository navigation
[Change] Implement truthful Code Review scope and differential enforcement #416
Description
Why
specfact code review run --scope changed currently describes local worktree changes rather than a committed pull-request delta. Git-resolution failure can collapse into an empty selection and produce false-green evidence. C14 must make scope and uncertainty explicit before the project makes PR-range assurance claims.
Parent and coordination
- Parent Feature: Validation Evidence And Governance Runtime Follow-Ups #163
- Parent Epic: specfact code / AI-bloat defense #162
- OpenSpec change:
code-review-14-scope-truth-and-differential-enforcement - Planning PR: docs(openspec): define truthful differential review scope #413 (merged; planning only)
- Main→dev synchronization PR: chore: synchronize main ancestry into dev for C14 #415 (merged)
- Requested issue type: User Story
- Project:
SpecFact CLI - Requested project status:
Todo - Assignee:
djm81 - Native blocked-by set: none; the planning contract and branch synchronization are complete
- Native blocking set: none yet; the separate core adoption implementation issue does not exist and must be created only after the signed module handoff
- Requirements R07/R08 are independent and do not block C14
Immutable compatibility contract
The first signed C14 release may advertise only core_compatibility: '===0.55.1', proven against lightweight core tag v0.55.1, full commit b1e517e60e669eaba15a18ecfa83ef5a9df65276, and full tree 47984be5434d7ae65ed6908bf525a32053290337. Ordinary equality, local aliases, ranges, wildcards, branch fallbacks, or another identity are not accepted.
What changes
- Resolve explicit worktree, index, range, full, and positional-file scopes with immutable evidence and fail-closed
UNKNOWNhandling. - Compare merge-base/head analyzer findings under one pinned target-tip policy and classify introduced, fixed, unchanged, or unknown results deterministically.
- Preserve changed tests and governed policy/config impact; reject incomplete or candidate-self-authorized assurance.
- Produce module-side
range_candidate/range_previewevidence and a signed static consumer contract. The protected workflow-native verifier andpr_rangeenvelope remain core-owned downstream work. - Separate lifecycle, differential state, autofix availability, blocking policy, and authoritative schema 1.6 status.
- Publish through the canonical signed modules workflow only after all prescribed gates pass.
Implementation gates
- Revalidate the amended OpenSpec change against synchronized
origin/devand record readiness evidence. - Follow the exact named-tests → collected-selectors → accepted mapping →
IMPLEMENTATION_CHECKPOINT.json→ actual failing evidence → production implementation → passing evidence order. - Stay inside the closed allowlist in
tasks.md; do not simplify the accepted contract without approval. - Run supported-Python exact-core compatibility smoke, contracts, full tests, type/lint, range/full Code Review, signature, and registry-integrity gates.
- Stop after the verified signed module handoff; no core source implementation belongs to this issue.
Acceptance criteria
- Scope resolution never converts Git, snapshot, policy, runtime, analyzer, or coverage uncertainty into no-impact or passing evidence.
- Differential classifications and aggregate schema 1.6 status obey the accepted signed contracts.
- The exact core
v0.55.1tag/commit/tree matrix loads the candidate module and validates the complete consumer matrix on CPython 3.11–3.13. - The reviewed implementation PR merges to
dev, the canonical publish workflow produces the signed package/registry artifacts, and every identity required for core adoption is recorded.
Non-goals
- Implement the protected core PR/merge-queue consumer or verification-envelope emitter.
- Change Requirements R07/R08 semantics.
- Add new analyzer rules, LLM review, or unbounded dependency inference.
- Archive C14 before signed publication and downstream core-adoption gates permit it.
Metadata
Metadata
Assignees
Type
Projects
- Status
Activity
djm81 commentedon Aug 21, 2026
Source Tracking update (2026-08-21): implementation PR #418 is open against dev from
feature/code-review-14-delivery. Final candidate head is158e33cbd699b3413a2cfddfd9ff83d20cfa28a6/ tree41e51726b320f74bb11a5444bd3c4b64b81d779f; module metadata isspecfact-code-review 0.49.0, checksumsha256:bc205355b32388d968ef30919bd57f30d147f46472c9099e8c19fc8f8b5d5470, core compatibility===0.55.1. Local gates and the CPython 3.11-3.13 immutable-core matrix pass. Protected Linux capsule/cache/Bubblewrap and independent range-candidate verification remain the only delivery evidence pending CI; no core implementation is included.djm81 commentedon Aug 23, 2026
Final delivery update — 2026-08-23
Implementation PR #418 has reached its frozen signed delivery head.
bbb5a705fe65e9036d1cf07229a6faddae5b7d51/ tree37dda86458d3ed5b5797c81f14558722c220746cbdb16b69857fa4d4947d58a757f807c47627dc3e/ treede20668b7ec3ecb5ee832fdbee701da283c5b829specfact-code-review 0.49.46sha256:62175eace29561d22ae6c46751c4fe39b3f6e54890f4387ee571b05801c512ca===0.55.1, proven against tagv0.55.1, commitb1e517e60e669eaba15a18ecfa83ef5a9df65276, and tree47984be5434d7ae65ed6908bf525a32053290337The review/remediation loop is complete at this head: all
156GitHub review threads are resolved, no Critical/High/P1/P2 finding remains open, and no production or test code changed after the final substantive checkpoint. The two later commits contain only TDD evidence and the canonical manifest signature.Final verification passes: strict OpenSpec; format/type/Ruff/Pylint/YAML/registry/import/documentation gates;
28contracts; independent smart and complete suites at1563 passedeach; exact-core schema/handoff/candidate-identity smoke on CPython 3.11-3.13; module signatures; protected signed-registry capsule cache-miss/cache-hit and empty Bubblewrap proof; CodeQL and Socket security; Requirements Evidence and Docs Review. Final changed-line Code Review has0blockers.C14's delivery boundary remains the accepted one: it freezes and hardens truthful scope, immutable snapshot/differential evidence, sealed analyzer/runtime identities, schema 1.6 status truth, and the signed module-side range candidate. It does not implement C15 severity/blocking calibration (#417), paired core adoption (
nold-ai/specfact-cli#679), the protectedpr_rangeconsumer/envelope, or Requirements R07/R08 replay semantics.Two adjacent delivery corrections are retained with bounded scope: the legacy development-source Linux compatibility opt-in never applies to immutable/index/range assurance, and the signature hook now compares versions against the fetched target branch rather than a bot signature-only predecessor.
No further code changes are planned before approval and squash merge to
dev. After merge, the canonical publish workflow must produce the signed release/handoff; C14 must not be archived until the accepted downstream publication and adoption conditions are satisfied.8 remaining items
djm81 commentedon Aug 25, 2026
Promotion status update — 2026-08-25
The bounded remediation and publication sequence reached
devthrough #429 and #430:dev:3ef93ac4e4eda8762192faf95b83f67e074cbf9fspecfact-code-review 0.49.4978706d115bd0fb0b5156df44d4f9d0dedb96a8d3d434627f4f30d5aaf191865dsha256:4d707d9938b787d96d61ce88e0498da566ff263cf47fba869e3014a5744f1da1===0.55.1Promotion is nevertheless blocked by one newly surfaced, validated P2 thread on #420. Suppression identity currently uses path/family/token/ordinal without source-location correspondence, so relocating identical directive text within a file is classified as unchanged/UNKNOWN instead of the C14-required introduced blocker. A direct reproducer confirms that relocation and a legitimate correspondence-preserving line shift are currently indistinguishable.
This finding was not among #429s four authorized fixes. To preserve scope boundaries, it remains unresolved and requires a new narrow
dev-target remediation limited to relocation correspondence, with failing-before relocation coverage and legitimate line-shift/pure-rename controls, followed by a new immutable patch publication. Do not merge #420, close #416, or archive C14 before that sequence is complete.fix(code-review): detect relocated suppressions (#435)
fix(code-review): close final C14 review findings (#438)
djm81 commentedon Aug 26, 2026
Final bounded analyzer-completion remediation: #440. Fresh PR #420 review found two in-scope C14 defects (projected basedpyright positional override and Semgrep fatal/structured-error acceptance). The requested local review-agent pass confirmed both and found one additional instance of the same completion invariant: basedpyright fatal/configuration/argument exits could be accepted when JSON parsed. PR #440 fixes only those states; its own valid non-project
extra_argsregression was reproduced and corrected without admitting another finding family. Candidatespecfact-code-review0.49.58 is replacement-signed at head3d1cda53; exact-core and quality matrices pass on Python 3.11/3.12/3.13, CodeRabbit reports no corrected-head actionable comments, and all #440 threads are resolved. Remaining sequence: human approval/merge #440, publish 0.49.58 to dev, then resolve the two intentionally open #420 threads and refresh the promotion candidate.fix(code-review): enforce analyzer completion contracts (#440)
fix(code-review): reject Ruff operational exits (#442)
release: publish C14 Code Review module to main (#420)
[Planning] Preflight assurance runtime and integrations (#436)
fix(governance): refresh hierarchy cache freshness (#458)