linkedin-automation-cli 1.0.0

package/docs/superpowers/plans/2026-03-13-linkedin-automation-resilience-migration.md

@@ -0,0 +1,425 @@
+# LinkedIn Automation Resilience Migration Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a resilient automation architecture that keeps the Go CLI thin while reducing breakage from LinkedIn UI changes for connect and message workflows.
+
+**Architecture:** Keep `internal/cmd` as orchestration-only, move interaction logic behind a provider interface, and add a detector/recovery layer with confidence scoring and fallback strategies. Preserve current PinchTab path first, then add optional AI fallback provider behind feature flags.
+
+**Tech Stack:** Go 1.21+, Cobra CLI, PinchTab HTTP client, optional sidecar HTTP provider (Stagehand/AgentQL-compatible contract).
+
+---
+
+## Chunk 1: Core Boundaries (Keep CLI Thin)
+
+### Task 1: Introduce automation contracts
+
+**Files:**
+- Create: `internal/automation/types.go`
+- Create: `internal/automation/provider.go`
+- Test: `internal/automation/types_test.go`
+
+- [ ] **Step 1: Write failing tests for core types and result contracts**
+
+```go
+func TestConnectOutcomeReasonValues(t *testing.T) {
+	if ConnectUnavailableReasonAlreadyConnected != "already_connected" {
+		t.Fatalf("unexpected value")
+	}
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `go test ./internal/automation -run TestConnectOutcomeReasonValues -v`
+Expected: FAIL with undefined type/constant.
+
+- [ ] **Step 3: Implement minimal contracts**
+
+Add:
+- `type ConnectState string`
+- `type ConnectOutcome struct { Success bool; Reason string; Confidence float64; DebugCandidates []string }`
+- `type MessageOutcome struct { Success bool; Reason string }`
+- `type Provider interface { Navigate(...); Connect(...); Message(...) }`
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `go test ./internal/automation -run TestConnectOutcomeReasonValues -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/automation/types.go internal/automation/provider.go internal/automation/types_test.go
+git commit -m "feat: add automation provider contracts and outcome types"
+```
+
+### Task 2: Add PinchTab provider adapter
+
+**Files:**
+- Create: `internal/linkedin/provider_pinchtab.go`
+- Modify: `internal/linkedin/navigator.go`
+- Test: `internal/linkedin/provider_pinchtab_test.go`
+
+- [ ] **Step 1: Write failing provider adapter tests**
+
+```go
+func TestPinchTabProviderConnectMapsUnavailableReason(t *testing.T) {
+	// arrange mock snapshot -> follow_only state
+	// act provider.Connect(...)
+	// assert outcome.Reason == "follow_only"
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `go test ./internal/linkedin -run TestPinchTabProviderConnectMapsUnavailableReason -v`
+Expected: FAIL with missing provider implementation.
+
+- [ ] **Step 3: Implement provider adapter**
+
+Map current navigator errors to `automation.ConnectOutcome` without changing rate-limit behavior.
+
+- [ ] **Step 4: Run tests to verify pass**
+
+Run: `go test ./internal/linkedin -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/linkedin/provider_pinchtab.go internal/linkedin/navigator.go internal/linkedin/provider_pinchtab_test.go
+git commit -m "feat: add pinchtab automation provider adapter"
+```
+
+### Task 3: Refactor command actions to use automation service
+
+**Files:**
+- Create: `internal/automation/service.go`
+- Modify: `internal/cmd/actions.go`
+- Test: `internal/automation/service_test.go`
+
+- [ ] **Step 1: Write failing service behavior tests**
+
+```go
+func TestServiceConnectPreservesLimiterOrdering(t *testing.T) {
+	// assert CheckConnection happens before Provider.Connect
+	// assert RecordConnection only on success
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `go test ./internal/automation -run TestServiceConnectPreservesLimiterOrdering -v`
+Expected: FAIL with missing service implementation.
+
+- [ ] **Step 3: Implement minimal service + wire actions.go**
+
+Keep `internal/cmd` thin and delegate to `automation.Service`.
+
+- [ ] **Step 4: Run tests to verify pass**
+
+Run: `go test ./internal/automation ./internal/cmd -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/automation/service.go internal/automation/service_test.go internal/cmd/actions.go
+git commit -m "refactor: route cmd actions through automation service"
+```
+
+---
+
+## Chunk 2: Resilience Engine (Detection + Recovery)
+
+### Task 4: Add confidence-based detector strategies
+
+**Files:**
+- Create: `internal/linkedin/detector.go`
+- Create: `internal/linkedin/strategy.go`
+- Test: `internal/linkedin/detector_test.go`
+
+- [ ] **Step 1: Write failing tests for strategy ordering and confidence**
+
+```go
+func TestDetectorPrefersHighConfidenceRoleMatch(t *testing.T) {
+	// ensure aria/role strategy beats weak text-only match
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `go test ./internal/linkedin -run TestDetectorPrefersHighConfidenceRoleMatch -v`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement detector with strategy chain**
+
+Strategies:
+- role+name semantic match
+- localized keyword match
+- more-actions fallback discovery
+- low-confidence rejection
+
+- [ ] **Step 4: Run tests to verify pass**
+
+Run: `go test ./internal/linkedin -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/linkedin/detector.go internal/linkedin/strategy.go internal/linkedin/detector_test.go
+git commit -m "feat: add confidence-based connect detector strategies"
+```
+
+### Task 5: Add snapshot fixture regression tests
+
+**Files:**
+- Create: `internal/linkedin/fixtures/*.json`
+- Create: `internal/linkedin/fixture_loader_test.go`
+- Modify: `internal/linkedin/navigator_test.go`
+
+- [ ] **Step 1: Write failing fixture tests**
+
+```go
+func TestDetectorAgainstRealisticFixtures(t *testing.T) {
+	// table: connectable, pending, connected, follow_only, hidden-in-more
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `go test ./internal/linkedin -run TestDetectorAgainstRealisticFixtures -v`
+Expected: FAIL until fixtures + loader exist.
+
+- [ ] **Step 3: Implement fixture loader and test matrix**
+
+Add at least five fixtures to cover common states.
+
+- [ ] **Step 4: Run tests to verify pass**
+
+Run: `go test ./internal/linkedin -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/linkedin/fixtures internal/linkedin/fixture_loader_test.go internal/linkedin/navigator_test.go
+git commit -m "test: add snapshot fixture regression suite for linkedin states"
+```
+
+### Task 6: Add observability hooks for failure triage
+
+**Files:**
+- Create: `internal/automation/telemetry.go`
+- Modify: `internal/automation/service.go`
+- Test: `internal/automation/telemetry_test.go`
+
+- [ ] **Step 1: Write failing telemetry tests**
+
+```go
+func TestServiceRecordsFailureContext(t *testing.T) {
+	// assert reason, confidence, and candidate nodes are logged
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `go test ./internal/automation -run TestServiceRecordsFailureContext -v`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement minimal structured telemetry**
+
+Record:
+- action (`connect`/`message`)
+- outcome reason
+- confidence
+- candidate nodes
+- profile + url
+
+- [ ] **Step 4: Run tests to verify pass**
+
+Run: `go test ./internal/automation -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/automation/telemetry.go internal/automation/telemetry_test.go internal/automation/service.go
+git commit -m "feat: add structured telemetry for automation failures"
+```
+
+---
+
+## Chunk 3: Optional AI Fallback Provider (Feature-Flagged)
+
+### Task 7: Add fallback provider contract and policy
+
+**Files:**
+- Create: `internal/automation/fallback.go`
+- Create: `internal/automation/policy.go`
+- Test: `internal/automation/policy_test.go`
+
+- [ ] **Step 1: Write failing policy tests**
+
+```go
+func TestFallbackPolicyTriggersOnlyLowConfidence(t *testing.T) {
+	// low confidence -> fallback true
+	// high confidence explicit unavailable -> fallback false
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `go test ./internal/automation -run TestFallbackPolicyTriggersOnlyLowConfidence -v`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement policy with conservative defaults**
+
+Defaults:
+- fallback disabled
+- only enabled by explicit config/env flag
+
+- [ ] **Step 4: Run tests to verify pass**
+
+Run: `go test ./internal/automation -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/automation/fallback.go internal/automation/policy.go internal/automation/policy_test.go
+git commit -m "feat: add conservative fallback policy contracts"
+```
+
+### Task 8: Implement generic HTTP fallback provider adapter
+
+**Files:**
+- Create: `internal/automation/http_provider.go`
+- Create: `internal/automation/http_types.go`
+- Test: `internal/automation/http_provider_test.go`
+
+- [ ] **Step 1: Write failing adapter tests**
+
+```go
+func TestHTTPProviderMapsConnectIntentAndResponse(t *testing.T) {
+	// mock endpoint; assert request/response mapping
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `go test ./internal/automation -run TestHTTPProviderMapsConnectIntentAndResponse -v`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement adapter (vendor-agnostic)**
+
+No vendor lock-in: define neutral request/response schema.
+
+- [ ] **Step 4: Run tests to verify pass**
+
+Run: `go test ./internal/automation -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/automation/http_provider.go internal/automation/http_types.go internal/automation/http_provider_test.go
+git commit -m "feat: add vendor-agnostic http fallback provider adapter"
+```
+
+---
+
+## Chunk 4: Rollout, Verification, and Safety
+
+### Task 9: Keep dry-run parity and command behavior stable
+
+**Files:**
+- Modify: `internal/cmd/connect.go`
+- Modify: `internal/cmd/sequence.go`
+- Modify: `internal/cmd/people.go`
+- Test: `internal/cmd/actions_test.go`
+
+- [ ] **Step 1: Write failing dry-run parity tests**
+
+```go
+func TestDryRunStillSkipsExternalActions(t *testing.T) {
+	// no provider calls when dry-run=true
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `go test ./internal/cmd -run TestDryRunStillSkipsExternalActions -v`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement minimal parity fixes**
+
+Ensure no behavior drift in CLI UX.
+
+- [ ] **Step 4: Run tests to verify pass**
+
+Run: `go test ./internal/cmd -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/cmd/connect.go internal/cmd/sequence.go internal/cmd/people.go internal/cmd/actions_test.go
+git commit -m "test: preserve dry-run behavior across automation refactor"
+```
+
+### Task 10: Final verification gate
+
+**Files:**
+- Modify: `README.md` (optional short section for provider/fallback config)
+
+- [ ] **Step 1: Run focused package tests**
+
+Run: `go test ./internal/linkedin ./internal/automation ./internal/cmd -v`
+Expected: PASS.
+
+- [ ] **Step 2: Run full test suite**
+
+Run: `go test ./...`
+Expected: PASS.
+
+- [ ] **Step 3: Build CLI**
+
+Run: `go build ./cmd/linkedin`
+Expected: exit 0.
+
+- [ ] **Step 4: Validate dry-runs manually**
+
+Run:
+- `go run ./cmd/linkedin --profile thaddeus connect --dry-run --url "https://www.linkedin.com/in/example" --message "Hi"`
+- `go run ./cmd/linkedin --profile thaddeus sequence --dry-run --url "https://www.linkedin.com/in/example" --step connect --message "Hi"`
+- `go run ./cmd/linkedin --profile thaddeus people --dry-run --company-url "https://www.linkedin.com/company/example" --mode both --limit 3`
+
+Expected: no action execution, only dry-run output.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: describe resilient automation architecture and fallback flags"
+```
+
+---
+
+## Decision Criteria During Execution
+
+- Keep `internal/cmd` thin; no detection heuristics inside command handlers.
+- Preserve rate limiter ordering and counters exactly.
+- Feature-flag AI fallback; default disabled.
+- Prefer deterministic strategies first, AI fallback only on low confidence.
+- No provider-specific business logic in CLI layer.
+
+## Expected Deliverables
+
+1. Stable automation service boundary (`internal/automation/*`).
+2. PinchTab provider compatible with existing behavior.
+3. Confidence-based detection and fixture regression tests.
+4. Optional vendor-agnostic HTTP fallback provider.
+5. Verified test/build/dry-run parity.