Kjell Tore Guttormsen 9ecd225018 feat(ultraplan-local): Spor 3 — semantic plan-critic, examples, CC features, security docs

- agents/plan-critic.md: rule #7 split into literal blockers (TBD/TODO/FIXME)
  + semantic rubric with 8 deferred-decision tests; calibrated against the
  5-phrase corpus from the v3.1.0 quality brief
- hooks/hooks.json: rebuilt from corrupted state; valid JSON, registers
  PreToolUse(Bash,Write), UserPromptSubmit, PostToolUse(Bash), PreCompact
- hooks/scripts/session-title.mjs: NEW — sets ultra:<cmd>:<slug> session
  title for ultra commands (CC v2.1.94+)
- hooks/scripts/post-bash-stats.mjs: NEW — appends duration_ms per Bash
  call to ultraexecute-stats.jsonl (CC v2.1.97+)
- SECURITY.md: NEW — Forgejo private-issue reporting, supported = current
  minor only, scope = 4 hooks + denylist, hardening recommendations
- docs/architect-bridge-test.md: NEW — manual smoke checklist for the
  ultraplan ↔ ultra-cc-architect bridge
- examples/01-add-verbose-flag/: NEW — calibrated end-to-end (brief +
  research + plan + progress.json) for fork-er onramp; all four artifacts
  pass their validators
- README.md: + Extending the plugin, + Headless multi-session tuning
  (MCP_CONNECTION_NONBLOCKING), + Session titles, + Per-step timing,
  + disableSkillShellExecution recommendation
- CLAUDE.md: documents session-title.mjs and post-bash-stats.mjs
- root README.md: v3.1.0 entry expanded with Spor 2+3 deliverables

CC features adopted: F8, F9, F12 implemented; F3 implemented as Bash
PostToolUse logger; F2 (hook 'if'-field scoping) deferred — universal
protection beats reduced-scope protection for blocked commands.

Tests: 109/109 green.

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

2026-05-01 06:28:44 +02:00

3.3 KiB

Raw Blame History

type	research_version	question	confidence	dimensions	created
ultraresearch-brief	1.0	How does small-auth currently parse arguments and where should --verbose hook in?	0.85	4	2026-05-01

CLI parser conventions in small-auth

Executive Summary

small-auth uses a hand-rolled argv parser at src/cli.mjs:12-58 with a two-pass approach: first pass extracts global flags (currently --help, --version), second pass dispatches to command handlers in src/commands/*.mjs. Adding --verbose requires touching only the first-pass extractor and a new verbose parameter in the handler contract — six command handlers each get a one-line update.

The parser does not use commander, yargs, or any external library — this is intentional (zero deps) and consistent with the plugin marketplace's broader convention. We keep that.

stderr is currently unused except for fatal errors. Adding verbose output to stderr does not collide with anything.

Confidence: 0.85. The 0.15 uncertainty is around whether --verbose should propagate into nested helper modules (src/lib/auth-token.mjs calls src/lib/db.mjs); the plan should either pass verbose via a context object or use a module-scoped log function. Both work; the brief doesn't specify, so the planner will choose.

Dimensions

1. Argument-parsing layer

The parser at src/cli.mjs:12-58 returns {globalFlags: {help, version}, command, positional, commandFlags}. We add verbose: boolean to globalFlags. The two-pass design means --verbose works in any position automatically — no extra effort.

-v short form maps to --verbose via the existing alias table at src/cli.mjs:34.

2. Command-handler contract

Each handler in src/commands/*.mjs exports async function run(positional, flags, ctx). Today ctx is {stdout, stderr, env}. We extend ctx with verbose: boolean so handlers can branch on it without re-reading globalFlags.

3. Internal log emission pattern

Existing fatal errors call ctx.stderr.write(\[error] ...\n`). The verbose pattern matches: if (ctx.verbose) ctx.stderr.write(`[verbose] ...\n`). No log helper needed for this iteration — six call sites total. Refactoring into a verbose()` helper is reasonable but not required for the goal.

4. Test infrastructure

Tests live in tests/*.test.mjs using node:test. Existing tests run the CLI as a subprocess via child_process.execFile and assert on exit code + stdout. Two new tests are needed:

tests/cli-verbose-flag.test.mjs — assert login --verbose alice exits 0, stderr contains "[verbose]", stdout matches golden file.
tests/cli-no-verbose-stability.test.mjs — assert login alice stdout is byte-identical to tests/golden/login.stdout.

Citations

src/cli.mjs:12-58 — parser implementation
src/commands/login.mjs:8-42 — typical handler shape
tests/cli-help.test.mjs:14 — subprocess testing pattern
package.json:scripts.test — node --test tests/*.test.mjs

Brief anchoring

Brief task: "Add a --verbose flag to the small-auth CLI parser". This research answers the planner's first question: where to hook into. The parser is small and centralized, so the change is minimal-scope.

The brief's success criteria around byte-identical default stdout maps directly to the stability test in dimension 4.

3.3 KiB Raw Blame History