Build the Flutter-first Pickforge integration alpha

[ElbertePlinio]

Goal

Turn PickLab into the Flutter-first foundation of the new Pickforge: one local command that detects a mobile project, safely wires the user's existing coding agent to upstream tools, teaches a proven workflow, and produces reviewable evidence.

First proof:

pickforge init
pickforge doctor

Then Claude Code, Codex, or Pi can fix a real Flutter overflow through the runtime and return before/after evidence.

Decisions

• Upstream-first: integrate official or established providers before building device automation.
• Flutter-first: prove one complete inspect → fix → hot reload → verify loop before expanding.
• Rust owns the durable local CLI/core; TypeScript owns the MCP and harness edges.
• Prototype in the PickLab repository. Rename repositories/packages only after the alpha is proven.
• Agents may prepare and open PRs. Elberte performs final review and is the only person who merges.
• Feature flag: mobileIntegrationAlpha (default off; gates release exposure while the multi-PR feature lands).

Acceptance criteria

• pickforge doctor detects Flutter, required local tools, supported harnesses, and actionable failures; human and JSON output are stable.
• pickforge init --dry-run previews every change without writing.
• pickforge init applies config transactionally with backups and is idempotent.
• Claude Code, Codex, and Pi adapters configure the same Flutter integration pack.
• The Flutter pack configures the official Dart/Flutter MCP and installs a portable workflow.
• A fresh Flutter project completes inspect → source → fix → hot reload → verify.
• The run produces canonical JSON plus a concise Markdown evidence report with before/after artifacts.
• State defaults outside the repo under ~/.pickforge/pickforge/projects/<stable-project-id>/, with an explicit test override.
• Normal startup and the demo leave the project Git working tree clean except for the intended source fix.
• The TypeScript MCP edge supports current and legacy clients through dual-era conformance tests.
• Every implementation PR reaches CI green and stops at Ready for human review.

Explicit non-goals

• New IDE, embedded terminal, chat, swarm, Operator, or model router
• Custom generic Android/iOS automation already available upstream
• GUI, emulator viewer, persistent daemon, cloud sync, billing, or marketplace
• React Native or iOS support in this issue
• Immediate product/package/repository rename
• Archiving or deleting existing repositories before replacement proof and release preservation

PR plan

• PR 1 — Rust CLI foundation and Flutter-aware doctor
  • Depends on: none
  • Touches: Rust workspace/crate, path resolution, detection, CLI contract, tests, CI wiring
  • Validation: cargo fmt --check; cargo clippy --workspace --all-targets -- -D warnings; cargo test --workspace; existing Bun typecheck/test/build
  • Link: feat: add Flutter-aware Pickforge doctor #65
• PR 2 — Transactional init planner and harness adapters
  • Depends on: PR 1
  • Touches: config plan/apply/backup, Claude Code/Codex/Pi adapters, --dry-run, idempotency tests
  • Validation: focused Rust/adapter tests plus existing suite
  • Link: feat: add transactional Pickforge init #68
• PR 3 — Flutter integration pack
  • Depends on: PR 2
  • Touches: Dart/Flutter MCP manifest, portable skill, compatibility checks, release gate
  • Validation: clean-project setup tests across all three harnesses
  • Link: feat: add Flutter integration pack #69
• PR 4 — Evidence capture and report
  • Depends on: PR 3
  • Touches: run artifact schema, Markdown renderer, redaction, storage isolation
  • Validation: golden schema/report tests and clean-working-tree smoke test
  • Link: pending
• PR 5 — MCP v2 dual-era edge
  • Depends on: PR 3; independent of PR 4 where possible
  • Touches: SDK v2 split packages, serveStdio, legacy fallback, MRTR/Tasks boundaries, client conformance
  • Validation: Claude Code, Codex, Pi, and generic stdio contract tests
  • Link: pending
• PR 6 — Alpha integration and release gate
  • Depends on: PRs 1–5
  • Touches: packaging, installer exposure, docs, unreleased notes, end-to-end demo
  • Validation: fresh Flutter repo and clean-machine smoke matrix
  • Link: pending
