Merge #412: refuse missing validator flag values

what changed: path-authority and researcher-release refuse missing, empty or next-flag value tokens by name, with usage and exit 2 before resolving paths.

why: Invalid CLI input previously reached Node path handling and produced an internal message or TypeError stack.

what it touched: Both parsers, their regression tables, architecture descriptions, changelog and the 1,838-test inventory.

what you verified: verified - red-first regressions, 40 current focused tests, normal full commit gate accepted 3770719, and all seven CI jobs passed in run 38558206514. Main and PR head checked immediately before merge.

what you got wrong and fixed: nothing to report.

Author: StepenkoAnatoli

CHANGELOG.md

@@ -5,6 +5,8 @@ Each release of Research-Kit, newest first. The version is `KIT_VERSION` in
 
 ## Unreleased
 
+- `path-authority` and `researcher-release` name a value flag with no value and print usage with exit 2 before resolving paths, including when another flag follows (#288).
+
 - `property-replay --all` refuses a missing regression directory with exit 2 and
   names it; an existing empty directory explicitly reports no captured regressions.
   JSON results identify the directory and zero count (#307).

docs/ARCHITECTURE.md

@@ -277,14 +277,17 @@ markers - they wrote `research/` into any folder until 2026-09-28, `prior` a PRI
 `doctor --fix-arity` and `install` name a write the system refused - `could not write <file>:
 <CODE> (why)`, exit 2, via `writeFailure` - where they printed a stack trace, 2026-09-28),
 `path-authority.mjs` (offline Git-origin/path-authority snapshot validation and
-schema conformance),
+schema conformance; refuses a missing value for `--file`, `--schema` or `--root` by
+name before reading any input, as a usage error with exit 2),
 `researcher-release.mjs` (ported 2026-09-20, ADR-0029 — three subcommands over the two
 validators: `validate` for R28–R32 release evidence, `conform` for schema-only checking,
 `fi-validate` for an FI bundle. It **duplicates no validation**: every check comes from
 `release-validator.mjs` or `fi-validator.mjs` through their public exports. Reads **no
 environment variable at all**, so it cannot depend on a credential or a config. Status
 maps to exit code — `PASS` 0, `FAIL`/`REOPEN` 1, `INCOMPLETE` 2, `BLOCKED` 3, unknown 4 —
 and a **usage error exits 2 from every subcommand**, printing the usage block to stderr;
+its argument parser names a value flag without a value before resolving any path,
+including when the next token is another flag;
 `test/support-policy.test.mjs` pins that by running the CLI. It writes exactly one thing,
 only when asked: `fi-validate --report <file>`),
 `selftest.mjs` (every requested group must match a test file before any test starts; an unmatched group is named and refused with exit 2, including beside a valid group; #332. CLI regressions isolate child report paths from the parent suite; the whole suite, queued by the harness — which **awaits** every test,

research-kit/README.md

@@ -568,7 +568,7 @@ node research-kit/bin/selftest.mjs            # all of it
 node research-kit/bin/selftest.mjs gate hook  # just these files
 ```
 
-1836 tests, offline, no key and no network. The runner **awaits** every test, so `ok` means
+1838 tests, offline, no key and no network. The runner **awaits** every test, so `ok` means
 the assertions settled (ADR-0021), and each test is raced against a watchdog
 (`RESEARCH_KIT_TEST_TIMEOUT`, default 60s).
 

research-kit/bin/path-authority.mjs

@@ -22,6 +22,10 @@ function parse(argv) {
   for (let i = 1; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--json') { result.json = true; continue; }
+    if (['--file', '--schema', '--root'].includes(arg)
+      && (argv[i + 1] === undefined || argv[i + 1] === '' || argv[i + 1].startsWith('--'))) {
+      return { error: `${arg} needs a value` };
+    }
     if (arg === '--file') { result.files.push(argv[++i]); continue; }
     if (arg === '--schema') { result.schema = argv[++i]; continue; }
     if (arg === '--root') { result.root = argv[++i]; continue; }

research-kit/bin/researcher-release.mjs

@@ -29,6 +29,10 @@ function argsAfterCommand(argv) {
   for (let i = 1; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--json') { result.json = true; continue; }
+    if (arg.startsWith('--')
+      && (argv[i + 1] === undefined || argv[i + 1] === '' || argv[i + 1].startsWith('--'))) {
+      return { error: `${arg} needs a value` };
+    }
     if (arg === '--file') { result.files ??= []; result.files.push(argv[++i]); continue; }
     if (arg.startsWith('--')) { result[arg.slice(2).replaceAll('-', '')] = argv[++i]; continue; }
     result._.push(arg);
@@ -47,6 +51,7 @@ function exitFor(status) {
 function main(argv = process.argv.slice(2)) {
   if (argv.includes('--help') || argv.includes('-h')) { process.stdout.write(`${usage()}\n`); return 0; }
   const parsed = argsAfterCommand(argv);
+  if (parsed.error) { console.error(`${parsed.error}\n${usage()}`); return 2; }
   let result;
   if (parsed.command === 'validate') {
     if (!parsed.root || !parsed.package || !parsed.registry || !parsed.roles || !parsed.pointers) {

research-kit/test/path-authority-validator.test.mjs

@@ -102,6 +102,20 @@ test('path-authority validator rejects out-of-root paths, symlink claims, host m
   assert(result.errors.some((error) => error.code === 'SNAP-ORIGIN-UNPROVEN'), JSON.stringify(result.errors));
 });
 
+test('path-authority names a missing value before validating any input', () => {
+  for (const flag of ['--file', '--schema', '--root']) {
+    for (const tail of [[], ['--json']]) {
+      const args = ['research-kit/bin/path-authority.mjs', 'validate', flag, ...tail];
+      const run = spawnSync(process.execPath, args, { encoding: 'utf8' });
+      const output = `${run.stdout}${run.stderr}`;
+      assertEqual(run.status, 2, `${args.join(' ')}: ${output}`);
+      assert(run.stderr.includes(`${flag} needs a value`), output);
+      assert(run.stderr.includes('Usage:'), output);
+      assert(!/TypeError|paths\[0\]|ERR_INVALID_ARG_TYPE/.test(output), output);
+    }
+  }
+});
+
 test('path-authority CLI conform and validate are offline, deterministic, and read-only', async () => {
   const root = tempRoot();
   try {

research-kit/test/release-validator.test.mjs

@@ -188,6 +188,23 @@ test('researcher-release validate emits the contract status and exit code withou
   }
 });
 
+test('researcher-release names a missing value before resolving paths', () => {
+  for (const flag of ['--file', '--schema', '--root']) {
+    for (const tail of [[], ['--json']]) {
+      const args = [
+        'research-kit/bin/researcher-release.mjs', 'conform', '--schema', 'missing-schema.json',
+        '--file', 'missing-record.json', flag, ...tail,
+      ];
+      const run = spawnSync(process.execPath, args, { encoding: 'utf8' });
+      const output = `${run.stdout}${run.stderr}`;
+      assertEqual(run.status, 2, `${args.join(' ')}: ${output}`);
+      assert(run.stderr.includes(`${flag} needs a value`), output);
+      assert(run.stderr.includes('Usage:'), output);
+      assert(!/TypeError|paths\[0\]|ERR_INVALID_ARG_TYPE/.test(output), output);
+    }
+  }
+});
+
 test('researcher-release conform validates explicit files and maps schema failure to exit 1', async () => {
   const root = tempRoot();
   try {