Skip to content

docs(idd): note the pnpm -- passthrough footgun for four helper scripts #146

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kurone-kito merged 2 commits into from
Aug 13, 2026
Merged

docs(idd): note the pnpm -- passthrough footgun for four helper scripts #146

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8ed32c2
docs(idd): note the pnpm -- passthrough footgun for four helper scripts
kurone-kito Aug 13, 2026
36bcb6e
docs(idd): keep inline code spans on one line in the pnpm-- note
kurone-kito Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/idd-helper-scripts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -599,6 +599,24 @@ retained. `instructions-only` uses neither. When an instruction shows a
`node scripts/...` command, resolve it to your profile's authoritative surface
rather than maintaining both.

**pnpm `--`-passthrough footgun.** Under `package-manager`,
`pnpm run idd:<name> -- <flag>...` forwards the literal `--` separator
to the invoked script instead of stripping it (npm strips it; pnpm does
not). `idd-skill`'s shared `cli-args.mts` parser strips one leading bare
`--`, so most `idd:<name>` scripts tolerate either form — but four
scripts route around that shared parser and reproduce the footgun:
`idd:post-idd-marker` and `idd:emit-marker` fail with
`missing value for argument: --`; `idd:discover-orphan-filter` and
`idd:discover-roadmap-graph` fail with `unknown argument: --`. Invoke
these four **without** a leading `--` separator —
`pnpm run idd:post-idd-marker --type claim ...`, not
`pnpm run idd:post-idd-marker -- --type claim ...` — every other
`idd:<name>` script in this repository's `package.json` tolerates
either form. This is a known upstream (`idd-skill`) gap, not a local
misconfiguration; revisit this note whenever the
`@kurone-kito/idd-skill` pin changes, since a future bump may narrow or
remove the affected list.

**Authoring rule for instructions/docs.** A mandatory helper step (one
with no skip/fallback wording) must always name an `instructions-only`
fallback, since that profile has no helper runtime at all. Every helper
Expand Down
Loading