From 8ed32c2055a7654419214b4f2666600d30fa1d85 Mon Sep 17 00:00:00 2001 From: kurone-kito Date: Fri, 14 Aug 2026 01:35:05 +0900 Subject: [PATCH 1/2] docs(idd): note the pnpm -- passthrough footgun for four helper scripts pnpm forwards a literal `--` separator to invoked package.json scripts instead of stripping it like npm does. idd-skill's shared cli-args.mts parser strips one leading bare `--`, but four idd: scripts route around that shared parser and reproduce the footgun: idd:post-idd-marker, idd:emit-marker, idd:discover-orphan-filter, and idd:discover-roadmap-graph. Document the failure modes and the no-leading-`--` workaround near the "Authoritative invocation surface per profile" section so operators hit this once, not repeatedly. Refs #145 Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01Pp83wfp8YJ8HuEegArMJvi --- docs/idd-helper-scripts.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/idd-helper-scripts.md b/docs/idd-helper-scripts.md index 6290bae..8aad0de 100644 --- a/docs/idd-helper-scripts.md +++ b/docs/idd-helper-scripts.md @@ -599,6 +599,23 @@ 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: -- ...` 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:` 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:` 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 From 36bcb6e5028f038963661357e964c191b8d95db3 Mon Sep 17 00:00:00 2001 From: kurone-kito Date: Fri, 14 Aug 2026 01:59:36 +0900 Subject: [PATCH 2/2] docs(idd): keep inline code spans on one line in the pnpm-- note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A self-review pass flagged that two inline code spans in the new pnpm passthrough footgun note wrapped mid-span across lines, including the literal error string `missing value for argument: --`. Reflow so every inline code span stays intact on one line, matching this repo's own precedent (commit 1070cee) — the error text stays grep-able for anyone who hits it verbatim. Refs #145 Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01Pp83wfp8YJ8HuEegArMJvi --- docs/idd-helper-scripts.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/idd-helper-scripts.md b/docs/idd-helper-scripts.md index 8aad0de..35284ac 100644 --- a/docs/idd-helper-scripts.md +++ b/docs/idd-helper-scripts.md @@ -599,22 +599,23 @@ 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: -- ...` 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:` 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 +**pnpm `--`-passthrough footgun.** Under `package-manager`, +`pnpm run idd: -- ...` 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:` 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:` 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. +`idd:` 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`