feat(intent): /trekplan halts without an approved intent; the approval is stamped on both paths

Veikart steg 1, økt 1 av 2. The three holes measured in the grounds:
(1) ## Intent / ## Goal were only checked for existence, (2) no approval
marker existed, (3) brief-approved was emitted only on the auto path.

- lib/validators/intent-approval.mjs: --check / --stamp. The marker is
  intent_approved_hash (sha256 over normalized ## Intent + ## Goal) +
  intent_approved_at. Editing either section after approval → STALE.
- /trekplan Phase 1 (Read the brief, both --brief and --project): runs
  --check and HALTS on BRIEF_INTENT_NOT_APPROVED / _STALE / _INVALID with
  the remedy spelled out; an unrunnable check halts too.
- /trekbrief Phase 4h (before the Phase 5 fork, asked even in --quick):
  shows Intent + Goal verbatim, AskUserQuestion Approve / Revise / Leave;
  only "Approve" runs --stamp. --stamp emits brief-approved, so the manual
  (default) path records it; the auto path's own emission is removed.
  New mode /trekbrief --approve <project-dir> = Phase 4h alone.
- README, CLAUDE.md, command-modes, HANDOVER-CONTRACTS §Handover 1,
  jsonl-schemas (trekbrief-stats gains intent_approved).

Valgt ingen brief_version-bump fordi skjemaendringen er rent additiv (to
valgfrie felt) og kravet sitter i /trekplan — enhver produsents brief kan
godkjennes via /trekbrief --approve uten produsentendring. Valgt eget
--check-kall i stedet for et flagg på brief-validator fordi --brief-stien
i dag ikke kjører validatoren i det hele tatt; et nytt validatorkall der
ville også stoppe på andre feil. Valgt fallback-datamappe = målestokkens
(plugins/data/voyage-…) fordi CLAUDE_PLUGIN_DATA er tom i Bash-miljøet og
event-emits egen fallback er stille skip — slik ble brief-approved 0 records.

What the marker does NOT prove (module header, command prose, contract):
same user, same machine — any session can stamp. A trace, not a signature.

Suite 1183 → 1201 (1199/0/2). Mutants M1–M5 (stale check off, check
always valid, gate line removed, stamp emits nothing, no normalization)
each fell ≥ 1 test. yardstick unchanged: RED, 1 of 3 countable.

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

lib/parsers/arg-parser.mjs

@@ -7,7 +7,7 @@
 const FLAG_SCHEMA = {
   trekbrief: {
     boolean: ['--quick', '--fg'],
-    valued: ['--profile'],
+    valued: ['--profile', '--approve'],
     aliases: {},
   },
   trekresearch: {

lib/validators/intent-approval.mjs

@@ -0,0 +1,209 @@
+// lib/validators/intent-approval.mjs
+// Intent approval marker — the gate /trekplan passes before it plans anything.
+//
+// A brief carries two optional frontmatter fields once the operator has
+// approved its intent in /trekbrief (Phase 4h, or `/trekbrief --approve`):
+//
+//   intent_approved_hash: "sha256:<64 hex>"   hash over ## Intent + ## Goal
+//   intent_approved_at:   "<ISO-8601>"        when the stamp was written
+//
+// The hash binds the approval to the EXACT intent text: each section is
+// normalized (lines trimmed, whitespace runs collapsed, blank lines dropped)
+// and the pair is hashed. Reflowing a paragraph keeps the approval; changing
+// a word in ## Intent or ## Goal after approval makes it stale, and /trekplan
+// stops until the operator approves the new text.
+//
+// WHAT THE MARKER DOES NOT PROVE. Same user, same machine: any session with
+// write access to the brief can run `--stamp` itself, or write the two fields
+// by hand. The marker is a TRACE that the approval step ran against this text,
+// NOT a signature binding a person — the same limit as the order queue's
+// `--from`. It catches drift (intent edited after approval) and omission (no
+// approval step at all); it does not catch a session that approves on the
+// operator's behalf.
+//
+// trekreview briefs are exempt: they are produced from a review of an already
+// planned brief and carry no ## Intent of their own.
+//
+// CLI:
+//   node lib/validators/intent-approval.mjs --check [--json] <brief.md>
+//     exit 0 = approved and current; exit 1 = stop (errors); exit 2 = usage
+//   node lib/validators/intent-approval.mjs --stamp <brief.md>
+//     writes the marker and emits `brief-approved`; exit 0 stamped, 1 refused
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { parseDocument } from '../util/frontmatter.mjs';
+import { issue } from '../util/result.mjs';
+import { emit } from '../stats/event-emit.mjs';
+
+export const INTENT_HASH_FIELD = 'intent_approved_hash';
+export const INTENT_APPROVED_AT_FIELD = 'intent_approved_at';
+export const INTENT_SECTIONS = Object.freeze(['Intent', 'Goal']);
+const HASH_RE = /^sha256:[0-9a-f]{64}$/;
+const STATS_FILENAME = 'trekexecute-stats.jsonl'; // where event-emit writes lifecycle events
+
+const APPROVE_HINT = 'Run /trekbrief --approve <project-dir> — the operator reads ## Intent + ## Goal and answers "Approve".';
+
+function extractSection(body, heading) {
+  const re = new RegExp(`^##\\s+${heading}\\b.*$`, 'm');
+  const m = re.exec(body);
+  if (!m) return null;
+  const after = body.slice(m.index + m[0].length);
+  const next = after.search(/^##\s/m);
+  return next === -1 ? after : after.slice(0, next);
+}
+
+function normalize(text) {
+  return text.split(/\r?\n/)
+    .map((l) => l.trim().replace(/\s+/g, ' '))
+    .filter(Boolean)
+    .join('\n');
+}
+
+/**
+ * Hash ## Intent + ## Goal of a brief body.
+ * @returns {{ hash: string|null, missing: string[] }} hash is null when a section is absent or empty.
+ */
+export function computeIntentHash(body) {
+  const parts = [];
+  const missing = [];
+  for (const h of INTENT_SECTIONS) {
+    const s = extractSection(body || '', h);
+    const n = s === null ? '' : normalize(s);
+    if (!n) missing.push(h);
+    parts.push(n);
+  }
+  if (missing.length) return { hash: null, missing };
+  const hex = createHash('sha256').update(JSON.stringify(parts), 'utf8').digest('hex');
+  return { hash: `sha256:${hex}`, missing };
+}
+
+/** Check the approval marker of a brief's text. Returns a validator Result. */
+export function checkIntentApprovalContent(text) {
+  const doc = parseDocument(text);
+  if (!doc.valid) return doc;
+  const fm = doc.parsed.frontmatter || {};
+  const body = doc.parsed.body || '';
+  const errors = [];
+  const result = () => ({ valid: errors.length === 0, errors, warnings: [], parsed: { frontmatter: fm } });
+
+  if (fm.type === 'trekreview') return result();
+
+  if (!(INTENT_HASH_FIELD in fm)) {
+    errors.push(issue(
+      'BRIEF_INTENT_NOT_APPROVED',
+      'The brief\'s intent has not been approved — /trekplan does not plan against an unapproved intent.',
+      APPROVE_HINT,
+    ));
+    return result();
+  }
+  const recorded = String(fm[INTENT_HASH_FIELD]);
+  if (!HASH_RE.test(recorded)) {
+    errors.push(issue(
+      'BRIEF_INTENT_APPROVAL_INVALID',
+      `${INTENT_HASH_FIELD} "${recorded}" is not "sha256:<64 hex>" — the marker is malformed.`,
+      APPROVE_HINT,
+    ));
+    return result();
+  }
+  const { hash, missing } = computeIntentHash(body);
+  if (!hash) {
+    errors.push(issue(
+      'BRIEF_INTENT_APPROVAL_INVALID',
+      `The approval cannot bind: ## ${missing.join(' and ## ')} is missing or empty.`,
+      'Write the missing section(s), then ' + APPROVE_HINT,
+    ));
+    return result();
+  }
+  if (hash !== recorded) {
+    errors.push(issue(
+      'BRIEF_INTENT_APPROVAL_STALE',
+      '## Intent or ## Goal changed after the intent was approved — the approval covers the old text, not this one.',
+      APPROVE_HINT,
+    ));
+  }
+  return result();
+}
+
+/**
+ * Write the approval marker into a brief's frontmatter (replacing any prior one).
+ * @returns {{ stamped: boolean, text: string, hash?: string, approvedAt?: string, reason?: string }}
+ */
+export function stampIntentApproval(text, now = new Date()) {
+  const doc = parseDocument(text);
+  if (!doc.valid) return { stamped: false, text, reason: 'frontmatter does not parse' };
+  const { hash, missing } = computeIntentHash(doc.parsed.body || '');
+  if (!hash) return { stamped: false, text, reason: `## ${missing.join(' and ## ')} missing or empty` };
+  const m = /^(?---\r?\n)([\s\S]*?)(\r?\n---)/.exec(text);
+  if (!m) return { stamped: false, text, reason: 'no frontmatter block' };
+  const approvedAt = now.toISOString();
+  const kept = m[2].split(/\r?\n/).filter((l) =>
+    !l.startsWith(`${INTENT_HASH_FIELD}:`) && !l.startsWith(`${INTENT_APPROVED_AT_FIELD}:`));
+  kept.push(`${INTENT_HASH_FIELD}: "${hash}"`, `${INTENT_APPROVED_AT_FIELD}: "${approvedAt}"`);
+  const out = m[1] + kept.join('\n') + m[3] + text.slice(m.index + m[0].length);
+  return { stamped: true, text: out, hash, approvedAt };
+}
+
+/**
+ * Where the brief-approved record goes. CLAUDE_PLUGIN_DATA when the harness
+ * provides it; otherwise the plugin data dir the hooks write to and
+ * scripts/yardstick.mjs reads — the Bash tool env carries no CLAUDE_PLUGIN_DATA,
+ * and event-emit's own fallback is a silent skip, which is how brief-approved
+ * reached 0 records.
+ */
+export function resolveApprovalDataDir(env = process.env) {
+  if (env.CLAUDE_PLUGIN_DATA) return env.CLAUDE_PLUGIN_DATA;
+  const home = env.HOME && env.HOME.length > 0 ? env.HOME : homedir();
+  return join(home, '.claude', 'plugins', 'data', 'voyage-ktg-plugin-marketplace');
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  const file = args.find((a) => !a.startsWith('--'));
+  const mode = args.includes('--stamp') ? 'stamp' : args.includes('--check') ? 'check' : null;
+  if (!file || !mode) {
+    process.stderr.write('Usage: intent-approval.mjs --check [--json] <brief.md> | --stamp <brief.md>\n');
+    process.exit(2);
+  }
+  let text = null;
+  if (existsSync(file)) {
+    try { text = readFileSync(file, 'utf8'); } catch { text = null; }
+  }
+
+  if (mode === 'check') {
+    const r = text === null
+      ? { valid: false, errors: [issue('BRIEF_NOT_FOUND', `Cannot read brief: ${file}`)], warnings: [] }
+      : checkIntentApprovalContent(text);
+    if (args.includes('--json')) {
+      process.stdout.write(JSON.stringify({ valid: r.valid, errors: r.errors, warnings: r.warnings }, null, 2) + '\n');
+    } else {
+      process.stdout.write(`intent-approval: ${r.valid ? 'APPROVED' : 'STOP'} ${file}\n`);
+      for (const e of r.errors) process.stderr.write(`  ERROR  [${e.code}] ${e.message}\n         ${e.hint || ''}\n`);
+    }
+    process.exit(r.valid ? 0 : 1);
+  }
+
+  // --stamp
+  if (text === null) {
+    process.stdout.write(JSON.stringify({ stamped: false, reason: `cannot read ${file}` }) + '\n');
+    process.exit(1);
+  }
+  const s = stampIntentApproval(text);
+  if (!s.stamped) {
+    process.stdout.write(JSON.stringify({ stamped: false, reason: s.reason }) + '\n');
+    process.exit(1);
+  }
+  const tmp = join(dirname(file), `.${basename(file)}.approve.tmp`);
+  writeFileSync(tmp, s.text);
+  renameSync(tmp, file);
+  const fm = parseDocument(s.text).parsed.frontmatter || {};
+  const record = emit('brief-approved',
+    { project: dirname(file), slug: fm.slug ?? null, intent_hash: s.hash },
+    { path: join(resolveApprovalDataDir(), STATS_FILENAME) });
+  process.stdout.write(JSON.stringify({
+    stamped: true, intent_hash: s.hash, approved_at: s.approvedAt, record,
+  }) + '\n');
+  process.exit(0);
+}