open/voyage
1
0
Fork 0
Code Issues Releases 13 Activity

fix(docs): the order fields stand on all five surfaces (green)

Browse source 
/trekbrief Phase 7 says the writer adds order_id / order_claimed_at /
order_reason (never typed by the model) and that the yardstick joins use on
order_id; the fixture row lists them in `fields`, EXPORT_DENYLIST names them,
and its stale line_ref (657-672) now reads 961-976; the allowlist header
names them as dropped; docs/architecture.md Stats explains them.

/trekbrief --approve now runs Phase 7 after a successful stamp, with fixed
values (mode "approve", 0 turns, brief_quality/research_topics/auto_research
from the brief's frontmatter, auto_result "manual", intent_approved true).
Valgt fordi PM 04.10 (point 3): fix the code, not the criterion - the
approval must leave the trekbrief record. Measured hole: okf-wiki v1-k has
brief-approved 04.10 17:12Z and trekplan 17:29Z, but only a 03.10 trekbrief
record with intent_approved false. CLAUDE.md, README.md and
docs/command-modes.md say so. The manual path is unchanged.

npm test 1309 -> 1362 (1360 pass / 0 fail / 2 skip).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-10-04 19:55:17 +02:00
commit 3f073b7bd7
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
7 changed files with 32 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

2
CLAUDE.md
View file

@ -26,7 +26,7 @@ Voyage — a contract-driven Claude Code pipeline: brief, research, plan, execut
| Command | Description | Orchestrator model |
|---------|-------------|--------------------|
| `/trekbrief` | Brief — interactive interview produces a task brief with explicit research plan; ends with the operator approving `## Intent` + `## Goal` (`--approve <dir>` does only that); optionally orchestrates the pipeline | session |
| `/trekbrief` | Brief — interactive interview produces a task brief with explicit research plan; ends with the operator approving `## Intent` + `## Goal` (`--approve <dir>` does only that, then writes the trekbrief record); optionally orchestrates the pipeline | session |
| `/trekresearch` | Research — deep local + external research, produces structured research brief. Opt-in `--engine {swarm\|deep-research}` delegates the external phase to Claude Code's built-in `/deep-research` workflow (swarm default) | session |
| `/trekplan` | Plan — brief-reviewer, explore, plan, review. Requires `--brief` or `--project`; halts unless the brief's intent is approved (hash-bound, stale on edit). Auto-discovers `architecture/overview.md` if present | session |
| `/trekexecute` | Execute — disciplined plan/session-spec executor with failure recovery | session |

2
README.md
View file

@ -169,7 +169,7 @@ Output: `.claude/projects/{YYYY-MM-DD}-{slug}/brief.md`
| **Default** | `/trekbrief <task>` | Dynamic interview until quality gates pass. No question cap. |
| **Quick** | `/trekbrief --quick <task>` | Starts compact (optional sections get at most one probe), still escalates on weak required sections or failed review gate. |
| **Profile** | `/trekbrief --profile <name> <task>` | (v4.1.0) Pin model profile for the brief phase: `economy` / `balanced` / `premium` / `fable` / `<custom>`. See [Profile system](#profile-system-v410) below. |
| **Approve** | `/trekbrief --approve <project-dir \| brief-file>` | No interview: show an existing brief's `## Intent` + `## Goal` verbatim and ask the operator to approve them. The same step (Phase 4h) ends every normal `/trekbrief` run. |
| **Approve** | `/trekbrief --approve <project-dir \| brief-file>` | No interview: show an existing brief's `## Intent` + `## Goal` verbatim and ask the operator to approve them; on "Approve" it also writes the trekbrief stats record. The same step (Phase 4h) ends every normal `/trekbrief` run. |
`/trekbrief` is **always interactive**. There is no foreground/background mode — the interview requires user input.

24
commands/trekbrief.md
View file

@ -62,8 +62,9 @@ Parse `$ARGUMENTS`:
file resolves to itself, whatever its name (a `/trekplan --brief` brief).
On exit 1, print its `error` and stop. Otherwise set `BRIEF_PATH`,
`PROJECT_DIR` and `PLAN_COMMAND` from `brief_path`, `project_dir` and
`plan_command`, jump straight to **Phase 4h**, run it, print its report,
and stop. This is the remedy `/trekplan` names when it halts on an
`plan_command`, jump straight to **Phase 4h**, run it and print its
report; if the stamp printed `stamped: true`, run **Phase 7** with the
approve-mode values it names, then stop. This is the remedy `/trekplan` names when it halts on an
unapproved or stale intent, on both of its brief modes.
In every other mode, `BRIEF_PATH = {PROJECT_DIR}/brief.md` and
@ -89,7 +90,7 @@ Examples:
Report:
```
Mode: {default | quick}
Mode: {default | quick | approve}
Task: {task description}
```
@ -786,7 +787,8 @@ Report:
Intent: {approved (sha256:…12 hex) | left unapproved — /trekplan will halt}
```
In `--approve` mode, stop after the report and print the next step:
In `--approve` mode, run **Phase 7** (`"mode": "approve"`) when the stamp
printed `stamped: true`, then stop and print the next step:
`{PLAN_COMMAND}` (only if approved).
## Phase 5 — Auto-orchestration opt-in (if research_topics > 0)
@ -961,7 +963,7 @@ node ${CLAUDE_PLUGIN_ROOT}/lib/stats/stats-append.mjs trekbrief <<'JSON'
"ts": "{ISO-8601}",
"task": "{task description (first 100 chars)}",
"slug": "{slug}",
"mode": "{default | quick}",
"mode": "{default | quick | approve}",
"interview_turns": {N},
"review_iterations": {1..3},
"brief_quality": "{complete | partial}",
@ -978,6 +980,18 @@ JSON
answered "Approve"). `slug` is the brief's `slug`, the same one the stamp's
`brief-approved` record and `/trekplan`'s record carry.
In `--approve` mode the record carries fixed values: `"mode": "approve"`,
`"interview_turns": 0`, `"review_iterations": 0`, `brief_quality`,
`research_topics` and `auto_research` from the brief's frontmatter (`complete`,
`0`, `false` when absent), `"auto_result": "manual"`, `"intent_approved": true`.
The writer adds three keys itself: `order_id`, `order_claimed_at` and
`order_reason` - the coord-queue order this run is working on, read from the
queue's claimed orders (exactly one: its id and claim time; zero or several:
`order_id: null` and the reason). Never type them: any `order_*` key in the
record is replaced. `scripts/yardstick.mjs` joins its `use` number on
`order_id`.
The writer prints `{"written": true, ...}`. On `"written": false` (exit 1),
print its `reason` in one line and continue. A stats failure never blocks the
workflow, but it is reported, not skipped silently.

5
docs/architecture.md
View file

@ -134,6 +134,11 @@ written by `lib/stats/stats-append.mjs`, which falls back to
`~/.claude/plugins/data/voyage-ktg-plugin-marketplace/`, the directory
`scripts/yardstick.mjs` reads. A failed write is reported, not skipped.
The other commands' stats phases still name the variable in prose only.
A brief record also carries `order_id`, `order_claimed_at` and `order_reason`:
the coord-queue order the run is working on, added by the writer from the
queue's claimed orders (`lib/stats/claimed-order.mjs`), never by the model.
`scripts/yardstick.mjs` joins its `use` number on `order_id`; the three fields
are never exported.
## Terminology

2
docs/command-modes.md
View file

@ -10,7 +10,7 @@ Per-command flag tables, imported from `CLAUDE.md` via pointer.
| `--quick` | Compact start; still escalates if required sections are weak or the brief-review gate fails → brief.md with research plan |
| `--gates {true\|false}` | (v3.4.0) Boolean autonomy-gate flag; present → gating on. Policy (`gates_mode`) detailed under `## Autonomy mode` in `docs/operations.md`. |
| `--profile <name>` | (v4.1.0) Model profile: `economy` / `balanced` / `premium` / `fable` / `<custom>`. Sets `phase_models` for the brief phase. See `## Profile system` in `docs/operations.md`. |
| `--approve <project-dir \| brief-file>` | (veikart steg 1) No interview: show the existing brief's `## Intent` + `## Goal` verbatim, ask the operator to approve, and on "Approve" stamp `intent_approved_hash` + `intent_approved_at` and emit `brief-approved`. The remedy `/trekplan` names when it halts on `BRIEF_INTENT_NOT_APPROVED` / `BRIEF_INTENT_APPROVAL_STALE`. |
| `--approve <project-dir \| brief-file>` | (veikart steg 1) No interview: show the existing brief's `## Intent` + `## Goal` verbatim, ask the operator to approve, and on "Approve" stamp `intent_approved_hash` + `intent_approved_at`, emit `brief-approved`, and write the trekbrief stats record (`"mode": "approve"`). The remedy `/trekplan` names when it halts on `BRIEF_INTENT_NOT_APPROVED` / `BRIEF_INTENT_APPROVAL_STALE`. |
Always interactive. Phase 3 is a section-driven completeness loop (no hard cap on question count); Phase 4 runs a `brief-reviewer` stop-gate with max 3 review iterations. After writing the brief, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground).

2
lib/exporters/field-allowlist.mjs
View file

@ -10,6 +10,8 @@
// Per-schema allowlists drop:
// - command_excerpt (post-bash-stats: arbitrary Bash slice, CWE-212)
// - session_id (UUID, high-cardinality, log-only)
// - order_id / order_claimed_at / order_reason (trekbrief: coordination
// metadata - order ids name private repos; high-cardinality, never exported)
// - task / question / project_dir / brief_path / plan / project (PII-ish prose, paths)
// - payload (event-emit: open-ended object, allowlist payload-keys instead)
// - phase_models (structured object, summarize via `profile` label instead)

5
tests/fixtures/jsonl-schemas.md vendored
View file

@ -19,7 +19,7 @@
| schema_id | fields | writer_path | line_ref | v4.1 additive | PII |
|-----------|--------|-------------|----------|---------------|-----|
| trekbrief-stats | ts, task, slug, mode, interview_turns, review_iterations, brief_quality, research_topics, auto_research, auto_result, intent_approved, project_dir | commands/trekbrief.md (orchestrator-emit Phase 7) | trekbrief.md:657-672 | profile, phase_models, profile_source | none |
| trekbrief-stats | ts, task, slug, mode, interview_turns, review_iterations, brief_quality, research_topics, auto_research, auto_result, intent_approved, project_dir, order_id, order_claimed_at, order_reason | commands/trekbrief.md (orchestrator-emit Phase 7; order_* added by lib/stats/stats-append.mjs) | trekbrief.md:961-976 | profile, phase_models, profile_source | none |
| trekresearch-stats | ts, question, mode, scope, engine, slug, project_dir, brief_path, dimensions, dimensions_baseline, dimensions_baseline_preserved, effort, conv_turns, empty_turns, unique_sources, agents_local, agents_external, gemini_used, confidence, contradictions, open_questions | commands/trekresearch.md (orchestrator-emit Stats tracking) | trekresearch.md:634-676 | profile, phase_models, parallel_agents, external_research_enabled, profile_source | none |
| trekplan-stats | ts, task, mode, slug, brief_path, project_dir, codebase_size, codebase_files, agents_deployed, deep_dives, research_briefs_used, research_scout_used, critic_verdict, guardian_verdict, outcome | commands/trekplan.md (orchestrator-emit Phase 12) | trekplan.md:805-826 | profile, phase_models, parallel_agents, profile_source | none |
| trekexecute-stats (Phase 9 record) | ts, plan, plan_type, mode, result, steps_total, steps_passed, steps_failed, steps_skipped, failed_at_step | commands/trekexecute.md (orchestrator-emit Phase 9) | trekexecute.md:1479-1494 | profile, phase_models, profile_source | none |
@ -55,7 +55,8 @@ cost_usd, is_estimate, price_table_version
**EXPORT_DENYLIST** (PII or high-cardinality, never export):
```
task, question, project_dir, project, plan, brief_path, command_excerpt, payload, counts, phase_models, session_id
task, question, project_dir, project, plan, brief_path, command_excerpt, payload, counts, phase_models, session_id,
order_id, order_claimed_at, order_reason
```
> Notes: