fix(stats): M6 — trekbrief and trekplan records land where the yardstick reads

New lib/stats/stats-append.mjs: one record on stdin, appended to
<data dir>/<kind>-stats.jsonl. The data dir is CLAUDE_PLUGIN_DATA, else
~/.claude/plugins/data/voyage-ktg-plugin-marketplace (the yardstick's
default). A failed write exits 1 with a reason: reported, never silent.
/trekbrief Phase 7 and /trekplan Phase 12 now run it instead of
"append to ${CLAUDE_PLUGIN_DATA}/…; skip silently". intent-approval's
resolveApprovalDataDir delegates to the same resolver.

Chose a stdin heredoc over a --json argument because a JSON record in a
shell argument breaks on quotes in task text. Only trekbrief and trekplan
are rewired (økt 2's countable form needs exactly those two); the other
commands' stats prose is unchanged and docs/architecture.md says so.

Red a358059 7/7 → green 7/7. Suite 1208: 1206 pass / 0 fail / 2 skip.

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

commands/trekbrief.md

@@ -942,9 +942,13 @@ Or:
 
 ## Phase 7 — Stats tracking
 
-Append one record to `${CLAUDE_PLUGIN_DATA}/trekbrief-stats.jsonl`:
+Append one record to `trekbrief-stats.jsonl` in the plugin data directory.
+Run it exactly like this. The record goes on stdin, and the writer resolves
+the directory: `CLAUDE_PLUGIN_DATA`, which the Bash tool env does not carry,
+else the directory `scripts/yardstick.mjs` reads.
 
-```json
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/lib/stats/stats-append.mjs trekbrief <<'JSON'
 {
   "ts": "{ISO-8601}",
   "task": "{task description (first 100 chars)}",
@@ -959,13 +963,16 @@ Append one record to `${CLAUDE_PLUGIN_DATA}/trekbrief-stats.jsonl`:
   "intent_approved": {true | false},
   "project_dir": "{path}"
 }
+JSON
 ```
 
 `intent_approved` is `true` only when Phase 4h ran the stamp (the operator
-answered "Approve").
+answered "Approve"). `slug` is the brief's `slug`, the same one the stamp's
+`brief-approved` record and `/trekplan`'s record carry.
 
-If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip silently.
+The writer prints `{"written": true, ...}`. On `"written": false` (exit 1),
-Never let stats failures block the workflow.
+print its `reason` in one line and continue. A stats failure never blocks the
+workflow, but it is reported, not skipped silently.
 
 ## Profile (v4.1)
 

commands/trekplan.md

@@ -840,17 +840,19 @@ multi-session waves.
 
 ## Phase 12 — Session tracking
 
-After the plan is presented (Phase 10) or after handoff (Phase 11), write a
+After the plan is presented (Phase 10) or after handoff (Phase 11), append a
-session record to `${CLAUDE_PLUGIN_DATA}/trekplan-stats.jsonl` (create the file
+session record to `trekplan-stats.jsonl` in the plugin data directory. Run it
-if it does not exist).
+exactly like this. The record goes on stdin, and the writer resolves the
+directory: `CLAUDE_PLUGIN_DATA`, which the Bash tool env does not carry, else
+the directory `scripts/yardstick.mjs` reads.
 
-Record format (one JSON line):
+```bash
-```json
+node ${CLAUDE_PLUGIN_ROOT}/lib/stats/stats-append.mjs trekplan <<'JSON'
 {
   "ts": "{ISO-8601 timestamp}",
   "task": "{task description (first 100 chars)}",
   "mode": "{default|fg|quick}",
-  "slug": "{plan slug}",
+  "slug": "{the brief's slug}",
   "brief_path": "{brief_path}",
   "project_dir": "{project_dir or null}",
   "codebase_size": "{small|medium|large}",
@@ -863,10 +865,14 @@ Record format (one JSON line):
   "guardian_verdict": "{ALIGNED|CREEP|GAP|MIXED}",
   "outcome": "{execute|execute_team|save|refine}"
 }