• Final retirement-plan pass
  • Create linked issues in Pickforge IDE, PickScribe, and PickGauge for notices/release preservation; no archive/delete action in this issue.
• File follow-up issues for optional Omarchy packaging, React Native/Android, iOS/Swift, PickArena benchmarking, and final rename.

Traceability

Acceptance criterion	PR/slice	Validation	Status
Stable Flutter-aware doctor	PR 1	Rust unit/CLI contract tests	PR #65 ready for human review
Safe dry-run/apply/backup/idempotency	PR 2	Config transaction tests	PR #68 ready for human review
Three harnesses + official Dart MCP	PR 3	Clean-project harness matrix	PR #69 ready for human review
Runtime fix workflow	PRs 3, 6	End-to-end Flutter overflow demo	pending
JSON + Markdown evidence	PR 4	Schema and golden report tests	pending
External isolated storage + clean repo	PRs 1, 4, 6	Path tests and startup smoke	pending
Dual-era MCP compatibility	PR 5	Real-client/stdio conformance	pending
Human-only merge gate	Every PR	PR status stops at Ready for human review	pending

Flag lifecycle

• merged behind flag mobileIntegrationAlpha
• tested on main with the flag on
• enabled in the alpha release
• flag removed after the enabled release is verified

Kickoff

Current status: Planned

Next action: start PR 1 in an isolated worktree with the smallest Rust CLI/doctor contract that can be validated independently.

[ElbertePlinio]

Progress update:

• PR 2 implementation complete
• Serious-backend local review and targeted verification clean
• Stacked PR opened against PR 1
• GitHub CI complete
• Ready for Elberte’s final review

PR: #68
Depends on: #65
Blocked: none
Next: watch CI, then begin PR 3 from the reviewed PR 2 HEAD.

[ElbertePlinio]

PR 2 is ready for human review:

• Local serious-backend review clean
• Follow-up verification clean
• Dependency audit and gitleaks green
• Rust CI green on Ubuntu and Windows
• Existing TypeScript test/build CI green
• No open review discussions

PR: #68
Reviewed HEAD: 0e87bec
Depends on: #65
Merge authorization: Elberte only
Next: prepare PR 3 on top of this reviewed HEAD; do not merge PR 2 automatically.

[ElbertePlinio]

PR 3 contract frozen on reviewed PR 2 HEAD 0e87bec:

• Default-off gate: hidden pickforge init --mobile-integration-alpha; normal init remains the empty base pack.
• Official server: owned key pickforge-dart, command dart mcp-server.
• Roots policy: Claude uses native roots; Codex and Pi add --force-roots-fallback (Pi adapter currently has no roots support).
• Portable workflow: embedded pickforge-flutter Agent Skill, installed outside the project tree to Claude's user skill directory and the standard user .agents/skills directory for Codex/Pi.
• Compatibility: fail before planning writes when dart is absent; no tool execution, guessed version floor, subprocess, or network access.
• Safety: all config/skill/receipt writes use PR 2's transactional planner, backups, rollback, and idempotency.
• Upstream skills: referenced but not downloaded or vendored in this slice; npx skills add would violate no-network and clean-project constraints.

Next: implement and validate the clean-project three-harness matrix on branch feat/64-flutter-pack.

[ElbertePlinio]

PR 3 opened as draft: #69

• Reviewed HEAD: 1acb945
• Base: feat/64-init-planner / feat: add transactional Pickforge init #68
• Local review: clean after trust-boundary fixes and targeted verification
• Local Rust/Windows cross-target/audit/smoke gates: green
• GitHub native Windows + pinned Bun CI: in progress

The PR will move to Ready for human review only after every required check is green. Merge authorization remains Elberte-only.

[ElbertePlinio]

PR 3 is ready for human review:

