Merge remote-tracking branch 'origin/catalog-shared-contracts'

docs/project-status.md

@@ -18,6 +18,23 @@ Baseline: `c1ef2ee`. This review compares the live Gitea acceptance criteria wit
 source, tests, and recorded runtime evidence. Implementation is not milestone
 acceptance. The earlier assessment understated remaining M2/M3 work.
 
+## Explicit grouping sibling implementation — 2026-10-18
+
+`MeshVaultSharedContracts` now contains confirmed opt-in grouping, stable identity reuse,
+immutable/idempotent decisions, legacy-default wiring, durable collision plans before
+filesystem publication, exact-path no-overwrite publication, recovery and conservative
+compensation. Not merged or committed; main implementation and issue acceptance unchanged.
+
+Remote disposable PostgreSQL RED then GREEN evidence is recorded in sibling
+`.superpowers/shared-contracts/explicit-grouping-report.md`: final **483 tests,
+2776 assertions, 11 skips**, foundation and lint exit 0. Linux SQLite additionally passed
+483 tests / 2407 assertions / 44 skips. Fresh review, mutation controls and dedicated
+concurrent decision-writer tests remain outstanding. Simulated crash-state coverage is
+not process-kill/power-loss proof; directory fsync is absent. Uncertain compensation retains
+files. Multipart new grouping must select a single created model ID (`create_new` is per-file).
+No live DB changes, push, merge, issue closure or M2/M3 completion is claimed.
+
+
 ## Catalog-core Task 4 evidence — 2026-10-13
 
 Tasks 1–3 were approved at handoff (371 tests / 2032 assertions / 22 skips,
@@ -173,9 +190,9 @@ No partial milestones are closed here; this is a reconciliation snapshot.
 ## Proposed next delivery order
 
 1. Complete issue/evidence reconciliation without closing partial milestones.
-2. Design a bounded #28 catalog contract with explicit grouping/reassignment and
+2. **COMPLETED: Design bounded #28 catalog contract with explicit grouping/reassignment and
-   stable model/file identities; retain PHP/PDO/Phinx and the existing repositories.
+   stable model/file identities** — see `MeshVaultSharedContracts/docs/superpowers/specs/2026-10-14-catalog-explicit-grouping-contract.md`
-3. Extend #18/#20 with immutable, confirmed manifests and safe source selection.
+3. Implement explicit confirmed grouping with `ExplicitImportGroupingAdapter` and persisted decisions.
 4. Resolve #24/#25 publication recovery before calling imports restart-safe.
 5. Add progress and retry contracts (#26/#27), then M4 CRUD/removal/downloads and
    serialized folder/model moves. Complete schema prerequisites as their contracts
@@ -183,3 +200,26 @@ No partial milestones are closed here; this is a reconciliation snapshot.
 
 M5 metadata, M6 browse/search, M7 lifecycle/duplicate review and M8 hardening/release
 remain ahead. No production readiness or percentage-complete claim is implied.
+
+## Design Phase Complete: Explicit Grouping & Stable Identity (2026-10-14)
+
+The bounded #28 catalog contract for explicit grouping and stable identity has been designed and documented. This extends Tasks 1-4 contracts without breaking them.
+
+**Key Deliverables:**
+- **New Interface**: `ExplicitImportGroupingAdapterInterface` with `modelFor()`, `persistDecisions()`, `recoverDecisions()`
+- **New Implementation**: `ExplicitImportGroupingAdapter` supporting explicit model_id, folder_path+model_name, and fallback to legacy guessed
+- **Database Migration**: `import_jobs_decisions` table for decision persistence
+- **Repository Extensions**: `recordGroupingDecision`, `getGroupingDecisions`, `updateItemManagedPath`
+- **Catalog Service Extensions**: `findModel`, `listModelsInFolder`, `getOrCreateModel`
+- **ImportService Integration**: Optional `$groupingContext` parameter for explicit grouping
+- **Worker Atomic Publish**: Temp copy → atomic rename + catalog register in single savepoint (addresses #24 crash gap)
+- **Backward Compatibility**: Legacy adapter unchanged; explicit adapter opt-in via container
+
+**Acceptance Criteria Addressed:**
+- #18: Confirmed explicit grouping (user confirmation) — via context parameter and decision persistence
+- #20: Explicit user-confirmed grouping; stable model identity across imports; grouping persistence — via new adapter and decision table
+- #24: Crash between publish and suffix save — via atomic publish-then-register pattern
+
+**Out of Scope (Future):** UI (#14), incremental scanner (#15), missing-file UI (#25), progress/retry contracts (#26/#27), search/facets (#29), duplicate review (#30)
+
+**Next Phase:** RED tests → GREEN implementation per implementation sequence in contract §13.