feature: Refinements become versioned specs refining another spec #13

Merged

Gilles merged 2 commits from feature/refinement-specs into master 2026-10-25 14:51:09 +00:00

Conversation 2 Commits 2 Files changed 14 +1144 -611

Gilles commented 2026-10-25 12:22:44 +00:00

Owner

• Copy link
• Copy Markdown

Closes #12

Backend half of the refinement-as-spec refactor. Do not merge before the matching frontend PR — /api/refinements/ disappears and the spec/version payloads change.

Model

• Refinement removed. A refinement is a Spec at a direct child place with refines → the refined spec (required by the API outside the root place; the refined spec's current version must be a draft, as before).
• SpecVersion.refines_versions (M2M): versions of spec.refines this version covers. Monotonic (cover() / check_coverage()): never older than what the previous version covers; equal is allowed.
• SpecVersion.is_absence: documented absence, content = justification (required to validate). Vacuously implemented, needs no refinements below.
• SpecVersion.refinement_versions() / missing_refinement_places(): for each spec refining this one, its latest version covering it; completeness = ≥ 1 per direct child place (1..n allowed).
• SpecCodeAlias: former -R- codes, resolved by the coverage upload after spec codes. Project.next_refinement_sequence removed.

Reopen cascade

• Spec.reopen() cascades to refinement specs whose current version covers the reopened version → new drafts with pending_decision, covering nothing yet. A refinement already in draft just covers the new version.
• Reopening a refinement directly keeps covering the parent version its previous version covered.
• POST /api/spec-versions/{id}/decide/ {decision: keep|new_version|absence, reason} — top down (parent decided first). keep / absence revert the still-pending drafts below.
• Pending drafts can't be edited or validated; project validation lists them.

API

• SpecSerializer: refines, code_aliases, write-only is_absence + content on creation; place/refines fixed after creation. ?refines= filter.
• SpecVersionSerializer: is_absence (writable on drafts), refines_versions, pending_decision, refinement_versions, missing_refinement_places.
• Attachments and automatic tests only target spec versions / specs; exists_in_refinements removed from stored files.

Data migration (0007 → 0008 → 0009)

• Target refinements: target spec refines the parent spec, target version covers the parent version, R-* → alias, attachments moved to the target version (same file deduplicated, name clash suffixed with the R code), automatic tests moved to the target spec (deduplicated, most recent run kept).
• Absences grouped by (parent spec, child place) → one spec "Absence de raffinement : ", one version per distinct reason, status/validation copied from the parent version.
• Stops (rolled back) if a spec is the target of two different parent specs, listing them — needs a read of prod data before deploying.
• Covered by apps/specs/test_migrations.py.

Tests

pytest: 117 passed. pylint 10.00, autopep8 clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_014BSmBtGWeFBD9z4mYm9SjA

Closes #12 Backend half of the refinement-as-spec refactor. **Do not merge before the matching frontend PR** — `/api/refinements/` disappears and the spec/version payloads change. ## Model - `Refinement` removed. A refinement is a `Spec` at a direct child place with `refines` → the refined spec (required by the API outside the root place; the refined spec's current version must be a draft, as before). - `SpecVersion.refines_versions` (M2M): versions of `spec.refines` this version covers. Monotonic (`cover()` / `check_coverage()`): never older than what the previous version covers; equal is allowed. - `SpecVersion.is_absence`: documented absence, `content` = justification (required to validate). Vacuously implemented, needs no refinements below. - `SpecVersion.refinement_versions()` / `missing_refinement_places()`: for each spec refining this one, its latest version covering it; completeness = ≥ 1 per direct child place (1..n allowed). - `SpecCodeAlias`: former `-R-` codes, resolved by the coverage upload after spec codes. `Project.next_refinement_sequence` removed. ## Reopen cascade - `Spec.reopen()` cascades to refinement specs whose current version covers the reopened version → new drafts with `pending_decision`, covering nothing yet. A refinement already in draft just covers the new version. - Reopening a refinement directly keeps covering the parent version its previous version covered. - `POST /api/spec-versions/{id}/decide/` `{decision: keep|new_version|absence, reason}` — top down (parent decided first). `keep` / `absence` revert the still-pending drafts below. - Pending drafts can't be edited or validated; project validation lists them. ## API - `SpecSerializer`: `refines`, `code_aliases`, write-only `is_absence` + `content` on creation; `place`/`refines` fixed after creation. `?refines=` filter. - `SpecVersionSerializer`: `is_absence` (writable on drafts), `refines_versions`, `pending_decision`, `refinement_versions`, `missing_refinement_places`. - Attachments and automatic tests only target spec versions / specs; `exists_in_refinements` removed from stored files. ## Data migration (0007 → 0008 → 0009) - Target refinements: target spec `refines` the parent spec, target version covers the parent version, `R-*` → alias, attachments moved to the target version (same file deduplicated, name clash suffixed with the R code), automatic tests moved to the target spec (deduplicated, most recent run kept). - Absences grouped by (parent spec, child place) → one spec "Absence de raffinement : <parent>", one version per distinct reason, status/validation copied from the parent version. - **Stops** (rolled back) if a spec is the target of two different parent specs, listing them — needs a read of prod data before deploying. - Covered by `apps/specs/test_migrations.py`. ## Tests `pytest`: 117 passed. pylint 10.00, autopep8 clean. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_014BSmBtGWeFBD9z4mYm9SjA

Gilles added 1 commit 2026-10-25 12:22:45 +00:00

Refinements become versioned specs refining another spec ... 58bd199083

Replace the Refinement link model: a refinement is now a regular Spec at
a direct child place, with `Spec.refines` pointing at the refined spec.

- SpecVersion.refines_versions (M2M, monotonic): one refinement version
  can cover several versions of the refined spec.
- SpecVersion.is_absence: a documented absence is a refinement version,
  its content being the justification.
- Reopen cascades down the refinement tree as drafts with a pending
  decision (keep / new version / absence), settled top down through
  POST /spec-versions/{id}/decide/; a project version cannot be
  validated while a decision is pending.
- Former "-R-" codes survive as SpecCodeAlias, still resolved by the
  coverage upload; no new refinement code is issued.
- Data migration 0008 moves every Refinement row (targets, grouped
  absences, attachments, automatic tests) and stops on a target refined
  by two parent specs.
- /api/refinements/ and attachment/test refinement targets are removed.

Refs #12

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014BSmBtGWeFBD9z4mYm9SjA

Gilles commented 2026-10-25 12:24:51 +00:00

Author

Owner

• Copy link
• Copy Markdown

📊 Rapports Argus pour cette PR

<!-- argus-link-bot:thierryade/backend --> 📊 [Rapports Argus pour cette PR](https://reports.stationmyr.net/thierryade/backend/pr/13)

Gilles referenced this pull request from thierryade/frontend 2026-10-25 12:29:58 +00:00

feature: Refinements as versioned specs (UI for backend#12) #8

Gilles added 1 commit 2026-10-25 14:29:24 +00:00

Copy a spec refined from two parent specs instead of stopping ... 332e60a6bd

Migration 0008 used to abort on a target spec refined from two different
parent specs (prod has one: FLO-3 <- FLO-2, FLO-18). The target now keeps
the parent of its oldest refinement; every other parent gets a copy of
it (versions, manual tests, attachments) under a new code, which its
refinements target and whose aliases they become.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014BSmBtGWeFBD9z4mYm9SjA

Gilles commented 2026-10-25 14:29:35 +00:00

Author

Owner

• Copy link
• Copy Markdown

Migration 0008 no longer stops on a spec refined from two parent specs (prod pre-check found one: FLO-3 <- FLO-2, FLO-18). The target keeps the parent of its oldest refinement; each other parent gets a copy (new code, title suffixed with the parent code, versions + manual tests + attachments copied, automatic tests left on the original). The copy has no refinements below it yet, so it will show missing child places until handled.

🤖 Generated with Claude Code

https://claude.ai/code/session_014BSmBtGWeFBD9z4mYm9SjA

Migration 0008 no longer stops on a spec refined from two parent specs (prod pre-check found one: FLO-3 <- FLO-2, FLO-18). The target keeps the parent of its oldest refinement; each other parent gets a copy (new code, title suffixed with the parent code, versions + manual tests + attachments copied, automatic tests left on the original). The copy has no refinements below it yet, so it will show missing child places until handled. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_014BSmBtGWeFBD9z4mYm9SjA

Gilles changed title from WIP: Refinements become versioned specs refining another spec to feature: Refinements become versioned specs refining another spec 2026-10-25 14:49:17 +00:00

Gilles merged commit 3833deca3f into master 2026-10-25 14:51:09 +00:00

Gilles deleted branch feature/refinement-specs 2026-10-25 14:51:09 +00:00

Gilles referenced this pull request from a commit 2026-10-25 14:51:11 +00:00

feature: Refinements become versioned specs refining another spec (#13)

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

breaking

Breaking change: listed first in the release notes

  

bug

Bug fix (release notes: Bug fixes)

  

ci

CI and maintenance (release notes: CI & maintenance)

  

dependencies

Dependency update (release notes: Dependencies, folded)

  

documentation

Documentation (release notes: Documentation)

  

feature

New feature (release notes: Features)

  

security

Security fix (release notes: Security)

  

skip-changelog

Left out of the release notes

No labels

breaking

bug

ci

dependencies

documentation

feature

security

skip-changelog

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

thierryade/backend!13

No description provided.