@marcomigozzi/trailhead 0.14.0 → 0.16.0

package/plugins/trailhead/hooks/lib/report-status.test.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-report-status.js. Run: node report-status.test.js
+// No framework: plain asserts, same style as work-state.test.js.
+//
+// Layers covered:
+//   1. checkReport() as a table, for the review techniques (#250).
+//   2. The same for the field families: executor, fix, plan, debug, research,
+//      codebase-map (#249): fields, body, the fields problem.
+//   3. The vocabulary equals the tokens the technique files define, and the field
+//      contracts equal what scripts/agent-blocks.md states.
+//   4. The CLI: --file, stdin, one JSON line, exit codes.
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-report-status.js');
+const { checkReport, TOKENS, CONTRACTS, FAMILY_OF } = require(scriptPath);
+const techDir = path.resolve(__dirname, '..', '..', 'skills', '_shared', 'techniques');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const K = 'critical: 0 · warning: 1 · info: 2'; // the counts line
+const V = 'verify';
+const C = 'code-review';
+const KEYS = ['action', 'verdict', 'problem', 'report', 'fields', 'body'];
+
+// [name, technique, input, expected]; expected = [action, verdict, problem] and,
+// for a normalise row, the exact normalised report as a fourth element.
+const rows = [
+  // --- accept ---
+  ['verify met, exact', V, 'status: met\nbody\n', ['accept', 'met', null]],
+  ['verify gaps_found, exact', V, 'status: gaps_found\n- claim 2 unmet\n', ['accept', 'gaps_found', null]],
+  ['verify inconclusive, exact', V, 'status: inconclusive\nreason: unrunnable-check\n', ['accept', 'inconclusive', null]],
+  ['verify status only, no newline', V, 'status: met', ['accept', 'met', null]],
+  ['verify ignores a counts-looking line', V, `status: met\n${K}\nbody`, ['accept', 'met', null]],
+  ['verify does not need a counts line', V, 'status: met\nbody', ['accept', 'met', null]],
+  ['code-review clean with counts on line 2', C, `status: clean\n${K}\nledger\n`, ['accept', 'clean', null]],
+  ['code-review issues_found with counts on line 2', C, `status: issues_found\n${K}\nC1 open\n`, ['accept', 'issues_found', null]],
+
+  // --- normalise: the same single token in another layout ---
+  ['status on line 3 with bold decoration and upper case token', V, 'Intro\n\n**Status:** GAPS_FOUND\nbody',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\nIntro\n\nbody']],
+  ['heading decoration', V, '## Status: met\nbody', ['normalise', 'met', null, 'status: met\nbody']],
+  ['list bullet', V, '- status: met\nbody', ['normalise', 'met', null, 'status: met\nbody']],
+  ['star bullet and bold', V, '* **status**: met\nbody', ['normalise', 'met', null, 'status: met\nbody']],
+  ['backtick decoration', V, '`status: met`\nbody', ['normalise', 'met', null, 'status: met\nbody']],
+  ['underscore decoration', V, '__status__: met\nbody', ['normalise', 'met', null, 'status: met\nbody']],
+  ['capitalised label and token', V, 'Status: Met\nbody', ['normalise', 'met', null, 'status: met\nbody']],
+  ['hyphen for underscore', V, 'status: gaps-found\nbody', ['normalise', 'gaps_found', null, 'status: gaps_found\nbody']],
+  ['space for underscore', C, `status: issues found\n${K}\nbody`, ['normalise', 'issues_found', null, `status: issues_found\n${K}\nbody`]],
+  ['space before the colon', V, 'status : met\nbody', ['normalise', 'met', null, 'status: met\nbody']],
+  ['two-space indent', V, '  status: met\nbody', ['normalise', 'met', null, 'status: met\nbody']],
+  ['trailing spaces', V, 'status: met   \nbody', ['normalise', 'met', null, 'status: met\nbody']],
+  ['leading blank lines', V, '\n\nstatus: met\nbody', ['normalise', 'met', null, 'status: met\nbody']],
+  ['a blank line after the status line is kept', V, 'Status: Met\n\nbody', ['normalise', 'met', null, 'status: met\n\nbody']],
+  ['CRLF line endings', V, 'status: met\r\nbody\r\n', ['normalise', 'met', null, 'status: met\nbody\n']],
+  ['lone trailing CR is a line ending', V, 'status: met\r', ['normalise', 'met', null, 'status: met\n']],
+  ['BOM before an exact status line', V, 'status: met\nbody', ['normalise', 'met', null, 'status: met\nbody']],
+  ['BOM + exact status: clean + counts on line 2', C, `status: clean\n${K}\nbody`, ['normalise', 'clean', null, `status: clean\n${K}\nbody`]],
+  ['status not first', V, 'intro\nstatus: met', ['normalise', 'met', null, 'status: met\nintro']],
+  ['repeated same token keeps one at line 1', V, 'status: met\nbody\nstatus: met', ['normalise', 'met', null, 'status: met\nbody']],
+  ['repeated same token in different case', V, 'status: met\nbody\nStatus: MET\ntail', ['normalise', 'met', null, 'status: met\nbody\ntail']],
+  ['status inside a code fence is ignored', V, 'x\n```\nstatus: PASS\n```\nstatus: met',
+    ['normalise', 'met', null, 'status: met\nx\n```\nstatus: PASS\n```']],
+  ['status inside a tilde fence is ignored', V, '~~~\nstatus: gaps_found\n~~~\nstatus: met',
+    ['normalise', 'met', null, 'status: met\n~~~\nstatus: gaps_found\n~~~']],
+  ['blockquote status is ignored, real one wins', V, '> status: gaps_found\nstatus: met',
+    ['normalise', 'met', null, 'status: met\n> status: gaps_found']],
+  ['indented status is ignored, unindented valid one wins', V, '    status: PASS\nstatus: met',
+    ['normalise', 'met', null, 'status: met\n    status: PASS']],
+  ['tab-indented status is ignored, unindented valid one wins', V, '\tstatus: PASS\nstatus: met',
+    ['normalise', 'met', null, 'status: met\n\tstatus: PASS']],
+  ['code-review heading between status and counts', C, `status: clean\n## Findings\n${K}\nbody`,
+    ['normalise', 'clean', null, `status: clean\n${K}\n## Findings\nbody`]],
+  ['code-review counts further down', C, `status: clean\nledger\n${K}`, ['normalise', 'clean', null, `status: clean\n${K}\nledger`]],
+  ['code-review counts with decoration on line 2', C, `status: clean\n**${K}**\nbody`, ['normalise', 'clean', null, `status: clean\n${K}\nbody`]],
+  ['code-review both lines out of place', C, `ledger\n${K}\n**Status:** ISSUES_FOUND\nbody`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K}\nledger\nbody`]],
+  ['verify leaves a counts-looking line where it is', V, `intro\n${K}\nStatus: met`, ['normalise', 'met', null, `status: met\nintro\n${K}`]],
+
+  // --- reask: missing ---
+  ['empty', V, '', ['reask', null, 'missing']],
+  ['whitespace only', V, '  \n\t\n\n', ['reask', null, 'missing']],
+  ['no status line', V, 'The change looks fine.\n', ['reask', null, 'missing']],
+  ['status only inside a blockquote', V, '> status: met\nbody', ['reask', null, 'missing']],
+  ['status only inside a code fence', V, '```\nstatus: met\n```\n', ['reask', null, 'missing']],
+  ['status only in an unterminated fence', V, 'text\n```\nstatus: met\n', ['reask', null, 'missing']],
+  ['only candidate indented 4 spaces', V, '    status: met\n', ['reask', null, 'missing']],
+  ['only candidate indented by a tab', V, '\tstatus: met\n', ['reask', null, 'missing']],
+  ['status mid-sentence is not a status line', V, 'Final status: met\n', ['reask', null, 'missing']],
+  ['code-review with no status', C, `${K}\nbody`, ['reask', null, 'missing']],
+
+  // --- reask: unknown-token ---
+  ['PASS', V, 'status: PASS\n', ['reask', null, 'unknown-token']],
+  ['OK', V, 'status: OK\n', ['reask', null, 'unknown-token']],
+  ['LGTM', C, `status: LGTM\n${K}\n`, ['reask', null, 'unknown-token']],
+  ['FAIL', V, 'status: FAIL\n', ['reask', null, 'unknown-token']],
+  ['done', V, 'status: done\n', ['reask', null, 'unknown-token']],
+  ['empty token', V, 'status:\nbody', ['reask', null, 'unknown-token']],
+  ['the other technique token (verify gets clean)', V, 'status: clean\n', ['reask', null, 'unknown-token']],
+  ['the other technique token (code-review gets met)', C, `status: met\n${K}\n`, ['reask', null, 'unknown-token']],
+  ['token with a trailing remark', V, 'status: met (5 claims)\n', ['reask', null, 'unknown-token']],
+  ['two different invalid tokens', V, 'status: PASS\nstatus: OK', ['reask', null, 'unknown-token']],
+  ['bad token and no counts line', C, 'status: LGTM\nbody', ['reask', null, 'unknown-token']],
+
+  // --- reask: conflicting ---
+  ['two different valid tokens', V, 'status: met\nstatus: gaps_found\n', ['reask', null, 'conflicting']],
+  ['valid next to invalid', V, 'status: met\nstatus: PASS\n', ['reask', null, 'conflicting']],
+  ['invalid first, then valid', V, 'status: PASS\nbody\nstatus: met\n', ['reask', null, 'conflicting']],
+  ['code-review differing tokens', C, `status: clean\n${K}\nstatus: issues_found\n`, ['reask', null, 'conflicting']],
+  ['conflicting outranks a missing counts line', C, 'status: clean\nstatus: issues_found\n', ['reask', null, 'conflicting']],
+
+  // --- reask: counts (code-review only) ---
+  ['counts line missing', C, 'status: clean\nbody\n', ['reask', null, 'counts']],
+  ['counts line malformed', C, 'status: clean\ncritical: x · warning: 0 · info: 0\n', ['reask', null, 'counts']],
+  ['two counts lines', C, `status: clean\n${K}\nbody\n${K}\n`, ['reask', null, 'counts']],
+  ['two different counts lines', C, `status: clean\n${K}\ncritical: 1 · warning: 1 · info: 2\n`, ['reask', null, 'counts']],
+  ['counts only inside a code fence', C, `status: clean\n\`\`\`\n${K}\n\`\`\`\n`, ['reask', null, 'counts']],
+];
+
+for (const [name, technique, input, expected] of rows) {
+  const r = checkReport(input, technique);
+  const [action, verdict, problem, normalised] = expected;
+  ok(`${technique} / ${name}: exactly the six keys`, JSON.stringify(Object.keys(r)) === JSON.stringify(KEYS));
+  ok(`${technique} / ${name}: fields ${r.action === 'reask' ? 'null on reask' : '{} for a review'}`, r.action === 'reask' ? r.fields === null : JSON.stringify(r.fields) === '{}');
+  ok(`${technique} / ${name}: body is null`, r.body === null);
+  ok(`${technique} / ${name}: action ${action}`, r.action === action);
+  ok(`${technique} / ${name}: verdict ${verdict}`, r.verdict === verdict);
+  ok(`${technique} / ${name}: problem ${problem}`, r.problem === problem);
+  ok(`${technique} / ${name}: problem is null iff not a reask`, (r.problem === null) === (r.action !== 'reask'));
+  if (action === 'normalise') {
+    ok(`${technique} / ${name}: normalised report`, r.report === normalised);
+    const again = checkReport(r.report, technique);
+    ok(`${technique} / ${name}: the normalised report is accepted as is`, again.action === 'accept' && again.verdict === verdict && again.report === r.report);
+  } else {
+    ok(`${technique} / ${name}: report is the original text`, r.report === input);
+  }
+}
+
+// --- the field families (#249) ---------------------------------------------------
+const EX = 'executor';
+const fullImpl = (status, blockers, extra = '') =>
+  `status: ${status}\ncommits:\nabc1234 feat: x\ndef5678 test: y\ntests: npm test, green\ndeviations: none\nblockers: ${blockers}\n${extra}`;
+// [name, technique, input, expected]; expected = [action, verdict, problem, fields-or-null, body, report-for-normalise]
+const frows = [
+  // --- accept ---
+  ['done, fields parsed', EX, fullImpl('done', 'none'), ['accept', 'done', null,
+    { commits: 'abc1234 feat: x\ndef5678 test: y', tests: 'npm test, green', deviations: 'none', blockers: 'none' }, null]],
+  ['fix uses the implementing contract', 'fix', fullImpl('done', 'none'), ['accept', 'done', null, null, null]],
+  ['done with blockers: empty', EX, 'status: done\ncommits: a b\ntests: t\ndeviations:\nblockers:\n', ['accept', 'done', null,
+    { commits: 'a b', tests: 't', deviations: '', blockers: '' }, null]],
+  ['partial with a blocker', EX, fullImpl('partial', 'infeasible: the gradient header'), ['accept', 'partial', null, null, null]],
+  ['blocked, multi-line blockers', EX, fullImpl('blocked', '\n- pkg-x: `npm i pkg-x`, first seen yesterday\n- foreign change in a.js'), ['accept', 'blocked', null, null, null]],
+  ['optional fields are parsed', EX, fullImpl('done', 'none', 'fidelity:\n- header -> reproduced\nsurfaced scope: a follow-up\n'), ['accept', 'done', null, null, null]],
+  ['investigating found', 'research', 'status: found\nanswer: use X\nevidence: https://a.example/doc\nopen questions: none\n', ['accept', 'found', null,
+    { answer: 'use X', evidence: 'https://a.example/doc', 'open questions': 'none' }, null]],
+  ['debug inconclusive keeps open questions', 'debug', 'status: inconclusive\nanswer: not yet\nevidence: a.js:3\nopen questions: which env?\n', ['accept', 'inconclusive', null, null, null]],
+  ['codebase-map needs_input with questions', 'codebase-map', 'status: needs_input\nanswer: partial\nevidence: a.js:1\nopen questions: which root?\n', ['accept', 'needs_input', null, null, null]],
+  ['plan ready, body is the rest', 'plan', 'status: ready\n\n## Steps\n1. a\n2. b\n\nVerification: x\n', ['accept', 'ready', null, {}, '## Steps\n1. a\n2. b\n\nVerification: x']],
+  ['plan needs_input', 'plan', 'status: needs_input\nquestions:\n1. Which db?\n2. Keep v1?\n', ['accept', 'needs_input', null, { questions: '1. Which db?\n2. Keep v1?' }, null]],
+  // --- normalise: layout, fields intact ---
+  ['bold label and token, bullets', EX, '**Status:** DONE\n- **commits:** abc1234 feat: x\n- tests: ok\n- deviations: none\n- blockers: none\n', ['normalise', 'done', null,
+    { commits: 'abc1234 feat: x', tests: 'ok', deviations: 'none', blockers: 'none' }, null,
+    'status: done\n- **commits:** abc1234 feat: x\n- tests: ok\n- deviations: none\n- blockers: none\n']],
+  ['labels in any case and with spaces', 'debug', 'Intro\nStatus: Found\nAnswer: a\nEVIDENCE: e\nOpen Questions: none', ['normalise', 'found', null,
+    { answer: 'a', evidence: 'e', 'open questions': 'none' }, null, 'status: found\nIntro\nAnswer: a\nEVIDENCE: e\nOpen Questions: none']],
+  ['plan ready, status not first: body without the status line', 'plan', 'Here is the plan.\n\nstatus: ready\nStep 1\n', ['normalise', 'ready', null, {}, 'Here is the plan.\n\nStep 1',
+    'status: ready\nHere is the plan.\n\nStep 1\n']],
+  ['a label inside a code fence is not a field', EX, 'status: done\ncommits: a b\ntests: t\ndeviations: none\n```\nblockers: x\n```\nblockers: none\n', ['accept', 'done', null,
+    { commits: 'a b', tests: 't', deviations: 'none\n```\nblockers: x\n```', blockers: 'none' }, null]],
+  ['a label in a blockquote is not a field', EX, 'status: done\ncommits: a\ntests: t\ndeviations: none\n> blockers: x\nblockers: none\n', ['accept', 'done', null, null, null]],
+  ['a label that is not in the closed list is part of the value', EX, 'status: done\ncommits: a\nnote: x\ntests: t\ndeviations: none\nblockers: none\n', ['accept', 'done', null,
+    { commits: 'a\nnote: x', tests: 't', deviations: 'none', blockers: 'none' }, null]],
+
+  // --- reask: the status problems keep precedence over fields ---
+  ['missing status', EX, 'commits: a\ntests: t\ndeviations: none\nblockers: none\n', ['reask', null, 'missing']],
+  ['conflicting outranks fields', EX, 'status: done\nstatus: blocked\nblockers: none\n', ['reask', null, 'conflicting']],
+  ['unknown token outranks fields', EX, 'status: met\ncommits: a\n', ['reask', null, 'unknown-token']],
+  ['a review token is unknown for a field technique', 'plan', 'status: met\n', ['reask', null, 'unknown-token']],
+  ['an implementing token is unknown for investigating', 'research', 'status: done\n', ['reask', null, 'unknown-token']],
+  // --- reask: fields ---
+  ['missing required field (tests)', EX, 'status: done\ncommits: a\ndeviations: none\nblockers: none\n', ['reask', null, 'fields']],
+  ['no fields at all', 'debug', 'status: found\nThe cause is X.\n', ['reask', null, 'fields']],
+  ['done with blockers', EX, fullImpl('done', 'a flagged package'), ['reask', null, 'fields']],
+  ['partial without blockers', EX, fullImpl('partial', 'none'), ['reask', null, 'fields']],
+  ['blocked with an empty blockers', EX, fullImpl('blocked', ''), ['reask', null, 'fields']],
+  ['needs_input without open questions', 'research', 'status: needs_input\nanswer: a\nevidence: e\nopen questions: none\n', ['reask', null, 'fields']],
+  ['needs_input with an empty open questions', 'debug', 'status: needs_input\nanswer: a\nevidence: e\nopen questions:\n', ['reask', null, 'fields']],
+  ['plan needs_input without questions', 'plan', 'status: needs_input\nsome prose\n', ['reask', null, 'fields']],
+  ['plan needs_input with none questions', 'plan', 'status: needs_input\nquestions: none\n', ['reask', null, 'fields']],
+  ['plan ready with an empty body', 'plan', 'status: ready\n\n  \n', ['reask', null, 'fields']],
+  ['plan ready with only a status line', 'plan', 'status: ready', ['reask', null, 'fields']],
+  ['a fenced status line inside a plan body is part of the body', 'plan', 'status: ready\n\nA feature about statuses:\n```\nstatus: pending\n```\nDone.\n', ['accept', 'ready', null, {},
+    'A feature about statuses:\n```\nstatus: pending\n```\nDone.']],
+  ['a blockquoted status line inside an answer is ignored', 'research', 'status: found\nanswer: see\n> status: pending\nevidence: e\nopen questions: none\n', ['accept', 'found', null, null, null]],
+  ['prose after the last field becomes its value, so a done report reasks', EX, fullImpl('done', 'none', 'Note: hi\n'), ['reask', null, 'fields']],
+  ['the same label twice', EX, fullImpl('done', 'none', 'tests: again\n'), ['reask', null, 'fields']],
+];
+for (const [name, technique, input, expected] of frows) {
+  const r = checkReport(input, technique);
+  const [action, verdict, problem, fields, body, normalised] = expected;
+  const t = `${technique} / ${name}`;
+  ok(`${t}: exactly the six keys`, JSON.stringify(Object.keys(r)) === JSON.stringify(KEYS));
+  ok(`${t}: action ${action}`, r.action === action);
+  ok(`${t}: verdict ${verdict}`, r.verdict === verdict);
+  ok(`${t}: problem ${problem}`, r.problem === problem);
+  if (action === 'reask') {
+    ok(`${t}: fields and body are null`, r.fields === null && r.body === null);
+    ok(`${t}: report is the original text`, r.report === input);
+    continue;
+  }
+  if (fields) ok(`${t}: fields`, JSON.stringify(r.fields) === JSON.stringify(fields));
+  else ok(`${t}: fields is an object`, r.fields !== null && typeof r.fields === 'object');
+  if (body !== undefined && (technique === 'plan' || body !== null)) ok(`${t}: body`, r.body === body);
+  if (action === 'normalise') {
+    ok(`${t}: normalised report`, r.report === normalised);
+    const again = checkReport(r.report, technique);
+    ok(`${t}: the normalised report is accepted as is, with the same fields and body`,
+      again.action === 'accept' && again.report === r.report && JSON.stringify(again.fields) === JSON.stringify(r.fields) && again.body === r.body);
+  } else {
+    ok(`${t}: report is the original text`, r.report === input);
+  }
+}
+{
+  const r = checkReport(fullImpl('done', 'none', 'fidelity:\n- header -> reproduced\nsurfaced scope: a follow-up\n'), EX);
+  ok('optional fidelity is multi-line', r.fields.fidelity === '- header -> reproduced');
+  ok('optional surfaced scope is read', r.fields['surfaced scope'] === 'a follow-up');
+  const b = checkReport(fullImpl('blocked', '\n- pkg-x: `npm i pkg-x`, first seen yesterday\n- foreign change in a.js'), EX);
+  ok('multi-line blockers keep every entry', b.fields.blockers === '- pkg-x: `npm i pkg-x`, first seen yesterday\n- foreign change in a.js');
+  ok('a report with an unterminated fence still parses its leading fields', checkReport('status: found\nanswer: a\nevidence: e\nopen questions: none\n```\nx', 'research').action === 'accept');
+}
+
+// --- misuse ---------------------------------------------------------------------
+ok('checkReport: unknown technique throws', (() => { try { checkReport('status: met', 'bogus'); } catch (e) { return true; } return false; })());
+ok('checkReport: missing technique throws', (() => { try { checkReport('status: met'); } catch (e) { return true; } return false; })());
+ok('checkReport: a non-string report is treated as empty', checkReport(undefined, V).problem === 'missing');
+
+// --- vocabulary equals the technique files --------------------------------------
+const techniqueTokens = (file) => {
+  const text = fs.readFileSync(path.join(techDir, file), 'utf8');
+  return [...new Set([...text.matchAll(/`status: (\w+)`/g)].map((m) => m[1]))].sort();
+};
+ok('vocabulary: verify tokens equal the ones verify.md defines',
+  JSON.stringify([...TOKENS.verify].sort()) === JSON.stringify(techniqueTokens('verify.md')) && TOKENS.verify.length === 3);
+ok('vocabulary: code-review tokens equal the ones code-review.md defines',
+  JSON.stringify([...TOKENS['code-review']].sort()) === JSON.stringify(techniqueTokens('code-review.md')) && TOKENS['code-review'].length === 2);
+
+// --- the field contracts equal scripts/agent-blocks.md (#249) -----------------------
+{
+  const { parseSource } = require(path.resolve(__dirname, '..', '..', '..', '..', 'scripts', 'sync-agent-blocks.js'));
+  const blocks = parseSource(fs.readFileSync(path.resolve(__dirname, '..', '..', '..', '..', 'scripts', 'agent-blocks.md'), 'utf8'));
+  const words = (block, prefix) => {
+    const line = block.split('\n').find((l) => l.startsWith(`- ${prefix}:`)) || '';
+    return [...line.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+  };
+  // `- invariant: `a`, `b` => `field` non-empty.` -> { when, field, rule }
+  const invariants = (block) => block.split('\n').filter((l) => l.startsWith('- invariant:')).map((l) => {
+    const [lhs, rhs] = l.split('=>');
+    return { when: [...lhs.matchAll(/`([^`]+)`/g)].map((m) => m[1]), field: /`([^`]+)`/.exec(rhs)[1], rule: /(non-empty|none)\.$/.exec(rhs)[1] };
+  });
+  for (const family of ['implementing', 'investigating', 'plan']) {
+    const block = blocks[family];
+    ok(`contracts: source defines the ${family} block`, typeof block === 'string');
+    ok(`contracts: ${family} tokens equal the source`, JSON.stringify(CONTRACTS[family].tokens) === JSON.stringify(words(block, 'statuses')));
+    ok(`contracts: ${family} required fields equal the source`, JSON.stringify(CONTRACTS[family].required) === JSON.stringify(words(block, 'required fields')));
+    ok(`contracts: ${family} optional fields equal the source`, JSON.stringify(CONTRACTS[family].optional) === JSON.stringify(words(block, 'optional fields')));
+    ok(`contracts: ${family} invariants equal the source`, JSON.stringify(CONTRACTS[family].invariants) === JSON.stringify(invariants(block)) && invariants(block).length > 0);
+  }
+  const { FAMILIES } = require(path.resolve(__dirname, '..', '..', '..', '..', 'scripts', 'sync-agent-blocks.js'));
+  for (const [technique, family] of Object.entries(FAMILY_OF)) {
+    ok(`contracts: technique ${technique} maps to the family of trailhead-${technique} in the sync script`, FAMILIES[`trailhead-${technique}`] === family);
+    ok(`contracts: TOKENS.${technique} are the ${family} tokens`, JSON.stringify(TOKENS[technique]) === JSON.stringify(CONTRACTS[family].tokens));
+  }
+  ok('contracts: every non-review agent has a technique here',
+    Object.entries(FAMILIES).filter(([, f]) => f !== 'reviewing').every(([a]) => FAMILY_OF[a.replace(/^trailhead-/, '')] !== undefined));
+}
+
+// --- CLI -------------------------------------------------------------------------
+function cli(args, input) {
+  const r = spawnSync(process.execPath, [scriptPath, ...args], { input, encoding: 'utf8' });
+  return { code: r.status, out: r.stdout, err: r.stderr };
+}
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-report-status-test-'));
+const file = (name, text) => { const p = path.join(tmp, name); fs.writeFileSync(p, text); return p; };
+const oneLine = (out) => { const lines = out.split('\n').filter(Boolean); return out.endsWith('\n') && lines.length === 1 ? JSON.parse(lines[0]) : null; };
+
+{
+  const r = cli(['--technique', 'verify', '--file', file('a.md', 'status: met\nbody\n')]);
+  const j = oneLine(r.out);
+  ok('cli --file accept: exit 0', r.code === 0);
+  ok('cli --file accept: one JSON line with the six keys', !!j && JSON.stringify(Object.keys(j)) === JSON.stringify(KEYS));
+  ok('cli --file accept: values', j.action === 'accept' && j.verdict === 'met' && j.problem === null && j.report === 'status: met\nbody\n');
+  ok('cli --file accept: fields {} and body null for a review', JSON.stringify(j.fields) === '{}' && j.body === null);
+}
+{
+  const r = cli(['--technique', 'plan', '--file', file('p.md', 'status: ready\n\nStep 1\n')]);
+  const j = oneLine(r.out);
+  ok('cli plan ready: exit 0, body is the plan', r.code === 0 && j.action === 'accept' && j.body === 'Step 1');
+  const e = cli(['--technique', 'executor'], fullImpl('done', 'none'));
+  const je = oneLine(e.out);
+  ok('cli executor stdin: fields returned', e.code === 0 && je.action === 'accept' && je.fields.tests === 'npm test, green');
+  const f = cli(['--technique', 'research'], 'status: needs_input\nanswer: a\nevidence: e\n');
+  const jf = oneLine(f.out);
+  ok('cli research: a fields reask, exit 0', f.code === 0 && jf.action === 'reask' && jf.problem === 'fields' && jf.fields === null);
+}
+{
+  const r = cli(['--technique', 'verify', '--file', file('b.md', '**Status:** GAPS_FOUND\r\nbody\r\n')]);
+  const j = oneLine(r.out);
+  ok('cli --file normalise: exit 0', r.code === 0);
+  ok('cli --file normalise: values', j.action === 'normalise' && j.verdict === 'gaps_found' && j.report === 'status: gaps_found\nbody\n');
+}
+{
+  const r = cli(['--technique', 'verify', '--file', file('c.md', 'status: PASS\n')]);
+  const j = oneLine(r.out);
+  ok('cli --file reask: exit 0', r.code === 0);
+  ok('cli --file reask: values', j.action === 'reask' && j.verdict === null && j.problem === 'unknown-token' && j.report === 'status: PASS\n');
+}
+{
+  const r = cli(['--technique', 'code-review'], `status: clean\n${K}\nbody\n`);
+  const j = oneLine(r.out);
+  ok('cli stdin: exit 0', r.code === 0);
+  ok('cli stdin: code-review accept', j.action === 'accept' && j.verdict === 'clean' && j.report === `status: clean\n${K}\nbody\n`);
+}
+{
+  const r = cli(['--technique', 'code-review'], 'status: clean\nbody\n');
+  const j = oneLine(r.out);
+  ok('cli stdin: counts reask', r.code === 0 && j.action === 'reask' && j.problem === 'counts');
+}
+{
+  const r = cli(['--technique', 'verify'], '');
+  const j = oneLine(r.out);
+  ok('cli stdin: empty input is a missing reask, exit 0', r.code === 0 && j.action === 'reask' && j.problem === 'missing');
+}
+{
+  // A report over the 64 KB pipe buffer must come back whole through a pipe.
+  const big = 'status: met\n' + 'x'.repeat(300000) + '\n';
+  const r = cli(['--technique', 'verify'], big);
+  const j = oneLine(r.out);
+  ok('cli: a report over 64 KB arrives whole through a pipe', r.code === 0 && !!j && j.action === 'accept' && j.report === big);
+  const f = cli(['--technique', 'verify', '--file', file('big.md', big)]);
+  const jf = oneLine(f.out);
+  ok('cli --file: a report over 64 KB arrives whole through a pipe', f.code === 0 && !!jf && jf.report === big);
+}
+const usageErrors = [
+  ['no technique', ['--file', file('d.md', 'status: met')]],
+  ['unknown technique', ['--technique', 'bogus', '--file', file('e.md', 'status: met')]],
+  ['technique without a value', ['--technique']],
+  ['unknown flag', ['--technique', 'verify', '--bogus', 'x', '--file', file('f.md', 'status: met')]],
+  ['--file without a value', ['--technique', 'verify', '--file']],
+  ['empty --file value', ['--technique', 'verify', '--file', '']],
+  ['unreadable file', ['--technique', 'verify', '--file', path.join(tmp, 'nope.md')]],
+];
+for (const [name, args] of usageErrors) {
+  const r = cli(args, 'status: met\n');
+  let e = null;
+  try { e = JSON.parse(r.err.trim()); } catch (_) { /* leave null */ }
+  ok(`cli usage error (${name}): exit 2`, r.code === 2);
+  ok(`cli usage error (${name}): nothing on stdout`, r.out === '');
+  ok(`cli usage error (${name}): {"error": message} on stderr`, !!e && typeof e.error === 'string' && e.error.length > 0);
+}
+
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log(`report-status.test.js: ${passed} checks passed`);

package/plugins/trailhead/hooks/lib/shell-scan.js

@@ -12,7 +12,8 @@
 // surrounding whitespace, the latter keeps a multi-word quoted phrase as ONE
 // opaque token instead of splitting it into separate words.
 //
-// Consumers: trailhead-search-guard.js and trailhead-secret-read-guard.js.
+// Consumers: several guards and libs (grep `lib/shell-scan`), e.g. the search,
+// secret-read, secret and install guards and lib/unmodelled.js.
 // Self-contained, no external dependencies. Best-effort, like the guards that
 // use it: not a full shell parser, just enough to close their known gaps.
 
@@ -658,7 +659,41 @@ function scanArgsSkippingPattern(args, config, isMatch) {
   return null;
 }
 
+// --- redirections ----------------------------------------------------------
+
+// Redirection token shapes (tokens are raw, so a quoted word never matches).
+const FD_DUP_RE = /^\d*[<>]&(?:\d+|-)$/; //            2>&1  >&2  >&-  0<&3
+const OUT_SEP_RE = /^(?:\d*|&)?>(?:>|&)?\|?$/; //     >  >>  >|  2>  &>  &>>  >&  2>&  (target is next token)
+const OUT_GLUED_RE = /^(?:\d*|&)>>?\|?./; //          >file  2>/dev/null  &>f  2>>f
+const HEREDOC_SEP_RE = /^\d*<<[<-]?$/; //             <<  <<-  <<<  (tag/word is next token)
+const HEREDOC_GLUED_RE = /^\d*<<./; //                <<EOF  <<-'EOF'  <<<word
+const IN_SEP_RE = /^\d*<$/; //                        <  0<  (target is next token, still a read)
+const IN_GLUED_RE = /^\d*<(.+)$/; //                  <file  0<file
+
+// Return a NEW arg list with redirections removed. Output/dup/heredoc pieces
+// vanish with their targets; an input redirection keeps only its target (a real
+// read). Done before the pattern-skipping walk so a redirection token can never
+// be mistaken for (or swallow) the leading pattern positional of grep/rg/sed/awk.
+function stripRedirections(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const t = args[i];
+    // Separate-operator forms first: `>>` would otherwise also satisfy the glued regex.
+    if (OUT_SEP_RE.test(t) || HEREDOC_SEP_RE.test(t)) { i++; continue; }
+    if (FD_DUP_RE.test(t) || HEREDOC_GLUED_RE.test(t) || OUT_GLUED_RE.test(t)) continue;
+    if (IN_SEP_RE.test(t)) continue; // operator dropped; next token is the read target
+    const m = IN_GLUED_RE.exec(t);
+    if (m) {
+      if (!m[1].startsWith('(')) out.push(m[1]); // `<(cmd)` process substitution: not a file
+      continue;
+    }
+    out.push(t);
+  }
+  return out;
+}
+
 module.exports = {
+  stripRedirections,
   basename,
   stripQuotes,
   stripHeredocBodies,

package/plugins/trailhead/hooks/lib/shell-scan.test.js

@@ -16,6 +16,7 @@ const {
   inWordContinuations,
   scanArgsSkippingPattern,
   SEARCH_VERB_CONFIG,
+  stripRedirections,
 } = require('./shell-scan.js');
 
 let passed = 0;
@@ -456,6 +457,19 @@ ok('scanArgsSkippingPattern still finds a secret FILE operand after the pattern'
   ok('inWordContinuations is empty for plain text', iw('echo hi').length === 0);
 }
 
+// --- stripRedirections ---
+{
+  const sr = (a) => JSON.stringify(stripRedirections(a));
+  ok('stripRedirections drops an fd dup (2>&1)', sr(['x', '2>&1']) === JSON.stringify(['x']));
+  ok('stripRedirections drops a glued output (>f)', sr(['x', '>f']) === JSON.stringify(['x']));
+  ok('stripRedirections drops a separate output and its target (> f)', sr(['x', '>', 'f', 'y']) === JSON.stringify(['x', 'y']));
+  ok('stripRedirections drops a glued append (>>f)', sr(['x', '>>f']) === JSON.stringify(['x']));
+  ok('stripRedirections keeps a glued input target (<f)', sr(['x', '<f']) === JSON.stringify(['x', 'f']));
+  ok('stripRedirections keeps a separate input target (< f)', sr(['x', '<', 'f']) === JSON.stringify(['x', 'f']));
+  ok('stripRedirections drops a glued heredoc (<<EOF)', sr(['x', '<<EOF']) === JSON.stringify(['x']));
+  ok('stripRedirections drops a process substitution (<(x))', sr(['x', '<(x)']) === JSON.stringify(['x']));
+}
+
 // --- the new hooks leave the existing lexer output untouched ---
 {
   const c = 'a ${ b; } c; d \\\ne | f $(g ${ h; })\ncat <<E\n${ x; }\nE';

package/plugins/trailhead/hooks/lib/statusline-context.test.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// Tests for templates/statusline-trailhead.sh (barra contesto, --context-only).
+// Run: node statusline-context.test.js
+// No framework: plain asserts, same style as work-state.test.js.
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const script = path.resolve(__dirname, '..', '..', 'templates', 'statusline-trailhead.sh');
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-statusline-ctx-'));
+const home = path.join(root, 'home');
+const cfg = path.join(root, 'cfg');
+const proj = path.join(root, 'proj');
+for (const d of [home, cfg, path.join(proj, '.claude')]) fs.mkdirSync(d, { recursive: true });
+
+const SETTINGS = {
+  user: path.join(cfg, 'settings.json'),
+  project: path.join(proj, '.claude', 'settings.json'),
+  local: path.join(proj, '.claude', 'settings.local.json'),
+};
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const eq = (name, got, want) => { assert.strictEqual(got, want, `${name}: got ${JSON.stringify(got)}, want ${JSON.stringify(want)}`); passed++; };
+
+function setSettings(files) {
+  for (const f of Object.values(SETTINGS)) fs.rmSync(f, { force: true });
+  for (const [k, v] of Object.entries(files || {})) {
+    fs.writeFileSync(SETTINGS[k], typeof v === 'string' ? v : JSON.stringify(v));
+  }
+}
+
+// Esegue lo script e ritorna { pct, shown, out }
+function ctx(tok, { env = {}, settings = {}, modelId = 'claude-opus-5-5[1m]', size = 1000000 } = {}) {
+  setSettings(settings);
+  const base = { ...process.env };
+  for (const k of ['CLAUDE_CODE_AUTO_COMPACT_WINDOW', 'CLAUDE_AUTOCOMPACT_PCT_OVERRIDE',
+    'DISABLE_AUTO_COMPACT', 'DISABLE_COMPACT', 'CONTEXT_LIMIT', 'CONTEXT_USABLE_RATIO']) delete base[k];
+  const input = {
+    model: { id: modelId, display_name: 'Test' },
+    workspace: { project_dir: proj, current_dir: proj },
+    context_window: { context_window_size: size, current_usage: { input_tokens: tok } },
+  };
+  const r = spawnSync('bash', [script, '--context-only'], {
+    input: JSON.stringify(input),
+    env: { ...base, NO_COLOR: '1', TRAILHEAD_STATUSLINE_USAGE: '0', HOME: home, CLAUDE_CONFIG_DIR: cfg, ...env },
+    encoding: 'utf8',
+  });
+  const out = r.stdout.trim();
+  const m = out.match(/^\[.{10}\] (\d+)k\/(\d+)k \((\d+)%\)$/);
+  assert.ok(m, `unexpected output: ${JSON.stringify(out)} ${r.stderr}`);
+  return { pct: Number(m[3]), shown: `${m[1]}k/${m[2]}k`, out };
+}
+const pct = (tok, o) => ctx(tok, o).pct;
+
+// --- default 1M: soglia = 1M - 33k = 967k ---
+eq('default 966k', pct(966000), 100);
+eq('default 967k', pct(967000), 100);
+eq('default 900k', pct(900000), 93);
+ok('default 800k not 100', pct(800000) < 100);
+eq('display full window', ctx(900000).shown, '900k/1000k');
+
+// --- autoCompactWindow ---
+const win650 = { autoCompactWindow: 650000 };
+eq('top-level 617k', pct(617000, { settings: { user: win650 } }), 100);
+ok('top-level 600k', pct(600000, { settings: { user: win650 } }) < 100);
+const perModel = { modelSettings: { 'claude-opus-5-5': { autoCompactWindow: 650000 } } };
+eq('per-model 617k', pct(617000, { settings: { user: perModel } }), 100);
+ok('per-model 600k', pct(600000, { settings: { user: perModel } }) < 100);
+eq('per-model beats top-level', pct(617000, {
+  settings: { user: { autoCompactWindow: 900000, ...perModel } } }), 100);
+eq('per-model beats top-level (larger top)', pct(300000, {
+  settings: { user: { autoCompactWindow: 400000, modelSettings: { 'claude-opus-5-5': { autoCompactWindow: 1000000 } } } } }), 31);
+eq('local beats user', pct(617000, { settings: { user: { autoCompactWindow: 1000000 }, local: win650 } }), 100);
+eq('local beats project', pct(617000, { settings: { project: { autoCompactWindow: 1000000 }, local: win650 } }), 100);
+eq('project beats user', pct(617000, { settings: { user: { autoCompactWindow: 1000000 }, project: win650 } }), 100);
+eq('invalid json skipped', pct(617000, { settings: { user: win650, local: '{nope' } }), 100);
+eq('non-positive setting ignored', pct(900000, { settings: { user: { autoCompactWindow: -5 } } }), 93);
+eq('non-numeric setting ignored', pct(900000, { settings: { user: { autoCompactWindow: 'big' } } }), 93);
+eq('invalid higher file value falls to lower', pct(617000, {
+  settings: { user: win650, local: { autoCompactWindow: 'x' } } }), 100);
+
+// --- env CLAUDE_CODE_AUTO_COMPACT_WINDOW ---
+eq('env beats setting', pct(617000, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '650000' },
+  settings: { user: { autoCompactWindow: 1000000 } } }), 100);
+for (const bad of ['abc', '0', '-100']) {
+  eq(`env ${bad} ignored`, pct(900000, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: bad } }), 93);
+}
+eq('env bad falls back to setting', pct(617000, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: 'abc' },
+  settings: { user: win650 } }), 100);
+eq('window above model capped', pct(966000, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '5000000' } }), 100);
+eq('window above model capped 900k', pct(900000, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '5000000' } }), 93);
+
+// --- CLAUDE_AUTOCOMPACT_PCT_OVERRIDE ---
+eq('pct 50 at threshold', pct(500000, { env: { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: '50' } }), 100);
+eq('pct 50 at 450k', pct(450000, { env: { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: '50' } }), 90);
+for (const v of ['100', '101', '0', '-3', 'abc']) {
+  eq(`pct ${v} no change`, pct(900000, { env: { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: v } }), 93);
+}
+eq('pct 1 -> threshold 10k', pct(10000, { env: { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: '1' } }), 100);
+eq('pct 1 at 5k', pct(5000, { env: { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: '1' } }), 50);
+
+// --- disabilitato ---
+eq('DISABLE_AUTO_COMPACT', pct(400000, { env: { DISABLE_AUTO_COMPACT: '1' } }), 40);
+eq('DISABLE_COMPACT true', pct(400000, { env: { DISABLE_COMPACT: 'TRUE' } }), 40);
+eq('disabled ignores settings and pct', pct(400000, { env: { DISABLE_AUTO_COMPACT: 'yes', CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: '10' },
+  settings: { user: win650 } }), 40);
+eq('falsy DISABLE ignored', pct(900000, { env: { DISABLE_AUTO_COMPACT: '0' } }), 93);
+eq('DISABLE_COMPACT on', pct(400000, { env: { DISABLE_COMPACT: 'on' } }), 40);
+eq('DISABLE false ignored', pct(900000, { env: { DISABLE_COMPACT: 'false' } }), 93);
+
+// --- per-modello in un file meno specifico batte top-level in uno piu' specifico ---
+eq('per-model user beats top-level local', pct(617000, {
+  settings: { user: perModel, local: { autoCompactWindow: 1000000 } } }), 100);
+
+// --- fallback tabella modello (niente context_window_size): 200k, soglia 167k ---
+eq('model table fallback', pct(100000, { size: 0 }), 60);
+eq('model table fallback display', ctx(100000, { size: 0 }).shown, '100k/200k');
+
+// --- tetto modello ---
+eq('CONTEXT_LIMIT caps display', ctx(100000, { env: { CONTEXT_LIMIT: '200000' } }).shown, '100k/200k');
+eq('CONTEXT_LIMIT pct (threshold 167k)', pct(100000, { env: { CONTEXT_LIMIT: '200000' } }), 60);
+
+// --- override manuale CONTEXT_USABLE_RATIO ---
+eq('ratio 0.8 old behaviour', pct(800000, { env: { CONTEXT_USABLE_RATIO: '0.8' } }), 100);
+eq('ratio 0.8 at 400k', pct(400000, { env: { CONTEXT_USABLE_RATIO: '0.8' } }), 50);
+eq('ratio bypasses window setting', pct(400000, { env: { CONTEXT_USABLE_RATIO: '0.8' }, settings: { user: win650 } }), 50);
+eq('ratio invalid ignored', pct(900000, { env: { CONTEXT_USABLE_RATIO: '2' } }), 93);
+
+// --- bordo soglia: finestra 34k -> soglia 1000 ---
+const edge = { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '34000' } };
+eq('edge threshold-1', pct(994, edge), 99);
+eq('edge threshold', pct(1000, edge), 100);
+// finestra minuscola: soglia mai sotto 1
+eq('tiny window guard', pct(5, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '10' } }), 100);
+
+fs.rmSync(root, { recursive: true, force: true });
+console.log(`statusline-context.test.js: ${passed} assertions passed`);