cad-capture

Capture through the seam - one call, and the only way this command reaches .planning/CAPTURE.md:

node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/planning.mjs" capture --kind <kind> --text-file <path> --phase <N>

Write the sentence to a scratch file and pass the PATH, never interpolate it (caller-derived text - cadence-core/references/conventions.md). --text remains for a human at a shell.

Pass --phase only with --kind todo, and leave it off entirely when step 1 found no phase. The seam owns every byte: it creates the file with its headings when absent, puts the bullet under the one heading that kind owns, stamps a note's date itself, and holds a lock so a concurrent writer cannot erase the line. Do not compose the bullet yourself and do not reach that file with any other tool - a second statement of the format is how the queue's writer and its reader drifted apart, and five filed items were lost to it.

An ok:false return STOPS the capture: report its reason back with the user's own sentence, so nothing is lost and they can re-run it, and skip step 3. A bullet that did not land is never reported as captured. capture-locked means another writer holds the queue at this instant, and running the call again is the whole fix.

Persist - the project-directed arm only, never under --cadence. Stage ONLY .planning/CAPTURE.md and commit docs: capture <kind> (protected-branch guard applies) - this never touches the user's in-flight changes. Report the one line captured and where.

--cadence: the note is about Cadence itself. REPLACES steps 2-3.

• The queue sits beside the global config layer: CAPTURE.md in the directory part of CADENCE_GLOBAL_CONFIG when that variable is set, in ~/.claude/cadence/ otherwise - the resolution cadence-core/bin/lib/config-merge.mjs performs for the config file. Never ${CLAUDE_PLUGIN_ROOT}: the next upgrade orphans a write there. Resolve that path yourself and hand it to the same seam, which creates the file and its directory when absent, so one writer serves both queues:

  node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/planning.mjs" capture --kind <kind> --text-file <path> --file <resolved dir>/CAPTURE.md
  

• The entry is the user's own sentence plus two fields, carried inside the --text-file sentence and never a phase: <text> (host: <host>, command: /cad-<name>). HOST: this repo's origin URL (git remote get-url origin), else the basename of the root from git rev-parse --show-toplevel, else the absolute working directory when this is not a repo - origin first because a worktree and a detached checkout both still resolve through it. COMMAND: the /cad-* whose behaviour caused the friction, from the invocation when the user names one, asked for once when not.

• Quote nothing else from this tree - no diff, no file contents, no path out of the user's own work. There is no redaction machinery here, and this rule stands in for it.

• Three rails. (a) NO commit - not in this repo, not in the global directory, which is not a working tree at all - so step 3 does not run. (b) Nothing is transmitted; a note meant for a maintainer who is not the user stays a manual export the user makes. (c) If that directory cannot be resolved (homedir() throws under an arbitrary UID) or the seam refuses the path, say so and STOP - NEVER fall back to .planning/CAPTURE.md, since a note landing in the host repo is the failure this arm exists to close. Report the one line captured and the file it landed in.