fix(endsession): parse arguments with the arg-parser so a slug with -h is no help request, and only the operator starts it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

CLAUDE.md

@@ -140,7 +140,7 @@ Full flag reference for each command (modes, `--gates`, `--profile`, breaking ch
 | `voyage:annotating` | The operator-annotation loop: the person writes every note, Claude none; Fix/Change edit only the quoted text, a Question is answered and changes nothing; the approval an edit costs is said first (stale brief intent → `/trekplan` halts; changed plan → K2, `/trekexecute` refuses); page rebuilt after the revision; research documents on request | `/trekbrief`, `/trekplan`, `/trekreview` name it where they build the page |
 | `voyage:writing-criteria` | Each criterion / `Verify:` / `Regression:` / `End-to-end:` is one command the criteria runner accepts, as the line's first backticked span; anything more is `bash tests/<name>.sh`; it must be able to go red (runner deterministic, go-red prose only) | `brief-reviewer` + `plan-critic` `skills:` (preload); `/trekplan` names it |
 
-> **Commands are the trunk** (operator, 06.10). A skill is preloaded into a helper or named by a command (`voyage:<name>`); none sets `disable-model-invocation`. Form = S1, checked by `lib/skills/skill-lint.mjs`; `lib/skills/routing.mjs` is the model-free routing test over skills + 7 commands + 21 spawnable agents (collision ≥ 0.75 fails; thresholds pinned, never lowered). Eval cases `evals/skill-*` (3 fire / 2 quiet / 1 effect) are written, not run.
+> **Commands are the trunk** (operator, 06.10). A skill is preloaded into a helper or named by a command (`voyage:<name>`); no skill sets `disable-model-invocation`; the one command that does is `/trekendsession`, operator-typed only (Claude Code still lets the operator type it; the model cannot start it). Form = S1, checked by `lib/skills/skill-lint.mjs`; `lib/skills/routing.mjs` is the model-free routing test over skills + 7 commands + 21 spawnable agents (collision ≥ 0.75 fails; thresholds pinned, never lowered). Eval cases `evals/skill-*` (3 fire / 2 quiet / 1 effect) are written, not run.
 > Every case in `evals/` (the test set too) carries `from=<event>`; the routing test fails one without it and reports both counts, checked for `from=` and routed; a quiet case's owner may be Claude Code's own `run` (`BUILTIN_OWNERS`, R2), outside the corpus, so only "not taken" is checked
 > (P10's model-free part, R1; the release eval gate is exempted until the test set runs again). Method (red baseline first) → `docs/skills-authoring.md`.
 

commands/trekendsession.md

@@ -2,6 +2,7 @@
 name: trekendsession
 description: Mark the current session as complete and write session-state pointing at the next session. Helper for informal multi-session flows.
 argument-hint: "<next-brief-path> <next-label> | --help"
+disable-model-invocation: true
 ---
 
 # Voyage End-Session Local v1.0
@@ -29,8 +30,25 @@ See **Handover 7** in `docs/HANDOVER-CONTRACTS.md` for the schema.
 
 ## Phase 0 — `--help` handling
 
-If `$ARGUMENTS` contains `--help` or `-h`, print the usage block below and exit
+Parse `$ARGUMENTS` with the arg parser. Run this via the Bash tool at runtime
-cleanly. Do NOT proceed to any further phase.
+(NOT eager-exec):
+
+```bash
+setopt nonomatch 2>/dev/null || true
+node ${CLAUDE_PLUGIN_ROOT}/lib/parsers/arg-parser.mjs --command trekendsession -- $ARGUMENTS
+```
+
+It prints the parse result as JSON. On exit 1, print its `errors` and stop.
+
+Print the usage block below and exit cleanly ONLY when one of these two
+conditions equals exactly true (no substring search, no "contains" check):
+
+- `flags['--help'] === true`, OR
+- `positional[0] === '-h'` (single-dash short form — the parser keeps it as
+  positional because the schema declares no alias).
+
+Then do NOT proceed to any further phase. In every other case — a slug or a
+label that holds `-h` or `help` too — go on to Phase 1.
 
 ```
 /trekendsession — Mark current session done; point at next session.
@@ -76,8 +94,9 @@ Decision tree:
 
 ## Phase 2 — Required args check (headless-safe)
 
-Read `$ARGUMENTS`. Both `<next-brief-path>` and `<next-label>` are required.
+Read the parse result from Phase 0: `<next-brief-path>` is `positional[0]`
-If either is missing or empty:
+and `<next-label>` is `positional[1]`. Both are required. If either is
+missing or empty:
 
 ```
 Error: missing required args.
@@ -176,6 +195,7 @@ before retrying — usually means a bad path or label argument.
 - **Atomic write only.** Tmp + rename — no partial state files on disk.
 - **Zero secrets.** Status, paths, labels — never API keys, never user content
   beyond filenames.
-- **NEVER auto-invoke this command.** It is operator-typed only at session-end.
+- **NEVER auto-invoke this command.** It is operator-typed only at session-end
+  (the frontmatter field keeps the model from starting it; the operator types it).
 - **Idempotent within a session.** Running twice with the same args
   overwrites cleanly (atomic rename); does not double-advance.

lib/parsers/arg-parser.mjs

@@ -1,5 +1,5 @@
 // lib/parsers/arg-parser.mjs
-// Parse $ARGUMENTS strings for the four voyage commands.
+// Parse $ARGUMENTS strings for the seven voyage commands.
 //
 // Each command has its own valid-flag set; passing flags from another command
 // produces an `unknown_flags` array but does not error — the caller decides.
@@ -38,6 +38,11 @@ const FLAG_SCHEMA = {
     valued: ['--profile'],
     aliases: {},
   },
+  trekendsession: {
+    boolean: ['--help'],
+    valued: [],
+    aliases: {},
+  },
 };
 
 /**

tests/lib/arg-parser.test.mjs

@@ -1,7 +1,12 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { parseArgs } from '../../lib/parsers/arg-parser.mjs';
 
+const PARSER = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'lib', 'parsers', 'arg-parser.mjs');
+
 test('trekbrief — empty args', () => {
   const r = parseArgs('', 'trekbrief');
   assert.equal(r.command, 'trekbrief');
@@ -155,3 +160,43 @@ test('trekcontinue — .md positional accepted by parser (rejection is command-l
   assert.deepEqual(r.positional, ['NEXT-SESSION-PROMPT.local.md']);
   assert.deepEqual(r.errors, []);
 });
+
+// --- #15 — /trekendsession reads its arguments with the parser ---
+// A slug or label holding "-h" is an argument, not a help request: only the
+// exact --help flag or a lone -h as the first positional asks for help.
+
+test('[#15] trekendsession — a slug is one positional, with no errors', () => {
+  const r = parseArgs('2026-05-01-hotfix', 'trekendsession');
+  assert.deepEqual(r.errors, []);
+  assert.deepEqual(r.positional, ['2026-05-01-hotfix']);
+  assert.equal(r.flags['--help'], undefined);
+});
+
+test('[#15] trekendsession — a path and a quoted label are two positionals, with no --help', () => {
+  const r = parseArgs('fix-header "Session 2"', 'trekendsession');
+  assert.deepEqual(r.errors, []);
+  assert.deepEqual(r.positional, ['fix-header', 'Session 2']);
+  assert.equal(r.flags['--help'], undefined);
+});
+
+test('[#15] trekendsession — --help is the boolean help flag', () => {
+  const r = parseArgs('--help', 'trekendsession');
+  assert.deepEqual(r.errors, []);
+  assert.equal(r.flags['--help'], true);
+  assert.deepEqual(r.unknown, []);
+});
+
+test('[#15] trekendsession — the CLI with --command trekendsession -- fix-header exits 0', () => {
+  const r = spawnSync(process.execPath, [PARSER, '--command', 'trekendsession', '--', 'fix-header'], { encoding: 'utf8' });
+  assert.equal(r.status, 0, `the parser CLI refused trekendsession: ${r.stdout}${r.stderr}`);
+  const out = JSON.parse(r.stdout);
+  assert.deepEqual(out.positional, ['fix-header']);
+  assert.equal(out.flags['--help'], undefined);
+});
+
+test('trekendsession — -h stays a positional (no alias resolution)', () => {
+  const r = parseArgs('-h', 'trekendsession');
+  assert.deepEqual(r.positional, ['-h']);
+  assert.deepEqual(r.errors, []);
+  assert.equal(r.flags['--help'], undefined);
+});

tests/lib/fix-round-4-5a-prose.test.mjs

@@ -1041,3 +1041,74 @@ test('[D67] the End to end section says to record run_seen, also when no app was
   assert.match(s, /The verdict is still the `End-to-end:` command\./,
     'the End to end section no longer says the End-to-end: command is the verdict');
 });
+
+// --- #15 / #67 -----------------------------------------------------------------------
+// #15: /trekendsession's Phase 0 printed its usage when $ARGUMENTS merely
+// contained "--help" or "-h", so a slug such as "fix-header" asked for help.
+// It now runs the arg parser and dispatches only on its exact result.
+// #67: "NEVER auto-invoke this command" was a sentence only; the frontmatter
+// now carries disable-model-invocation, so the model cannot start it.
+
+const ENDSESSION = 'commands/trekendsession.md';
+const ENDSESSION_PARSER_LINE = 'node ${CLAUDE_PLUGIN_ROOT}/lib/parsers/arg-parser.mjs --command trekendsession -- $ARGUMENTS';
+
+/** The Phase 0 parser line run through bash() with `args` in place of $ARGUMENTS. */
+function runEndsessionParser(cmd, args) {
+  return bash(cmd.split('$ARGUMENTS').join(args), ROOT);
+}
+
+test('[#15] /trekendsession Phase 0 has no "contains --help or -h" check, and its parser line run on fix-header gives no help', () => {
+  const phase0 = section(read(ENDSESSION), '## Phase 0 — `--help` handling');
+  assert.doesNotMatch(flat(phase0), /contains\s+`?--help`?\s+or\s+`?-h`?/i,
+    'Phase 0 still prints help when $ARGUMENTS merely contains --help or -h');
+  assert.match(flat(phase0), /`flags\['--help'\] === true`/, 'Phase 0 does not dispatch on the parsed --help flag');
+  assert.match(flat(phase0), /`positional\[0\] === '-h'`/, 'Phase 0 does not dispatch on a lone -h as the first positional');
+  const cmd = line(phase0, 'parsers/arg-parser.mjs');
+  assert.equal(cmd, ENDSESSION_PARSER_LINE, 'the Phase 0 parser line is not the trekendsession parser call on $ARGUMENTS');
+  const block = phase0.split('\n```bash\n').slice(1).map((b) => b.split('\n```')[0]).find((b) => b.includes(cmd));
+  assert.ok(block, 'the parser line is not in a runtime ```bash block');
+  assert.equal(block.split('\n')[0], 'setopt nonomatch 2>/dev/null || true', 'the block does not open with setopt nonomatch');
+  const plain = runEndsessionParser(cmd, 'fix-header');
+  assert.equal(plain.status, 0, `the parser line refused fix-header: ${plain.stdout}${plain.stderr}`);
+  const r = JSON.parse(plain.stdout);
+  assert.equal(r.flags['--help'], undefined, 'fix-header set the --help flag');
+  assert.deepEqual(r.positional, ['fix-header']);
+  assert.notEqual(r.positional[0], '-h');
+  const help = runEndsessionParser(cmd, '--help');
+  assert.equal(help.status, 0, help.stdout + help.stderr);
+  assert.equal(JSON.parse(help.stdout).flags['--help'], true, 'control: --help must set the help flag');
+  const two = runEndsessionParser(cmd, 'fix-header "Session 2"');
+  assert.equal(two.status, 0, two.stdout + two.stderr);
+  assert.deepEqual(JSON.parse(two.stdout).positional, ['fix-header', 'Session 2']);
+});
+
+test('[#15] /trekendsession Phase 2 reads the brief path and the label from the parser\'s positional', () => {
+  const phase2 = flat(section(read(ENDSESSION), '## Phase 2 — Required args check (headless-safe)'));
+  assert.match(phase2, /`positional\[0\]`/, 'Phase 2 does not read <next-brief-path> from positional[0]');
+  assert.match(phase2, /`positional\[1\]`/, 'Phase 2 does not read <next-label> from positional[1]');
+});
+
+test('[#67] /trekendsession sets disable-model-invocation, and CLAUDE.md names it as the one command that does', () => {
+  const text = read(ENDSESSION);
+  const fm = readFrontmatterFields(text);
+  assert.ok(fm.ok, fm.error);
+  assert.equal(fm.fields['disable-model-invocation']?.value, 'true',
+    'commands/trekendsession.md does not set disable-model-invocation: true');
+  assert.match(flat(text),
+    /\*\*NEVER auto-invoke this command\.\*\* It is operator-typed only at session-end \(the frontmatter field keeps the model from starting it; the operator types it\)/,
+    'the hard rule does not say the frontmatter field keeps the model from starting it');
+  const withField = readdirSync(join(ROOT, 'commands')).filter((f) => f.endsWith('.md'))
+    .filter((f) => readFrontmatterFields(read(`commands/${f}`)).fields['disable-model-invocation'] !== undefined);
+  assert.deepEqual(withField, ['trekendsession.md'], 'trekendsession must be the one command with the field');
+  const trunk = read('CLAUDE.md').split('\n').find((l) => l.startsWith('> **Commands are the trunk**'));
+  assert.ok(trunk, 'CLAUDE.md has no "Commands are the trunk" note');
+  assert.doesNotMatch(trunk, /none sets `disable-model-invocation`/, 'CLAUDE.md still says no command or skill sets the field');
+  assert.ok(trunk.includes('no skill sets `disable-model-invocation`; the one command that does is `/trekendsession`, operator-typed only (Claude Code still lets the operator type it; the model cannot start it)'),
+    'CLAUDE.md does not name /trekendsession as the one command that sets the field');
+});
+
+test('keep: commands/trekreview.md carries no disable-model-invocation field (/trekexecute starts it through the Skill tool)', () => {
+  const fm = readFrontmatterFields(read('commands/trekreview.md'));
+  assert.ok(fm.ok, fm.error);
+  assert.equal(fm.fields['disable-model-invocation'], undefined);
+});