feat(voyage): S6 — v5.5 brief framing enforcement (brief_version 2.2)
Implements the CLAUDE.md cross-cutting invariant "brief framing must match operator intent" as a controlled brief_version 2.1->2.2 bump (operator option A1). Three defense layers, version-gated at >=2.2 so existing 2.0/2.1 briefs stay valid (forward + backward compatible), mirroring the phase_signals >=2.1 gate: - L1 framing: enum field (preserve|refine|replace|new-direction). Enum-checked on any version when present (BRIEF_INVALID_FRAMING); missing at >=2.2 -> BRIEF_MISSING_FRAMING. /trekbrief Phase 2.5 collects it BEFORE any brief prose (non-skippable, even in --quick). - L2 memory alignment: new brief-reviewer dimension 6 comparing brief Intent/Goal + framing against operator memory for explicit contradictions; degrades to score 5 (N/A) when no memory context is supplied. Wired into Phase 4e gate (memory_alignment.score >= 4). - L3 obligatory ## TL;DR (<=5 content lines) at >=2.2; soft cap -> BRIEF_TLDR_TOO_LONG warning. trekreview briefs are exempt from the framing/TL;DR gate. Handover 1 PUBLIC CONTRACT doc, README "What's new", and the CLAUDE.md invariant + agents table (brief-reviewer 5->6 dimensions) updated to 2.2 (schema axis only; plugin version badge + CHANGELOG remain S10). Iron Law followed: validator tests red->green first. Tests 586 -> 606 (+20, 604 pass / 2 skip). claude plugin validate passes (pre-existing CLAUDE.md root-context warning unchanged). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LqBYc8Ltrk7LipyJmGxXiB
This commit is contained in:
parent
fa23b16443
commit
736ae55d66
10 changed files with 409 additions and 31 deletions
|
|
@ -21,6 +21,8 @@ import { parseDocument } from '../../lib/util/frontmatter.mjs';
|
|||
const HERE = dirname(fileURLToPath(import.meta.url));
|
||||
const ROOT = join(HERE, '..', '..');
|
||||
const COMMAND_FILE = join(ROOT, 'commands', 'trekbrief.md');
|
||||
const REVIEWER_FILE = join(ROOT, 'agents', 'brief-reviewer.md');
|
||||
const TEMPLATE_FILE = join(ROOT, 'templates', 'trekbrief-template.md');
|
||||
const FIXTURE = (name) => join(ROOT, 'tests', 'fixtures', name);
|
||||
|
||||
function read() {
|
||||
|
|
@ -97,6 +99,62 @@ test('trekbrief — SC1: missing phase_signals + brief_version 2.1 triggers BRIE
|
|||
);
|
||||
});
|
||||
|
||||
// --- v5.5 — framing enforcement + TL;DR + memory-alignment prose-pins ---
|
||||
|
||||
test('trekbrief — v5.5 Phase 2.5 framing declaration heading present', () => {
|
||||
const text = read();
|
||||
assert.match(text, /^## Phase 2\.5 — Framing declaration/m,
|
||||
'Phase 2.5 framing-declaration heading missing from commands/trekbrief.md');
|
||||
});
|
||||
|
||||
test('trekbrief — v5.5 Phase 2.5 references all four framing values', () => {
|
||||
const text = read();
|
||||
const start = text.indexOf('## Phase 2.5');
|
||||
const section = text.slice(start, text.indexOf('## Phase 3', start));
|
||||
for (const v of ['preserve', 'refine', 'replace', 'new-direction']) {
|
||||
assert.ok(section.includes(v), `Phase 2.5 missing framing value "${v}"`);
|
||||
}
|
||||
});
|
||||
|
||||
test('trekbrief — v5.5 Phase 2.5 runs before any brief prose (precedes Phase 3)', () => {
|
||||
const text = read();
|
||||
assert.ok(text.indexOf('## Phase 2.5') < text.indexOf('## Phase 3'),
|
||||
'Phase 2.5 must come before the completeness loop (before prose)');
|
||||
assert.ok(text.includes('even in `--quick` mode'),
|
||||
'framing must be non-skippable even in --quick mode');
|
||||
});
|
||||
|
||||
test('trekbrief — v5.5 Step 4a writes framing + brief_version 2.2 + generates TL;DR', () => {
|
||||
const text = read();
|
||||
assert.ok(/brief_version: "2\.2"/.test(text), 'Step 4a must set brief_version 2.2');
|
||||
assert.ok(/framing: <state\.framing>/.test(text), 'Step 4a must write the committed framing value');
|
||||
assert.ok(/## TL;DR/.test(text), 'Step 4a must generate the TL;DR section');
|
||||
});
|
||||
|
||||
test('trekbrief — v5.5 Phase 4e gate includes memory_alignment', () => {
|
||||
const text = read();
|
||||
assert.ok(/memory_alignment\.score ≥ 4/.test(text),
|
||||
'Phase 4e gate must require memory_alignment.score ≥ 4');
|
||||
});
|
||||
|
||||
test('trekbrief — v5.5 brief-reviewer declares the memory-alignment dimension', () => {
|
||||
const reviewer = readFileSync(REVIEWER_FILE, 'utf8');
|
||||
assert.match(reviewer, /### 6\. Memory alignment/,
|
||||
'brief-reviewer.md missing dimension 6 (memory alignment)');
|
||||
assert.ok(reviewer.includes('"memory_alignment"'),
|
||||
'brief-reviewer.md JSON schema missing memory_alignment key');
|
||||
assert.ok(/no memory context (is )?supplied/i.test(reviewer),
|
||||
'brief-reviewer must define the no-memory-context N/A fallback');
|
||||
});
|
||||
|
||||
test('trekbrief — v5.5 template carries framing field, 2.2, and TL;DR section', () => {
|
||||
const tpl = readFileSync(TEMPLATE_FILE, 'utf8');
|
||||
assert.ok(/brief_version: "2\.2"/.test(tpl), 'template must declare brief_version 2.2');
|
||||
assert.match(tpl, /^framing: \{preserve \| refine \| replace \| new-direction\}/m,
|
||||
'template frontmatter must include the framing field');
|
||||
assert.match(tpl, /^## TL;DR$/m, 'template must include the ## TL;DR section');
|
||||
});
|
||||
|
||||
test('trekbrief — SC1: phase_signals_partial: true does NOT trigger the gate', () => {
|
||||
const partial = `---
|
||||
type: trekbrief
|
||||
|
|
|
|||
|
|
@ -559,10 +559,10 @@ test('operational files no longer reference trekrevise (v5.0.0 removal)', () =>
|
|||
|
||||
// --- v5.1 — phase_signals + brief_version 2.1 ---
|
||||
|
||||
test('v5.1 — templates/trekbrief-template.md declares brief_version: "2.1" (quoted)', () => {
|
||||
test('v5.5 — templates/trekbrief-template.md declares brief_version: "2.2" (quoted)', () => {
|
||||
const t = read('templates/trekbrief-template.md');
|
||||
assert.match(t, /^brief_version: "2\.1"$/m,
|
||||
'trekbrief-template.md must declare brief_version: "2.1" (quoted) — unquoted parses as Number and bypasses sequencing gate');
|
||||
assert.match(t, /^brief_version: "2\.2"$/m,
|
||||
'trekbrief-template.md must declare brief_version: "2.2" (quoted) — unquoted parses as Number and bypasses sequencing gate; v5.5 bumped 2.1→2.2 for framing enforcement');
|
||||
});
|
||||
|
||||
test('v5.1 — templates/trekbrief-template.md contains phase_signals: block', () => {
|
||||
|
|
@ -641,18 +641,53 @@ test('v5.4 — Handover 1 declares the PUBLIC CONTRACT callout + breaking-for-do
|
|||
'the callout must state that a brief-schema change is a breaking change for every downstream consumer');
|
||||
});
|
||||
|
||||
test('v5.4 — brief_version 2.1 is the frozen public-contract baseline (no stale 2.0)', () => {
|
||||
test('v5.5 — brief_version 2.2 is current in the public-contract schema table (no stale 2.0/2.1)', () => {
|
||||
const t = read('docs/HANDOVER-CONTRACTS.md');
|
||||
assert.ok(!t.includes('`"2.0"` (current)'),
|
||||
'Handover 1 schema table must not still mark brief_version "2.0" as current (stale)');
|
||||
assert.ok(t.includes('`"2.1"` (current)'),
|
||||
'Handover 1 schema table must mark brief_version "2.1" as current');
|
||||
assert.ok(!t.includes('`"2.1"` (current)'),
|
||||
'Handover 1 schema table must not still mark brief_version "2.1" as current (stale — v5.5 bumped to 2.2)');
|
||||
assert.ok(t.includes('`"2.2"` (current)'),
|
||||
'Handover 1 schema table must mark brief_version "2.2" as current');
|
||||
});
|
||||
|
||||
test('v5.4 — phase_signals stays optional: v5.4 freezes, does not promote to required', () => {
|
||||
test('v5.4 — phase_signals stays optional: not promoted to required', () => {
|
||||
const t = read('docs/HANDOVER-CONTRACTS.md');
|
||||
assert.ok(!t.includes('v5.4 may promote'),
|
||||
'the speculative "v5.4 may promote phase_signals to required" line must be resolved (S3 froze the shape)');
|
||||
assert.ok(t.includes('freezes this schema as the public-contract baseline'),
|
||||
'the Versioning note must record that v5.4 freezes the schema as the public-contract baseline');
|
||||
assert.ok(t.includes('froze `2.1` as the public-contract baseline'),
|
||||
'the Versioning note must record that v5.4 froze 2.1 as the public-contract baseline');
|
||||
});
|
||||
|
||||
// --- v5.5 — framing enforcement: brief_version 2.2 (Handover 1 contract evolution) ---
|
||||
// S6: the framing-alignment invariant (CLAUDE.md) ships as a controlled brief_version
|
||||
// bump 2.1→2.2 adding two required-at-2.2 elements (framing field + ## TL;DR section),
|
||||
// version-gated so 2.0/2.1 briefs stay valid. These pin the contract-doc evolution.
|
||||
|
||||
test('v5.5 — Handover 1 schema table adds the framing field row', () => {
|
||||
const t = read('docs/HANDOVER-CONTRACTS.md');
|
||||
assert.ok(t.includes('| `framing` |'),
|
||||
'HANDOVER-CONTRACTS must add a framing row to the Handover 1 schema table');
|
||||
assert.ok(t.includes('preserve \\| refine \\| replace \\| new-direction'),
|
||||
'the framing row must list the four canonical enum values');
|
||||
});
|
||||
|
||||
test('v5.5 — Handover 1 documents the framing gate + required-at-2.2 TL;DR section', () => {
|
||||
const t = read('docs/HANDOVER-CONTRACTS.md');
|
||||
assert.ok(t.includes('v5.5 framing gate'),
|
||||
'validation-strategy table must add a v5.5 framing gate row');
|
||||
assert.ok(/##\s*TL;DR.*required at `brief_version ≥ 2\.2`/.test(t) || t.includes('`## TL;DR` — **required at `brief_version ≥ 2.2`**'),
|
||||
'body-invariants must mark ## TL;DR as required at brief_version ≥ 2.2');
|
||||
});
|
||||
|
||||
test('v5.5 — Versioning note records the 2.2 framing-enforcement evolution', () => {
|
||||
const t = read('docs/HANDOVER-CONTRACTS.md');
|
||||
assert.ok(t.includes('v5.5 → `2.2` (framing enforcement)'),
|
||||
'the Versioning note must document the v5.5 → 2.2 framing-enforcement evolution');
|
||||
});
|
||||
|
||||
test('v5.5 — voyage README.md mentions framing enforcement / brief_version 2.2', () => {
|
||||
const t = read('README.md');
|
||||
assert.ok(t.includes('framing') && t.includes('brief_version 2.2'),
|
||||
'voyage README.md must carry a "What\'s new" note for framing enforcement (brief_version 2.2)');
|
||||
});
|
||||
|
|
|
|||
|
|
@ -250,3 +250,111 @@ test('validateBrief — v5.1.1: UNQUOTED brief_version 2.1 WITH phase_signals is
|
|||
assert.equal(r.valid, true, JSON.stringify(r.errors));
|
||||
assert.ok(!r.errors.find(e => e.code === 'BRIEF_V51_MISSING_SIGNALS'));
|
||||
});
|
||||
|
||||
// --- v5.5 — framing enforcement + obligatory TL;DR (gated at brief_version ≥ 2.2) ---
|
||||
// Operator decision (S6, option A1): framing + TL;DR are hard BLOCKERs for briefs
|
||||
// declaring brief_version ≥ 2.2; existing 2.0/2.1 briefs stay valid (forward-compat,
|
||||
// mirroring the phase_signals ≥ 2.1 precedent). The framing ENUM check fires on any
|
||||
// version when the field is present but malformed.
|
||||
|
||||
const GOOD_BRIEF_22 = `---
|
||||
type: trekbrief
|
||||
brief_version: "2.2"
|
||||
created: 2026-06-18
|
||||
task: "Add JWT auth to API"
|
||||
slug: jwt-auth
|
||||
project_dir: .claude/projects/2026-06-18-jwt-auth/
|
||||
research_topics: 0
|
||||
research_status: complete
|
||||
auto_research: false
|
||||
interview_turns: 5
|
||||
source: interview
|
||||
framing: new-direction
|
||||
phase_signals_partial: true
|
||||
---
|
||||
|
||||
# Task: JWT auth
|
||||
|
||||
## TL;DR
|
||||
|
||||
Net-new JWT auth; no prior brief to anchor against.
|
||||
|
||||
## Intent
|
||||
|
||||
Why this matters.
|
||||
|
||||
## Goal
|
||||
|
||||
What success looks like.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- All tests pass.
|
||||
`;
|
||||
|
||||
test('validateBrief — v5.5 well-formed 2.2 brief (framing + TL;DR) accepted', () => {
|
||||
const r = validateBriefContent(GOOD_BRIEF_22, { strict: true });
|
||||
assert.equal(r.valid, true, JSON.stringify(r.errors));
|
||||
});
|
||||
|
||||
test('validateBrief — v5.5 framing enum: invalid value rejected on any version', () => {
|
||||
const t = GOOD_BRIEF.replace('source: interview\n', 'source: interview\nframing: sideways\n');
|
||||
const r = validateBriefContent(t, { strict: true });
|
||||
assert.equal(r.valid, false);
|
||||
assert.ok(r.errors.find(e => e.code === 'BRIEF_INVALID_FRAMING'));
|
||||
});
|
||||
|
||||
test('validateBrief — v5.5 framing enum: all four canonical values accepted', () => {
|
||||
for (const v of ['preserve', 'refine', 'replace', 'new-direction']) {
|
||||
const t = GOOD_BRIEF_22.replace('framing: new-direction', `framing: ${v}`);
|
||||
const r = validateBriefContent(t, { strict: true });
|
||||
assert.equal(r.valid, true, `framing=${v}: ${JSON.stringify(r.errors)}`);
|
||||
}
|
||||
});
|
||||
|
||||
test('validateBrief — v5.5 brief_version 2.2 missing framing rejected (BRIEF_MISSING_FRAMING)', () => {
|
||||
const t = GOOD_BRIEF_22.replace('framing: new-direction\n', '');
|
||||
const r = validateBriefContent(t, { strict: true });
|
||||
assert.equal(r.valid, false);
|
||||
assert.ok(r.errors.find(e => e.code === 'BRIEF_MISSING_FRAMING'));
|
||||
});
|
||||
|
||||
test('validateBrief — v5.5 brief_version 2.2 missing ## TL;DR rejected (strict)', () => {
|
||||
const t = GOOD_BRIEF_22.replace(/## TL;DR\n\n[^\n]*\n\n/, '');
|
||||
const r = validateBriefContent(t, { strict: true });
|
||||
assert.equal(r.valid, false);
|
||||
assert.ok(r.errors.find(e => e.code === 'BRIEF_MISSING_SECTION' && /TL;DR/.test(e.message)));
|
||||
});
|
||||
|
||||
test('validateBrief — v5.5 brief_version 2.2 missing ## TL;DR demoted to warning (soft)', () => {
|
||||
const t = GOOD_BRIEF_22.replace(/## TL;DR\n\n[^\n]*\n\n/, '');
|
||||
const r = validateBriefContent(t, { strict: false });
|
||||
assert.ok(r.warnings.find(w => w.code === 'BRIEF_MISSING_SECTION' && /TL;DR/.test(w.message)));
|
||||
});
|
||||
|
||||
test('validateBrief — v5.5 TL;DR exceeding 5 lines emits BRIEF_TLDR_TOO_LONG warning', () => {
|
||||
const longTldr = ['l1', 'l2', 'l3', 'l4', 'l5', 'l6'].join('\n');
|
||||
const t = GOOD_BRIEF_22.replace('Net-new JWT auth; no prior brief to anchor against.', longTldr);
|
||||
const r = validateBriefContent(t, { strict: true });
|
||||
assert.ok(
|
||||
r.warnings.find(w => w.code === 'BRIEF_TLDR_TOO_LONG'),
|
||||
`expected TL;DR-too-long warning; warnings=${JSON.stringify(r.warnings)}`,
|
||||
);
|
||||
});
|
||||
|
||||
test('validateBrief — v5.5 backward-compat: 2.1 brief without framing/TL;DR stays valid', () => {
|
||||
const t = GOOD_BRIEF
|
||||
.replace('brief_version: "2.0"', 'brief_version: "2.1"')
|
||||
.replace('source: interview\n', 'source: interview\nphase_signals_partial: true\n');
|
||||
const r = validateBriefContent(t, { strict: true });
|
||||
assert.equal(r.valid, true, JSON.stringify(r.errors));
|
||||
assert.ok(!r.errors.find(e => e.code === 'BRIEF_MISSING_FRAMING'));
|
||||
assert.ok(!r.errors.find(e => e.code === 'BRIEF_MISSING_SECTION' && /TL;DR/.test(e.message)));
|
||||
});
|
||||
|
||||
test('validateBrief — v5.5 trekreview brief not subject to framing/TL;DR gate', () => {
|
||||
const r = validateBriefContent(REVIEW_AS_BRIEF, { strict: true });
|
||||
assert.equal(r.valid, true, JSON.stringify(r.errors));
|
||||
assert.ok(!r.errors.find(e => e.code === 'BRIEF_MISSING_FRAMING'));
|
||||
assert.ok(!r.errors.find(e => e.code === 'BRIEF_MISSING_SECTION' && /TL;DR/.test(e.message)));
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue