open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

docs(voyage): pin operator-UX contract — always emit file:// link + open command

Browse source 
Operator runs Ghostty (also iTerm2, modern Terminal.app) — all support
cmd+click on file:// URLs. Producing commands (/trekbrief, /trekplan,
/trekreview) already emit both forms but the contract was implicit.
This commit makes it explicit:

1. CLAUDE.md gains an "Operator-UX guarantee" paragraph stating both
   forms must always appear in the final report: (a) plain file://
   URL with absolute path (for cmd+click), (b) copy-pasteable
   `open file://` command (for terminals without cmd+click).

2. tests/lib/doc-consistency.test.mjs gains a pin asserting both
   patterns appear in all three producing commands' final report
   blocks. Drift catches at test time.

Non-functional change to the commands themselves — they already
emit both forms (verified at trekbrief.md L510/L519, trekplan.md
L798/L802, trekreview.md L299/L317).

Operator request 2026-05-13: "Noter ned i Voyage at jeg ALLTID får
en slik direkte file:// lenke."
This commit is contained in:
Kjell Tore Guttormsen 2026-05-13 20:31:58 +02:00
commit 8cbb33e1fd
2 changed files with 20 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

18
plugins/voyage/tests/lib/doc-consistency.test.mjs
View file

@ -485,6 +485,24 @@ test('producing commands tell the operator the flow is THEIR own annotations', (
}
});
test('producing commands emit file:// link in final report (operator-UX contract, 2026-05-13)', () => {
// Operator runs Ghostty / iTerm2 / modern Terminal.app — all support cmd+click
// on file:// URLs. Producing commands MUST emit both forms: (a) plain file://
// line in the report block, (b) `open file://...` copy-pasteable command.
// Both must reference $ANNOT_HTML (absolute path from scripts/annotate.mjs).
for (const f of ['trekbrief.md', 'trekplan.md', 'trekreview.md']) {
const text = read(`commands/${f}`);
assert.ok(
/file:\/\/\{\$ANNOT_HTML\}/.test(text),
`commands/${f} must include "file://{$ANNOT_HTML}" plain URL in the final report block`,
);
assert.ok(
/open file:\/\/\{\$ANNOT_HTML\}/.test(text),
`commands/${f} must include "open file://{$ANNOT_HTML}" copy-pasteable command in the final report block`,
);
}
});
test('package.json still has no "npm run render" script (removed in v5.0.1)', () => {
const pkg = JSON.parse(read('package.json'));
assert.equal(