fix(langfuse): harden v4 migration workflow

[hassiebp]

Summary

• make the v4 migration skill executable with full project access or honest code-only/project-only fallbacks
• cover SDK, raw ingestion, deprecated APIs, evaluator contracts, exports, canary validation, and a seven-area readiness report
• treat deprecated trace I/O as a last-resort escape hatch that requires explicit confirmation; never add it merely because a legacy rule exists or project access is unavailable
• bump the Claude, Codex, and Cursor plugin manifests to 1.4.3

Why

Cross-harness testing found that agents could infer project state without access, preserve deprecated trace I/O too readily, under-test semantic behavior, and omit a complete handoff. The revised workflow makes those failure modes explicit acceptance gates.

Linear: LFE-10897

Validation

• custom frontmatter, required_access, manifest lockstep, line-count, JSON, and H1 checks
• git diff --check
• live verification against the current Langfuse v4, compatibility, custom ingestion, evaluator, and export docs
• clean disposable v3 fixture forward test using Langfuse Python 4.14.1: 3 passed
• fixture scan confirmed no legacy ingestion/read endpoints, trace update calls, or trace-I/O compatibility methods remained
• forward test returned all seven readiness rows and kept project-dependent evaluator/export/canary checks blocked without credentials

Note: the generic quick_validate.py could not run because its Python environment lacks PyYAML; equivalent structural checks were run directly with Ruby YAML and Python JSON parsers.

[github-actions]

@claude review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a8e76e2ce6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

No bugs were found, but this PR is a substantial rewrite of the v4 migration workflow's policy (execution-mode fallback, new required_access grants for CODEBASE/LANGFUSE_PROJECT_SCRIPT, and the new deprecated-trace-I/O escape-hatch gating), so I think it's worth a human look before merging.

What was reviewed: the restructured reference against the routing entry in SKILL.md (still one line, matches), required_access frontmatter tokens (valid), and the three plugin manifests for version lockstep (all bumped to 1.4.3 together). I could not independently re-fetch the Langfuse docs pages referenced/changed in this diff to confirm content accuracy, so I'm relying on the PR's stated live-verification for that part.

Extended reasoning...

Overview

The PR rewrites skills/langfuse/references/v4-project-migration.md end-to-end (134 -> 73 lines), changing it from a single-mode (project-interface-only) workflow to one with explicit code-only / project-only / full-access execution modes, a new escape-hatch gate for deprecated trace input/output, and a seven-area readiness report. It also bumps all three plugin manifests (Claude, Codex, Cursor) from 1.4.3 in lockstep, and swaps several doc links (e.g. deprecated-API migration guide now points at /faq/all/deprecated-api-migration, ingestion migration now points at the OpenTelemetry custom-ingestion guide).

Security risks

None directly — this is documentation/skill-instruction content, not executable application code. The main risk surface is behavioral: the reference now grants the skill CODEBASE and LANGFUSE_PROJECT_SCRIPT required_access, meaning an agent following it may edit source and run SDK code against a live Langfuse project. The new escape-hatch section is a safety-relevant policy (governs when deprecated trace-I/O compatibility calls are added), and getting its wording wrong could cause agents to either strand legacy evaluators or retain deprecated calls too readily — exactly the failure mode this PR claims to fix.

Level of scrutiny

This warrants a genuine content read rather than a mechanical diff check. It's not a simple config/typo change — it restructures the workflow's control flow (execution modes, gating conditions for the escape hatch, new required_access scopes) in ways that reflect real design judgment about agent behavior. The bug-hunting system found no bugs and its finder/verifier pass already investigated and ruled out several plausible concerns (a sibling-file contradiction in trace-evaluator-upgrade.md's 'keep deprecated trace-I/O while an active legacy rule requires it' language, whether the evaluator-migration section duplicates trace-evaluator-upgrade.md instead of delegating, the changed deprecated-API link, and the patch- vs minor-version-bump question). I independently checked the SKILL.md routing entry (still exactly one line, matches frontmatter description) and the required_access tokens (valid, drawn from the allowed list) and found no issues there.

Other factors

I was not able to use WebFetch in this environment to independently re-verify the several docs links that changed or were added in this diff, so I'm relying on the PR description's claim of live doc verification for that specific check. Given the meaningful behavioral/policy scope of the rewrite and that one of my checks (live docs verification) couldn't be completed independently, a human pass is warranted even though no concrete bugs surfaced.