feat(voyage)!: marketplace handoff — rename plugins/ultraplan-local to plugins/voyage [skip-docs]

Session 5 of voyage-rebrand (V6). Operator-authorized cross-plugin scope.

- git mv plugins/ultraplan-local plugins/voyage (rename detected, history preserved)
- .claude-plugin/marketplace.json: voyage entry replaces ultraplan-local
- CLAUDE.md: voyage row in plugin list, voyage in design-system consumer list
- README.md: bulk rename ultra*-local commands -> trek* commands; ultraplan-local refs -> voyage; type discriminators (type: trekbrief/trekreview); session-title pattern (voyage:<command>:<slug>); v4.0.0 release-note paragraph
- plugins/voyage/.claude-plugin/plugin.json: homepage/repository URLs point to monorepo voyage path
- plugins/voyage/verify.sh: drop URL whitelist exception (no longer needed)

Closes voyage-rebrand. bash plugins/voyage/verify.sh PASS 7/7. npm test 361/361.
This commit is contained in:
Kjell Tore Guttormsen 2026-05-05 15:37:52 +02:00
commit 7a90d348ad
149 changed files with 26 additions and 33 deletions

View file

@ -0,0 +1,224 @@
# REGENERATED.md — examples/02-real-cli
| Field | Value |
|-------|-------|
| Calibrated against | trekplan v3.4.1 |
| Last regenerated | 2026-05-04 (B3 session) |
| Source brief author | Hand-authored by operator (B1 session, 2026-05-04) |
| Baseline author | B2 session, 2026-05-04 (commit `c8146c1`) |
| Pipeline run | B3 session, 2026-05-04 (commits `c4cf49f``da68c2f`) |
## What this example demonstrates
`examples/02-real-cli/` is the first **runnable** trekplan example.
Unlike `examples/01-add-verbose-flag/` (which ships a frozen brief, plan,
and research as artifacts but no executable code), this example ships a
working ~80-line Node.js CLI (`tally`), a passing test suite, and known
fixture data — all designed to be the input for a real pipeline run.
The fixture's purpose is twofold:
1. **End-to-end pipeline validation:** running `/trekresearch`,
`/trekplan`, and `/trekexecute` against `brief.md` must
produce green commits that satisfy all 10 brief Success Criteria. This
is the controlled environment used to verify pipeline correctness on
release-validation passes (see "Regeneration triggers" below).
2. **Cache-prefix measurement target (Spor C, planned):** the next track
in the post-v3.4.0 roadmap will use this fixture under
`CLAUDE_CODE_FORK_SUBAGENT` to measure cache-prefix preservation
semantics. The fixture is small enough to fit comfortably under the
150-250K context window where Path C measurements need to happen.
The brief deliberately picks a small, well-scoped feature (single boolean
flag with regex semantics) so the pipeline output is predictable and
testable, while still exercising the full plan/execute machinery
(manifest YAML, plan-critic, scope-guardian, per-step verify, progress.json).
## Baseline (delivered by B2, 2026-05-04, commit `c8146c1`)
`tally` — an 80-line zero-dep Node.js CLI that counts literal-substring
occurrences of a pattern in a text file. Three flags (`--json`,
`-i`/`--ignore-case`, `--lines`), `--help`, exit codes 0/1/2.
Layout:
```
examples/02-real-cli/
├── tally.mjs # CLI (80 lines, hand-rolled argv parser)
├── tests/tally.test.mjs # 10 node:test cases (all pass ~2.2s)
├── fixtures/
│ ├── sample.txt # 9 lines, known counts (foo×7, Foo×1, /fo+/g×9, .×4)
│ ├── poem.txt # 5 lines, "foo" --lines = 3, total = 4
└── REGENERATED.md # this file
```
Baseline preconditions verified by B2:
- `grep -c 'foo' fixtures/sample.txt` returns 4 lines containing `foo`
(literal `foo` count = 7 across those lines).
- regex `/fo+/g` matchAll on `sample.txt` = 9 (greater than literal `foo`
count, as required by brief SC #1).
- `--lines foo poem.txt` = 3, total `foo` in `poem.txt` = 4 (exercises
`--lines` distinction in baseline tests).
## Pipeline run (delivered by B3, 2026-05-04)
The pipeline ran against `brief.md` (research_topics: 0, hand-authored).
Each phase produced an artifact in
`.claude/projects/2026-05-04-examples-02-real-cli/`.
### `/trekresearch`
**Outcome: skipped (intentionally).**
Brief declares `research_topics: 0` and `research_status: complete`.
The brief's "Research Plan" section is explicit:
> No external research needed — this is a pure Node.js stdlib + `node:test`
> task, the codebase fixture is self-contained, and the regex semantics
> needed (`new RegExp(p)` + `String.prototype.matchAll`) are well-documented
> MDN material.
Following the prompt's guidance ("Ikke kjør Gemini-bridge eller
community-researcher for trivielle Node-stdlib-spørsmål"), the swarm was
not invoked. No research file was written; `research/` directory does not
exist for this project. Downstream commands (`/trekplan`) auto-discover
research files but do not require them — the missing directory is fine
per the soft-mode `research-validator` contract.
### `/trekplan`
**Outcome: plan.md with 4 steps; plan-validator strict PASS;
plan-critic 0 BLOCKER (4 MAJOR fixed in revision); scope-guardian
PASS — ALIGNED.**
`plan.md` headers:
```
# Add `--regex`/`-r` mode to the `tally` CLI fixture
plan_version: 1.7
## Context
## Codebase Analysis
## Research Sources
## Implementation Plan
### Step 1: Add `--regex`/`-r` parsing and `compileRegex` helper
### Step 2: Wire regex counting path in `main()`
### Step 3: Update `--help` text to document `--regex`/`-r`
### Step 4: Add 4 new tests covering the regex path
## Verification
## Plan-critic notes
## Scope-guardian notes
## Execution Strategy
```
Adversarial-review summary:
| Reviewer | Verdict | Findings |
|----------|---------|----------|
| `plan-critic` | REVISE → re-run after fixes | 0 BLOCKER, 4 MAJOR (non-assertive verify in step 1; unchained verify in step 2; SC #9 final-block mismatch; `compileRegex` 'g' flag rationale missing). All 4 fixed. |
| `scope-guardian` | PASS — ALIGNED | 0 creep, 0 material gaps. Every brief SC and Non-Goal mapped to a step or manifest constraint. |
Manifest YAML on every step uses `forbidden_paths: examples/02-real-cli/package.json`
to enforce the brief's "no package.json" Non-Goal. `must_contain` patterns
require named symbols (`flags.regex`, `compileRegex`, `--regex 'fo+'`,
`-r short form`, `invalid regex`) so the verifier confirms substantive
changes, not just file modifications.
### `/trekexecute`
**Outcome: 4 commits, all green, all `verify_passed: true`.**
`progress.json` summary:
```json
{
"schema_version": "1",
"plan_version": "1.7",
"mode": "single-session",
"status": "completed",
"total_steps": 4,
"current_step": 4
}
```
Step-by-step:
| Step | Commit | Title | Verify |
|------|--------|-------|--------|
| 1 | `c4cf49f` | feat(tally): parse --regex/-r flag and add compileRegex helper | flag parsed, literal count = 7 |
| 2 | `44d7f33` | feat(tally): wire regex counting path in main with invalid-regex exit-2 | OK1, OK2, OK3, OK4 (4 chained assertions) |
| 3 | `c6ff4fa` | docs(tally): document --regex / -r in --help text | `--help \| grep -c -- "--regex"` = 1 |
| 4 | `da68c2f` | test(tally): add 4 tests for --regex/-r path covering SC #1, #2, #4, #5 | tests 14, pass 14, fail 0, duration_ms 3162.74 |
Constraint compliance:
- `tally.mjs`: 93 lines (under 100-line cap, +13 from 80-line baseline)
- `tests/tally.test.mjs`: 14 tests (exactly at 14-test cap, +4 from 10-test baseline)
- Test wall-clock: 3.16 s (under 5 s cap)
- `package.json`: not created (Non-Goal enforced)
- Files outside `examples/02-real-cli/`: zero
- Hook safety: zero shutdown/halt/reboot/poweroff/mkfs words in commit
bodies or verify commands
### Success Criteria status (10/10 PASS)
| SC | Verifier | Result |
|----|----------|--------|
| #1 | flag in 3 positions, all exit 0, same count | PASS (all = 9) |
| #2 | `-r 'fo+' sample.txt` == long form | PASS (both = 9) |
| #3 | `tally '.' sample.txt` (= 4) << `tally --regex '.' sample.txt` (= 209) | PASS |
| #4 | `tally --regex '[' sample.txt` exits 2, stderr `^tally: invalid regex` | PASS |
| #5 | `--json --regex 'fo+'` includes `flags.regex: true` | PASS |
| #6 | `tally 'foo' sample.txt` = 7 (= B2 baseline) | PASS |
| #7 | tests ≥ 12, ≥ 2 names contain `--regex` or `-r` | PASS (14 tests, 4 named) |
| #8 | `tally --help` contains `--regex` line | PASS |
| #9 | `REGENERATED.md` walk-through filled in | PASS (this file) |
| #10 | no `package.json` created | PASS |
## How to re-run this example
```bash
cd /path/to/trekplan
# 1. Re-run the pipeline against the existing brief
# (research is skipped — research_topics: 0)
/trekplan --project .claude/projects/2026-05-04-examples-02-real-cli
/trekexecute --project .claude/projects/2026-05-04-examples-02-real-cli
# 2. Verify all 10 Success Criteria from brief.md hold (commands above)
node --test examples/02-real-cli/tests/tally.test.mjs # 14 pass
# 3. Smoke-test individual SC commands:
node examples/02-real-cli/tally.mjs --regex 'fo+' examples/02-real-cli/fixtures/sample.txt
# expected: 9
node examples/02-real-cli/tally.mjs -r 'fo+' examples/02-real-cli/fixtures/sample.txt
# expected: 9
node examples/02-real-cli/tally.mjs --json --regex 'fo+' examples/02-real-cli/fixtures/sample.txt | python3 -m json.tool
# expected: {"pattern": "fo+", "count": 9, "flags": {..., "regex": true}}
node examples/02-real-cli/tally.mjs --help | grep -- "--regex"
# expected: " -r, --regex Interpret <pattern> as a JavaScript regular expression"
```
If any of those expected values changes, the pipeline output has drifted
and `examples/02-real-cli/` should be re-baselined (see "Regeneration
triggers" below).
## Regeneration triggers
When to re-run this example:
- trekplan minor version bump (e.g. v3.4 → v3.5)
- `plan_version` schema bump
- Manifest YAML required-key additions
- `progress.json` schema bump
- Pipeline-output format change (brief / research / plan / progress)
When regenerating: re-run the pipeline against the existing `brief.md` and
update this file plus the `examples/02-real-cli/` artifacts. The
"baseline" portion of the fixture (`tally.mjs` minus the regex feature,
the fixture text files, and the original 10 baseline tests) stays stable
across regenerations — only the pipeline outputs and any drift in the
extended `tally.mjs` change. If you want a clean re-run, reset to commit
`c8146c1` (B2 baseline) before invoking the pipeline.

View file

@ -0,0 +1,5 @@
foo on this line
nothing here
foo and foo here
silence
foo

View file

@ -0,0 +1,9 @@
Foo bar baz
The quick brown fox jumps over the foo
foo foo bar foo
food for thought.
fooo, fooooo, very loud
This line has no match here.
A line without the magic word
And another one without it
The end. Final period.

View file

@ -0,0 +1,93 @@
#!/usr/bin/env node
import { readFileSync } from 'node:fs';
const HELP = `Usage: tally [options] <pattern> <file>
Count literal-substring occurrences of <pattern> in <file>.
Options:
-i, --ignore-case Case-insensitive matching
--lines Count lines containing pattern (not total occurrences)
-r, --regex Interpret <pattern> as a JavaScript regular expression
--json Emit a JSON object on stdout
-h, --help Show this help and exit
Exit codes: 0=success 1=file error 2=invalid argv
`;
function fail(msg, code = 2) {
process.stderr.write(`tally: ${msg}\n`);
process.exit(code);
}
function parseArgs(argv) {
const positional = [];
const flags = { json: false, ignoreCase: false, lines: false, regex: false };
for (const a of argv) {
if (a === '--json') flags.json = true;
else if (a === '-i' || a === '--ignore-case') flags.ignoreCase = true;
else if (a === '--lines') flags.lines = true;
else if (a === '--regex' || a === '-r') flags.regex = true;
else if (a === '-h' || a === '--help') { process.stdout.write(HELP); process.exit(0); }
else if (a.startsWith('-')) fail(`unknown flag: ${a}`);
else positional.push(a);
}
if (positional.length !== 2) fail('expected <pattern> <file>');
return { pattern: positional[0], file: positional[1], flags };
}
function compileRegex(pattern) {
try { return new RegExp(pattern, 'g'); }
catch (e) { fail(`invalid regex: ${e.message}`); }
}
function countOccurrences(text, pattern, ignoreCase) {
if (pattern.length === 0) return 0;
const haystack = ignoreCase ? text.toLowerCase() : text;
const needle = ignoreCase ? pattern.toLowerCase() : pattern;
let count = 0, idx = 0;
while ((idx = haystack.indexOf(needle, idx)) !== -1) { count++; idx += needle.length; }
return count;
}
function countLines(text, pattern, ignoreCase) {
if (pattern.length === 0) return 0;
const needle = ignoreCase ? pattern.toLowerCase() : pattern;
let count = 0;
for (const line of text.split('\n')) {
const haystack = ignoreCase ? line.toLowerCase() : line;
if (haystack.includes(needle)) count++;
}
return count;
}
function main() {
const { pattern, file, flags } = parseArgs(process.argv.slice(2));
let text;
try {
text = readFileSync(file, 'utf8');
} catch (err) {
const what = err.code === 'ENOENT' ? 'file not found' : 'read error';
process.stderr.write(`tally: ${what}: ${file}\n`);
process.exit(1);
}
let count;
if (flags.regex) {
const re = compileRegex(pattern);
count = (text.match(re) || []).length;
} else if (flags.lines) {
count = countLines(text, pattern, flags.ignoreCase);
} else {
count = countOccurrences(text, pattern, flags.ignoreCase);
}
if (flags.json) {
process.stdout.write(JSON.stringify({
pattern, file, count,
flags: { json: flags.json, ignoreCase: flags.ignoreCase, lines: flags.lines, regex: flags.regex },
}) + '\n');
} else {
process.stdout.write(count + '\n');
}
}
main();

View file

@ -0,0 +1,127 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { dirname, resolve } from 'node:path';
const here = dirname(fileURLToPath(import.meta.url));
const TALLY = resolve(here, '..', 'tally.mjs');
const SAMPLE = resolve(here, '..', 'fixtures', 'sample.txt');
const POEM = resolve(here, '..', 'fixtures', 'poem.txt');
function run(...args) {
return spawnSync('node', [TALLY, ...args], { encoding: 'utf8' });
}
test('plain count: tally foo sample.txt prints 7', () => {
const r = run('foo', SAMPLE);
assert.equal(r.status, 0);
assert.equal(r.stdout.trim(), '7');
assert.equal(r.stderr, '');
});
test('JSON output: tally --json foo sample.txt parses with count 7', () => {
const r = run('--json', 'foo', SAMPLE);
assert.equal(r.status, 0);
const parsed = JSON.parse(r.stdout);
assert.equal(parsed.count, 7);
assert.equal(parsed.pattern, 'foo');
assert.equal(parsed.flags.json, true);
assert.equal(parsed.flags.ignoreCase, false);
assert.equal(parsed.flags.lines, false);
});
test('case-sensitive default: tally Foo sample.txt prints 1', () => {
const r = run('Foo', SAMPLE);
assert.equal(r.status, 0);
assert.equal(r.stdout.trim(), '1');
});
test('case-insensitive: tally -i Foo == tally -i foo (and exceeds case-sensitive)', () => {
const ri1 = run('-i', 'Foo', SAMPLE);
const ri2 = run('-i', 'foo', SAMPLE);
const rcs = run('foo', SAMPLE);
assert.equal(ri1.status, 0);
assert.equal(ri2.status, 0);
assert.equal(ri1.stdout, ri2.stdout);
assert.ok(Number(ri1.stdout) > Number(rcs.stdout));
});
test('--lines mode: tally --lines foo poem.txt prints 3 (not total occurrences 4)', () => {
const lines = run('--lines', 'foo', POEM);
const total = run('foo', POEM);
assert.equal(lines.status, 0);
assert.equal(total.status, 0);
assert.equal(lines.stdout.trim(), '3');
assert.equal(total.stdout.trim(), '4');
});
test('flag in last position: tally foo sample.txt --json equals tally --json foo sample.txt', () => {
const last = run('foo', SAMPLE, '--json');
const first = run('--json', 'foo', SAMPLE);
assert.equal(last.status, 0);
assert.equal(first.status, 0);
assert.equal(last.stdout, first.stdout);
});
test('missing argument: tally foo exits 2 with stderr', () => {
const r = run('foo');
assert.equal(r.status, 2);
assert.match(r.stderr, /^tally: /);
assert.equal(r.stdout, '');
});
test('unknown flag: tally --unknown foo sample.txt exits 2 with stderr', () => {
const r = run('--unknown', 'foo', SAMPLE);
assert.equal(r.status, 2);
assert.match(r.stderr, /^tally: /);
assert.equal(r.stdout, '');
});
test('file not found: tally foo /does/not/exist exits 1 with stderr', () => {
const r = run('foo', '/does/not/exist');
assert.equal(r.status, 1);
assert.match(r.stderr, /^tally: /);
assert.equal(r.stdout, '');
});
test('--help: stdout contains "Usage:", exit 0', () => {
const r = run('--help');
assert.equal(r.status, 0);
assert.match(r.stdout, /Usage:/);
assert.match(r.stdout, /--ignore-case/);
});
// --- Tests for --regex / -r mode (added in plan step 4, Spor B B3) ---
test("--regex 'fo+' counts more matches than literal 'foo' (long form, exit 0)", () => {
const literal = run('foo', SAMPLE);
const regex = run('--regex', 'fo+', SAMPLE);
assert.equal(literal.status, 0);
assert.equal(regex.status, 0);
assert.ok(Number(regex.stdout) >= Number(literal.stdout),
`regex count (${regex.stdout.trim()}) should be >= literal count (${literal.stdout.trim()})`);
});
test("-r short form equals --regex long form (same stdout)", () => {
const short = run('-r', 'fo+', SAMPLE);
const long = run('--regex', 'fo+', SAMPLE);
assert.equal(short.status, 0);
assert.equal(long.status, 0);
assert.equal(short.stdout, long.stdout);
});
test("--regex '[' exits 2 with stderr 'tally: invalid regex'", () => {
const r = run('--regex', '[', SAMPLE);
assert.equal(r.status, 2);
assert.equal(r.stdout, '');
assert.match(r.stderr, /^tally: invalid regex/);
});
test("--json --regex 'fo+' includes flags.regex === true in output", () => {
const r = run('--json', '--regex', 'fo+', SAMPLE);
assert.equal(r.status, 0);
const parsed = JSON.parse(r.stdout);
assert.equal(parsed.flags.regex, true);
assert.ok(typeof parsed.count === 'number' && parsed.count > 0);
});