+JSON
 ```
 
-If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip tracking silently.
+`slug` is the brief's `slug`, so this record pairs with the brief's
-Never let tracking failures block the main workflow.
+`brief-approved` and `trekbrief` records. The writer prints
+`{"written": true, ...}`. On `"written": false` (exit 1), print its `reason` in
+one line and continue. A tracking failure never blocks the main workflow, but
+it is reported, not skipped silently.
 
 ## Profile (v4.1)
 

docs/architecture.md

@@ -129,6 +129,12 @@ Stats:
 - Research stats: `${CLAUDE_PLUGIN_DATA}/trekresearch-stats.jsonl`
 - Continue stats: `${CLAUDE_PLUGIN_DATA}/trekcontinue-stats.jsonl`
 
+The Bash tool env carries no `CLAUDE_PLUGIN_DATA`. Brief and plan stats are
+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.
+
 ## Terminology
 
 - **Task brief** — produced by `/trekbrief`. Declares intent, goal, and research plan. Drives planning.

lib/stats/stats-append.mjs

@@ -0,0 +1,70 @@
+// lib/stats/stats-append.mjs
+// Append one command-stats record to <data dir>/<kind>-stats.jsonl.
+//
+// Why this exists: the commands' stats phases said "append to
+// ${CLAUDE_PLUGIN_DATA}/<kind>-stats.jsonl; if it is not set, skip silently".
+// The Bash tool's env carries no CLAUDE_PLUGIN_DATA, so the record was skipped
+// whenever the model did not guess the directory itself — the same silent skip
+// that left brief-approved at 0 records. This writer resolves the directory
+// the way scripts/yardstick.mjs reads it, and a failed write is REPORTED
+// (exit 1 + reason), never swallowed. Stats still never block the workflow:
+// the command prose reports the failure and carries on.
+//
+// CLI (the record is read from stdin, so no shell quoting of JSON):
+//   node lib/stats/stats-append.mjs <kind> <<'JSON'
+//   { ...record... }
+//   JSON
+//   → prints {"written":true,"path":...} exit 0 | {"written":false,"reason":...} exit 1
+
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const STATS_KINDS = Object.freeze([
+  'trekbrief', 'trekresearch', 'trekplan', 'trekexecute', 'trekreview', 'trekcontinue',
+]);
+
+/**
+ * The plugin data directory: CLAUDE_PLUGIN_DATA when the harness provides it,
+ * otherwise the directory the hooks write to and scripts/yardstick.mjs reads.
+ */
+export function resolveStatsDir(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');
+}
+
+/**
+ * @returns {{ written: boolean, path: string|null, reason?: string }}
+ */
+export function appendStatsRecord(kind, record, env = process.env) {
+  if (!STATS_KINDS.includes(kind)) {
+    return { written: false, path: null, reason: `unknown kind "${kind}" (one of ${STATS_KINDS.join(', ')})` };
+  }
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    return { written: false, path: null, reason: 'record must be a JSON object' };
+  }
+  const dir = resolveStatsDir(env);
+  const path = join(dir, `${kind}-stats.jsonl`);
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(path, JSON.stringify(record) + '\n');
+  } catch (e) {
+    return { written: false, path, reason: `${e.code || 'write-failed'}: ${e.message}` };
+  }
+  return { written: true, path };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const kind = process.argv[2];
+  let record = null;
+  let reason = null;
+  try {
+    record = JSON.parse(readFileSync(0, 'utf8'));
+  } catch (e) {
+    reason = `stdin is not JSON: ${e.message}`;
+  }
+  const r = reason ? { written: false, path: null, reason } : appendStatsRecord(kind, record);
+  process.stdout.write(JSON.stringify(r) + '\n');
+  process.exit(r.written ? 0 : 1);
+}

lib/validators/intent-approval.mjs

@@ -32,11 +32,11 @@
 
 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';
+import { resolveStatsDir } from '../stats/stats-append.mjs';
 
 export const INTENT_HASH_FIELD = 'intent_approved_hash';
 export const INTENT_APPROVED_AT_FIELD = 'intent_approved_at';
@@ -151,12 +151,10 @@ export function stampIntentApproval(text, now = new Date()) {
  * 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.
+ * reached 0 records. One resolver for every stats writer: lib/stats/stats-append.mjs.
  */
 export function resolveApprovalDataDir(env = process.env) {
-  if (env.CLAUDE_PLUGIN_DATA) return env.CLAUDE_PLUGIN_DATA;
+  return resolveStatsDir(env);
-  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]}`) {