Close out the local-dev project: docs reconciled, evidence migrated, workspace removed

[wmadden-electric]

$ prisma-composer dev module.ts     # any Composer app, no PRISMA_* env set
[dev] ready:
[dev] storefront        http://localhost:3004
[dev] catalog.service   http://localhost:3000
^C                                  # services stop; emulators and data stay warm

This PR closes the local-dev project: the feature is shipped and proven, so the transient project workspace comes out of the repo, and everything durable moves into the design docs.

The implementation landed through #158 (watch + directory builds), #159 (the S3 wire protocol package), #160 (the emulator daemons), #162 (the localTarget seam), and #164 (the dev command). The diff here is docs-only by nature — a close-out — and does three things:

1. Reconciles the design docs with what shipped. ADR-0041, the ADR index, local-dev.md, and deploy-cli.md still described the pre-rename seam (dev field, DevDescriptor); they now describe ExtensionDescriptor.localTarget and LocalTargetDescriptor, the names actually in the code. The warm-restart finding is marked fixed (feat(cli): prisma-composer dev — bring the whole app up locally, credential-free #164), and the watch-path caveat is updated: both build adapters populate Bundle.watch now.

2. Migrates the durable evidence into local-dev.md. A "Proven against a real app" section records what the proving pass established: open-chat — a real, pre-existing Composer app in its own repo — came up credential-free under prisma-composer dev (sign-in, history, live-tail all working), failing at exactly one place, the outbound OpenRouter call, where a placeholder stood in for the unset secret. That is the designed failure boundary, observed end to end. Restart latency is recorded beside it: median 3.24s per edit-rebuild-reconverge cycle (5 runs, examples/store, Apple M3 Max).

3. Deletes .drive/projects/local-dev/ (the spec and plan, ~1,100 lines). The spec's job was zero-ambiguity implementation contracts; the implementation now on main is that contract, and the repo's rule is that transient project artifacts do not outlive their project. The raw proving assets (port friction log, patch, latency script) live on the claude/local-dev-s6-proof branch if ever needed.

Acceptance, verified

The project's acceptance criteria are all enforced or recorded: credential-free bring-up with a served HTTP round-trip, one-service-restart on rebuild, data surviving Ctrl-C and warm restart, --fresh clearing it, the bucket round-trip through plain files, the placeholder-secret and missing-env-param behaviors — each is a required CI integration test on main (local-dev.integration.ts, local-dev-store.integration.ts, local-dev-criteria-4-5.integration.ts). The real-app port and the latency target are the recorded proof now in local-dev.md.

Alternatives considered

• Landing the proving assets on main first, deleting them at close-out (the closed Proof: an existing Composer app runs locally with zero cloud credentials #166) — churn: files whose next act is deletion. Folded here instead, with the durable content migrated and the raw assets left on their branch.
• Keeping the spec in-repo as documentation — it was a build-time contract, not reader documentation; the design docs are the durable surface, and stale duplicated contracts are how docs rot.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@wmadden-electric, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 45 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 78299b59-d1cf-4060-bd6f-f061788a36df

📥 Commits

Reviewing files that changed from the base of the PR and between d0377c9 and c93d340.

📒 Files selected for processing (2)

• docs/design/10-domains/local-dev.md
• docs/design/90-decisions/ADR-0041-local-dev-runs-the-deploy-pipeline-against-local-providers.md

Walkthrough

The local development documentation now uses localTarget instead of dev for extension descriptors and updates the associated contract and error wording. It documents warm-start service recovery after Ctrl-C, watch behavior, restart latency, and migration handling. Deploy CLI documentation adds prisma-composer dev and clarifies flag applicability. ADR-0041 and its index are reconciled with the renamed interface. The local-dev project plan and specification files were removed.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the docs reconciliation, evidence migration, and workspace removal in the PR.
Description check	✅ Passed	The description is directly about the local-dev closeout and matches the documented changes.
Linked Issues check	✅ Passed	The changes align with #166 by reconciling localTarget docs, recording proof and latency, and removing the transient workspace.
Out of Scope Changes check	✅ Passed	No clearly unrelated changes are present; the deletions and doc edits all support the close-out objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/local-dev-close-out

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/local-dev-close-out

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/design/10-domains/local-dev.md`:
- Around line 37-39: Update the documented local-development pipeline hooks to
use the shipped ExtensionDescriptor.localTarget descriptor instead of the
nonexistent dev.container, dev.emulators, dev.providers(), and dev.attach
fields. Ensure every affected reference and reader consistently resolves hooks
through localTarget.
- Around line 37-39: Update the local development documentation around the
`localTarget` requirement to state that only non-build-only extensions must
provide a descriptor. Explicitly document that build-only extensions are exempt,
and ensure the extension factory guidance does not imply that every configured
extension must resolve a platform.
- Around line 272-276: Update the parenthetical note near the “Restart latency
is measured” sentence to remove the reference to the deleted implementation spec
and point readers to the retained ADR/domain documentation instead. Preserve the
existing settled behavior details and wording unrelated to the documentation
reference.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 9f7fcce5-2318-4762-8324-8968bedc6612

📥 Commits

Reviewing files that changed from the base of the PR and between cb93583 and d0377c9.

📒 Files selected for processing (6)

• .drive/projects/local-dev/plan.md
• .drive/projects/local-dev/spec.md
• docs/design/10-domains/deploy-cli.md
• docs/design/10-domains/local-dev.md
• docs/design/90-decisions/ADR-0041-local-dev-runs-the-deploy-pipeline-against-local-providers.md
• docs/design/90-decisions/README.md

💤 Files with no reviewable changes (2)

• .drive/projects/local-dev/plan.md
• .drive/projects/local-dev/spec.md