T-V3FZ-deprecate-namespaceconflict-legacy-ctor

Status: closed/obsoleted · Impact: low · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to open/ready before picking up.

Goal

The NamespaceConflict exception in plugin/lib/lease/exceptions.ts currently supports two constructor shapes — the original NamespaceConflict(namespace: str) and the richer NamespaceConflict(ref, sha, remediation) form added by T-K3RR-add-lease-namespace-conflict-guard. The dual shape is held together by runtime shape-detection in __init__. Once external callers of the legacy positional form are confirmed gone, remove the shape-detection branch so the class has a single, type-stable constructor. The post-mortem of T-K3RR-add-lease-namespace-conflict-guard explicitly flagged this as a slice-2 cleanup pass.

Today

Location	Role today
plugin/lib/lease/exceptions.ts	NamespaceConflict.__init__ carries a runtime shape-detection branch: single positional arg is treated as the legacy namespace: str; (ref, sha, remediation) triple is the current form.
plugin/lib/lease/ (callers)	All known callers within plugin/lib/lease/ and plugin/scripts/lease_cli/ use the (ref, sha, remediation) form after the namespace-conflict guard landed. The legacy form’s last in-tree caller (if any) needs a one-shot audit.
plugin/lib/lease/tests/	Tests cover the new ctor form; no test asserts the legacy form keeps working — it survives by accident of the shape-detection branch.

Proposed

NamespaceConflict.__init__ accepts only the (ref, sha, remediation) form. Any caller still passing a single positional argument fails at call time with a clear TypeError (or a deprecation-then-removal window if any cross-repo caller is identified).

Approach

1. Grep the in-tree codebase for NamespaceConflict( invocations. Confirm every site uses the (ref, sha, remediation) form.
2. If any legacy-form caller is found, fix it in this task (or split into a precursor).
3. Remove the runtime shape-detection branch from NamespaceConflict’s constructor. Tighten the type signature.
4. Add a regression test that the legacy single-positional form now raises TypeError so the deprecation is observable.
5. Refresh the exception’s docstring to drop the “legacy form accepted for back-compat” note.

Files to touch

Location	Kind	Change
plugin/lib/lease/exceptions.ts	modify	Drop the runtime shape-detection branch from NamespaceConflict’s constructor; tighten signature and docstring.
plugin/lib/lease/tests/exceptions.test.ts	modify	Add a regression test asserting NamespaceConflict("just-a-namespace") now raises a TypeError-equivalent. Co-locate with the lease library’s existing exception tests.
plugin/lib/lease/tests/guard.test.ts	modify	If any guard test happens to construct NamespaceConflict via the legacy form (audit step 1), update to the (ref, sha, remediation) form.

Acceptance criteria

• AC-1: grep -rn 'NamespaceConflict(' plugin/ shows zero single-positional invocations after this task lands.
• AC-2: NamespaceConflict("just-a-namespace") raises TypeError (regression test asserts this).
• AC-3: NamespaceConflict(ref="refs/sdlc", sha="<sha>", remediation="...") continues to construct cleanly and the .ref / .sha / .remediation attributes are populated as before.
• AC-4: The test_check_raises_on_literal_refs_sdlc regression test (in the namespace-conflict-guard suite) still passes unchanged.

Out of scope

• A formal multi-version deprecation cycle. The lease protocol is pre-1.0 and all callers are in-tree as of this writing; a hard removal is appropriate. If external callers are discovered during the AC-1 grep, split into a precursor task instead of stretching this one.

Dependencies

• T-K3RR-add-lease-namespace-conflict-guard — introduced the shape-detection branch this task removes.

Discovery context

Spawned by /sdlc:task-work post-mortem of T-K3RR-add-lease-namespace-conflict-guard on 2026-05-24.

Dedup search (spawn-from-post-mortem)

Bullet: exceptions.NamespaceConflict carried a compat burden. Constructor was (namespace: str) before; this task needs (ref, sha, remediation). Extended with a runtime-shape detection so legacy single-positional callers still work. Worth deprecating the legacy form once external callers are confirmed gone — flagged for a slice-2 cleanup pass. Keywords searched: namespaceconflict, single-positional, runtime-shape, constructor, remediation, deprecating, exceptions, namespace Excluded: 2026-05-23-add-lease-namespace-conflict-guard Top candidates (score / status / headline):

• 16 / in-progress / 2026-05-23-add-lease-protocol-library-and-schemas — Add lease-protocol library and payload schemas
• 6 / closed/done / 2026-05-20-task-branches-use-task-prefix — Use task/ prefix for task-work branches (was feat/)
• 5 / planning/draft / 2026-05-24-lease-fixture-exposes-fetch-helper — Lease local-bare-repo fixture exposes a fetch-all-sdlc-refs helper
• 3 / planning/draft / 2026-05-23-lease-primitives-validate-git-actually-acted — Every lease primitive validates git actually performed the operation
• 2 / in-progress / 2026-05-23-add-sdlc-lease-cli-commands — Add sdlc lease … CLI commands Decision: LINKED-EXISTING 2026-05-23-add-lease-protocol-library-and-schemas Rationale: Overridden to SPAWNED. The lease-library foundation task scoped the initial NamespaceConflict exception with a single-positional namespace: str ctor; this cleanup is explicitly slice-2 work (per the originating post-mortem) that lands after the namespace-conflict guard’s compat shim has been in-tree long enough to confirm no external callers depend on the legacy shape. Folding it into the foundation task would conflate the new-feature work with a future deprecation, and the foundation task is already in-progress on a separate branch. Sibling task is cleaner.

---

← Back to Tasks