ktg-plugin-marketplace/plugins/voyage/examples/02-real-cli/REGENERATED.md

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:

{
  "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

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.