OCL Mapper | Require explicit target_repo.version in project config form (no blank, no silent HEAD default)

[paynejd]

Context

Companion follow-up to OpenConceptLab/ocl_issues#2520 (target-repo version alignment across algorithm paths).

The mapping project's target repo version is semantically load-bearing — it determines concept identity for dedup across all algorithm paths, and it's the version \$resolveReference must be invoked against when loading concept details. The version dropdown on the project config screen already exposes this as a first-class field (Repository → Version, e.g. "2.81", "2.71.21AA", "HEAD").

But the current code paths accept missing/blank version in several ways:

• MapProject.jsx:1060 defaults missing version to the string 'HEAD'.
• MapProject.jsx:693 defaults missing version to undefined.
• These two defaults diverge, so the same project can end up with version: \"HEAD\" vs version: undefined depending on which code path populated projectContext.target_repo.

Why this matters

1. Dedup correctness. PR3-X.2 | Bridge cascade target inherits target_repo version 'HEAD', splitting concept_key from direct-path matches #2520 fixed dedup by anchoring concept identity to the project pin. That fix is on solid ground only when the pin is reliably present.
2. Resolution correctness. `$resolveReference` resolves to the latest released version (or HEAD if none) when version is unspecified — NOT to whatever the user intended. Missing-version projects therefore quietly load concept details from a version the user didn't choose.
3. Auditability. "What did the user actually pick?" should be a clear, single value on the project, not a side-effect of code-path order.
4. Author/user role separation. HEAD is for authors editing in-progress data; mapping users should rarely target HEAD. Making HEAD an explicit choice (rather than a fallback default) discourages accidental HEAD-pinning. In the future, repo admins may control whether HEAD is even offered in the dropdown for mapping use.

Scope

• Form-level validation on the project create/edit screen: "Version" must be selected before save is allowed. The field is already starred (required) visually in the UI ([screenshot in PR3-X.2 | Bridge cascade target inherits target_repo version 'HEAD', splitting concept_key from direct-path matches #2520 thread]); make it enforced in code.
• Remove the || 'HEAD' default at MapProject.jsx:1060.
• Remove the || undefined default at MapProject.jsx:693.
• Migration consideration: existing saved projects with missing version need a one-time backfill OR a project-load gate that prompts the user to pick a version before continuing.

Acceptance

• Cannot save a project without selecting a target_repo version.
• Loading a legacy project with no version triggers a blocking prompt to select one.
• projectContext.target_repo.version is always a non-empty string in any code path that reads it.
• The two defaults at MapProject.jsx:1060 and :693 are removed.

Out of scope

• Restricting which versions are available in the dropdown (HEAD allowed-by-default vs. admin-controlled) — that's a separate repo-admin policy ticket.
• Multi-version mapping support.

[ocl-automation]

Automated Triage — 2026-05-14

Dimension	Score
Complexity	3
Scope	2
Clarity	4
Dependency	2
Risk	3

Decision: decision/ai-ready
Type: type/feature
Signals: signal/small-scope, signal/well-specified

Moderate complexity involving form validation and UI changes across a few files. Well-defined requirements with clear acceptance criteria. Moderate risk because incorrect version handling could affect concept identity and deduplication logic.

---

Generated by ticket-triage pipeline v3. Model: anthropic/claude-sonnet-4 (openrouter).