• Serious-backend review complete
• Trust-boundary and cross-platform findings fixed
• Targeted fix verification clean
• Dependency audit and gitleaks green
• Rust CI green on Ubuntu and Windows
• Pinned Bun TypeScript test/coverage/build CI green
• Clean-project three-harness smoke proven

PR: #69
Reviewed HEAD: 1acb945
Depends on: #68
Merge authorization: Elberte only

Next: freeze PR 3's reviewed interfaces, then prepare PR 4 and PR 5 without merging any stack member automatically.

[ElbertePlinio]

PR 4 / PR 5 contracts frozen from reviewed PR 3 HEAD 1acb945.

PR 4 — sibling branch feat/64-evidence-report

• Rust-only Flutter evidence domain under <stateRoot>/projects/<projectId>/runs/.
• Typed schema v1, deterministic pretty JSON + trailing newline, and concise deterministic Markdown.
• Explicit before/after scenario pairing, bounded allowlisted observations, redaction, image attachment validation/copying, hashes, atomic metadata/report writes, and fail-closed path/schema handling.
• Requires the PR 3 project receipt; never writes into the project, runs tools, invokes Git, wraps/spawns Dart MCP, or modifies the TypeScript evidence system.
• The installed Flutter workflow teaches the agent to pass official Dart MCP results to Pickforge; Pickforge is a recorder, not a proxy.
• Golden schema/report tests, security/storage tests, and a Git-clean Flutter-project smoke are required.

PR 5 — sibling branch feat/64-mcp-v2

• Replace SDK v1 with stable split MCP SDK 2.0.0 packages.
• Serve stdio with one serveStdio factory; preserve default legacy serving and add modern 2026-07-28 conformance.
• Thread the negotiated era explicitly through server context.
• Preserve legacy elicitation behavior. Modern request_user_input returns honest relay guidance; no fake push elicitation.
• Tasks, MRTR/inputRequired, sampling, HTTP, installers, and new product behavior remain out of scope.
• Raw legacy/modern wire tests, stdout/stderr/shutdown checks, migrated in-memory tests, and existing real-stdio tests are required.

The sibling branches intentionally have no source overlap. PR 6 will integrate their frozen interfaces. No PR in this stack will be merged without Elberte's final authorization.

[ElbertePlinio]

Progress update — PR 4 and PR 5 are open from independently reviewed sibling branches:

• PR 4 — Flutter evidence capture/report: feat: record Flutter evidence reports #70
  • Reviewed HEAD: d6c908a
  • Local Rust, Windows cross-target, OSV, persistence, redaction, and clean-project gates passed.
• PR 5 — MCP v2 dual-era edge: feat(mcp): migrate to split SDK v2 #71
  • Reviewed HEAD: a26535e
  • Frozen install, typecheck, lint, build, focused wire/server tests, OSV, and lifecycle gates passed.
• GitHub CI green on both PRs
• Ready for human review
• PR 6 — alpha integration/release gate

Both PRs depend on #69. No merge, release, rename, or retirement action is authorized. Elberte remains the final review and merge gate.

[ElbertePlinio]

PR 4 / PR 5 checkpoint — Ready for human review

Both sibling PRs are independently reviewed, remotely verified, and fully green against feat/64-flutter-pack:

• feat: record Flutter evidence reports #70 — Flutter evidence recorder — f31101aeb08baaf2a4d5ca6e2079f6205f8bfb11
  • CI: https://github.com/pickforge/picklab/actions/runs/32087828087
  • Includes the Windows-native home-resolution/test-isolation fix discovered by CI.
• feat(mcp): migrate to split SDK v2 #71 — split MCP SDK v2 / dual-era edge — 54a195418e715360812e76fe07129fcb1589f72e
  • CI: https://github.com/pickforge/picklab/actions/runs/32086544702

Dependency audit, Gitleaks, Ubuntu Rust, Windows-native Rust, and headed Bun test/coverage/build jobs all pass on both reviewed HEADs.

Status: PRs #70 and #71 are ready for Elberte's human review. No merge, release, rename, retirement, or archival action was performed.