feat(from-plan): make the task destination and section mapping format-agnostic

[willywg]

Summary

Follow-up to #16 (and #23). /cursor:from-plan assumes Claude's plan-mode shape in two ways: it silently drops any section the four intents don't claim, and it hardcodes where the task file goes. This PR fixes both, and the second fix turned out to need more than a config knob.

Section loss. A PRP (Context Engineering format) is the clearest case — full repro in #16: Why → context, Implementation Blueprint → approach and Validation Loop → verification all match, so the 0.5.1 verbatim fallback (which requires zero matches) never fires, and Goal, What / success criteria and All Needed Context — including its CRITICAL: gotchas — are discarded with no warning. In that example Cursor is told to build the feature with the "SSR flashes light theme" warning removed.

Where the task file goes. I first made this a config key, then hit the real problem while using it. tasksDir is stored per repository, keyed by a hash of the CWD's repo. A developer keeping PRPs centralised in one monorepo while the code lives in sibling service repos would have to set it once per repo, and every setting would point at a different PRPs/ that doesn't exist. Worse, in that layout --out-dir PRPs silently created a second, disconnected PRPs/ tree inside the wrong repo, and --in-place refused outright.

The faulty assumption wasn't the directory string — it was that the spec and the code share a repository. Notably, upstream openai/codex-plugin-cc never makes that assumption: it has no from-plan, generates no task file, reads specs via --prompt-file (codex-companion.mjs:645) without ever writing one, and confines every write to CLAUDE_PLUGIN_DATA/state/ (state.mjs:29). The tasks/ directory is an addition of this fork, not something inherited — so this PR moves back toward the upstream posture rather than away from it.

Changes

• Never drop an unmapped section. Leftovers are carried through under ## Additional specification context, preserving the author's original heading casing (splitSections now also returns a headings map). Only reviewer-facing commentary stays on an explicit drop-list: Effort / risks, Open questions, Alternatives considered, Notes to reviewer. A ## Goal section fills the Goal slot instead of the task file echoing its own title.
• Derive the destination from the spec. Point the command at a project spec and the task file is written next to it — PRPs/018-wizard.md → PRPs/<stamp>-018-wizard.md. Spec-driven projects need no configuration at all. New isPlanModeFile() distinguishes a project spec from one of Claude's ~/.claude/plans/ files.
• Multi-repo as a first-class case. New referenceFor(): @path inside the repo, absolute path outside it. cursor-agent reads absolute paths fine (verified), so a spec in another repo is reachable, and the prompt tells Cursor to apply its changes in the current repository. The --in-place outside-the-repo guard is dropped as unnecessary.
• Config demoted to a fallback. Resolution order: --out-dir → the spec's own directory → CURSOR_PLUGIN_CC_TASKS_DIR → per-repo tasksDir → tasks/. The last three apply only to plan-mode files. /cursor:setup --tasks-dir <dir> / --no-tasks-dir persists it, surfaced in --doctor.

Plan-mode output is unchanged. With no spec path, no flag, no env var and no config, output still lands in tasks/ and conversions are byte-identical — the existing plan.test.mjs assertions (including not.toContain('Effort / risks')) pass untouched.

Happy to reshape any of this — e.g. drop the /cursor:setup key and keep flag + env only, or split the section-loss fix from the destination work into two PRs if you'd rather review them separately.

Closes #16

Test plan

• npm test — 151 specs green (24 new, covering: section leftovers and the still-dropped commentary; isPlanModeFile; the five-level destination precedence; referenceFor inside/outside/name-prefix-sibling; and end-to-end runs through main() for the same-repo, spec-derived, and cross-repo cases)
• npm run lint — prettier + eslint clean
• npm run typecheck — tsc --checkJs clean (JSDoc updated for headings, the config shape, and the new helpers)
• Smoke-tested the real multi-repo layout: two git repos, PRPs 016–018 in the monorepo, command run from the sibling code repo. The task file joined its siblings in the monorepo; the code repo got no PRPs/ and no tasks/; --in-place succeeded where it previously errored; the CRITICAL: gotcha reached the generated task file.
• Verified cursor-agent reads an absolute path outside its repo before relying on it (cursor-agent --print --force from repo A reading a file in repo B returned the file's heading).
• Docs updated — README.md, commands/from-plan.md, commands/setup.md, CHANGELOG.md (## Unreleased)

Checklist

• No new runtime dependencies — node stdlib only (node:path)
• No build step, no new dist/ or .ts files
• $ARGUMENTS is quoted in every edited commands/*.md
• No new slash command (flags on existing ones)
• User-visible behaviour change noted under ## Unreleased in CHANGELOG.md