# Primary Profile Relationship Labels Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Render direct localized family relationships for primary profiles, inverse relationships for non-primary profiles, and consume the real catalog response envelope.

**Architecture:** Keep response-shape adaptation in `PersonProfileRepository`, where the upstream HTTP contract enters the application. Keep perspective selection in `FamilyRelationshipLabelResolver`, using only the strict boolean value of `is_primary`.

**Tech Stack:** PHP 8, Laravel, Blade, PHPUnit feature tests.

---

### Task 1: Reproduce the primary-profile regression

**Files:**
- Modify: `tests/Feature/PublicProfileCanonicalLabelsTest.php`
- Create: `tests/Feature/PublicProfileRelationshipLabelsTest.php`

- [ ] **Step 1: Make the fake catalog match the API envelope**

Return the catalog as `['data' => [...]]`, matching `/catalogs/family-relationships` in `api_mycode`.

- [ ] **Step 2: Add a primary contact fixture and assertions**

Use this person payload:

```php
[
    'name' => 'Canonical Person',
    'identifier' => 'CANONPERSON',
    'is_primary' => true,
    'sex' => 'FEMALE',
    'care_type' => 'CHILD',
    'contact_relationship' => 'SON_OR_DAUGHTER',
    'phone' => '+56 900000000',
    'secondary_phone' => '+56 911111111',
    'secondary_contact_relationship' => 'FATHER',
]
```

In Spanish assert `Padre` is visible and `FATHER` is not. In English assert `Father` is visible and `FATHER` is not.

- [ ] **Step 3: Run the focused test and verify RED**

Run:

```bash
php artisan test tests/Feature/PublicProfileCanonicalLabelsTest.php
```

Expected: FAIL because a primary profile currently inverts `FATHER` to a child label.

### Task 2: Adapt the catalog response at the infrastructure boundary

**Files:**
- Modify: `app/Infrastructure/Http/Profile/PersonProfileRepository.php`
- Test: `tests/Feature/PublicProfileCanonicalLabelsTest.php`

- [ ] **Step 1: Add a focused catalog extractor**

Add:

```php
private function relationshipCatalog(array $response): array
{
    if (($response['status'] ?? null) !== 'ok') {
        return [];
    }

    $payload = $response['data'] ?? [];

    if (! is_array($payload)) {
        return [];
    }

    $catalog = $payload['data'] ?? $payload;

    return is_array($catalog) ? $catalog : [];
}
```

Use it for `familyRelationships` instead of casting `$relationships['data']` directly.

- [ ] **Step 2: Keep the focused test RED for perspective**

Run:

```bash
php artisan test tests/Feature/PublicProfileCanonicalLabelsTest.php
```

Expected: FAIL on `Padre`/`Father`, proving the envelope is fixed while perspective still needs correction.

### Task 3: Apply the `is_primary` perspective rule

**Files:**
- Modify: `app/Application/Profile/FamilyRelationshipLabelResolver.php`
- Test: `tests/Feature/PublicProfileCanonicalLabelsTest.php`

- [ ] **Step 1: Select one resolver from the strict primary flag**

At the start of `apply`, define:

```php
$resolve = ($person['is_primary'] ?? false) === true
    ? fn ($value): ?string => $this->resolveDirect($value, $catalog, $locale)
    : fn ($value): ?string => $this->resolve($value, $catalog, $locale);
```

Use `$resolve` for both `contact_relationship` and `secondary_contact_relationship`. Remove the previous secondary-only `is_primary` conditional.

- [ ] **Step 2: Run the focused test and verify GREEN**

Run:

```bash
php artisan test tests/Feature/PublicProfileCanonicalLabelsTest.php
```

Expected: all tests in the file pass; canonical relationship keys are absent.

### Task 4: Verify architecture and regressions

**Files:**
- Verify all modified production and test files.

- [ ] **Step 1: Check formatting and changed-file scope**

Run:

```bash
git diff --check
git status --short
```

Expected: no whitespace errors; only the intended source, test, and plan changes are attributable to this task, while pre-existing image and cache changes remain untouched.

- [ ] **Step 2: Run the strict architecture audit**

Run:

```bash
php artisan architecture:audit --strict
```

Expected: PASS.

- [ ] **Step 3: Run the complete suite**

Run:

```bash
php artisan test
```

Expected: all tests pass with zero failures.