feat(ms-ai-architect): Spor D N1–N5 — Anthropic-deterministiske skill-sjekker (TDD) [skip-docs]

Legger de fem deterministiske sjekkene fra Anthropics «Skill authoring best
practices» som K1–K10-rubrikken manglet, i begge lag av score-motoren:

- eval.mjs (disk-laget): extractName + checkN1..checkN5
  - N1 name-validitet (≤64, a-z0-9-, ingen «claude»/«anthropic»; gerund rapporteres, gater ikke)
  - N2 description ikke-tom + ≤1024 tegn
  - N3 refs én nivå dypt (ref-fil lenker ikke til annen ref-fil)
  - N4 TOC i ref-filer >100 linjer (delpoeng = andel store filer med TOC)
  - N5 forward-slash-stier (ingen Windows-backslash-stier i body)
  wiret inn i evalSkill.deterministic (leser nå ref-fil-innhold for N3/N4)
- lib/skill-score.mjs (ren): N1–N5 i CRITERIA (vekt 1, ikke-gulv, det)

Live-sanity mot de 5 skills: N1/N2/N5 rene, N3 fanger ekte nøstet ref i
advisor (licensing-matrix.md → 3 andre ref-filer), N4 avdekker 387 store
ref-filer uten TOC (primær forbedringsspak for oppgraderingsfasen).

Tester: kb-eval 110→134 (+24). validate 239, kb-update 316 uendret grønt.
[skip-docs]: N1–N5 alt spesifisert i docs/skill-quality-scoring-plan.md §2.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/kb-eval/test-eval.test.mjs

@@ -6,10 +6,16 @@ import assert from 'node:assert/strict';
 import {
   splitFrontmatter,
   extractDescription,
+  extractName,
   checkK2,
   checkK3,
   checkK5K6,
   checkRefConsistency,
+  checkN1,
+  checkN2,
+  checkN3,
+  checkN4,
+  checkN5,
 } from '../../scripts/kb-eval/eval.mjs';
 
 test('splitFrontmatter — separates frontmatter from body', () => {
@@ -100,3 +106,126 @@ test('checkRefConsistency — same folder cited with two different numbers flags
   const r = checkRefConsistency(body, { foo: 24 });
   assert.equal(r.consistent, false);
 });
+
+// --- N1-N5: deterministic checks added from Anthropic best-practices ---------
+
+test('extractName — pulls the name scalar from frontmatter', () => {
+  const fm = '---\nname: ms-ai-advisor\ndescription: x\n---\n';
+  assert.equal(extractName(fm), 'ms-ai-advisor');
+});
+
+test('extractName — missing name returns empty string', () => {
+  assert.equal(extractName('---\ndescription: x\n---\n'), '');
+});
+
+test('checkN1 — valid lowercase-hyphen name passes', () => {
+  const r = checkN1('ms-ai-advisor');
+  assert.equal(r.pass, true);
+  assert.equal(r.withinLength, true);
+  assert.equal(r.validChars, true);
+  assert.equal(r.noReserved, true);
+});
+
+test('checkN1 — name over 64 chars fails on length', () => {
+  const r = checkN1('a'.repeat(65));
+  assert.equal(r.withinLength, false);
+  assert.equal(r.pass, false);
+});
+
+test('checkN1 — uppercase, spaces or underscores are invalid chars', () => {
+  assert.equal(checkN1('Ms-AI Advisor').validChars, false);
+  assert.equal(checkN1('ms_ai_advisor').pass, false);
+});
+
+test('checkN1 — reserved words claude/anthropic fail', () => {
+  assert.equal(checkN1('claude-helper').noReserved, false);
+  assert.equal(checkN1('claude-helper').pass, false);
+  assert.equal(checkN1('anthropic-tool').pass, false);
+});
+
+test('checkN1 — gerund is reported but does not gate pass (real skills are non-gerund)', () => {
+  const r = checkN1('ms-ai-advisor');
+  assert.equal(r.gerund, false);
+  assert.equal(r.pass, true); // non-gerund still passes
+});
+
+test('checkN2 — non-empty description within 1024 chars passes', () => {
+  const r = checkN2('A normal, useful description.');
+  assert.equal(r.nonEmpty, true);
+  assert.equal(r.withinLimit, true);
+  assert.equal(r.pass, true);
+});
+
+test('checkN2 — empty/whitespace description fails', () => {
+  const r = checkN2('   ');
+  assert.equal(r.nonEmpty, false);
+  assert.equal(r.pass, false);
+});
+
+test('checkN2 — description over 1024 chars fails', () => {
+  const r = checkN2('x'.repeat(1025));
+  assert.equal(r.withinLimit, false);
+  assert.equal(r.pass, false);
+});
+
+test('checkN3 — a ref file linking to another .md flags nesting', () => {
+  const refs = [{ path: 'references/a.md', content: 'see [b](b.md) for more' }];
+  const r = checkN3(refs);
+  assert.equal(r.pass, false);
+  assert.equal(r.nested.length, 1);
+  assert.equal(r.nested[0].file, 'references/a.md');
+});
+
+test('checkN3 — ref files with only external (http) links pass', () => {
+  const refs = [{ path: 'references/a.md', content: 'see [docs](https://x.com/y) and [t](#anchor)' }];
+  assert.equal(checkN3(refs).pass, true);
+});
+
+test('checkN3 — a ref file with no links passes', () => {
+  assert.equal(checkN3([{ path: 'references/a.md', content: 'plain prose only' }]).pass, true);
+});
+
+test('checkN4 — large file without TOC fails and ratio reflects coverage', () => {
+  const big = '# T\n' + 'line\n'.repeat(150);
+  const r = checkN4([{ path: 'references/a.md', content: big }]);
+  assert.equal(r.largeFiles, 1);
+  assert.equal(r.withToc, 0);
+  assert.equal(r.ratio, 0);
+  assert.equal(r.pass, false);
+});
+
+test('checkN4 — large file with an explicit TOC heading passes', () => {
+  const big = '# T\n\n## Innhold\n- [A](#a)\n- [B](#b)\n' + 'body\n'.repeat(150);
+  const r = checkN4([{ path: 'references/a.md', content: big }]);
+  assert.equal(r.withToc, 1);
+  assert.equal(r.ratio, 1);
+  assert.equal(r.pass, true);
+});
+
+test('checkN4 — large file with an in-page anchor-link cluster near the top passes', () => {
+  const big = '# T\n- [A](#a)\n- [B](#b)\n- [C](#c)\n' + 'body\n'.repeat(150);
+  const r = checkN4([{ path: 'references/a.md', content: big }]);
+  assert.equal(r.withToc, 1);
+  assert.equal(r.pass, true);
+});
+
+test('checkN4 — files at or under 100 lines are not required to have a TOC (vacuous pass)', () => {
+  const r = checkN4([{ path: 'references/a.md', content: 'short\nfile\n' }]);
+  assert.equal(r.largeFiles, 0);
+  assert.equal(r.ratio, 1);
+  assert.equal(r.pass, true);
+});
+
+test('checkN5 — forward-slash paths pass', () => {
+  assert.equal(checkN5('See references/foo/bar.md for detail.').pass, true);
+});
+
+test('checkN5 — Windows backslash path fails', () => {
+  const r = checkN5('Open references\\foo\\bar.md now.');
+  assert.equal(r.pass, false);
+  assert.ok(r.windowsPaths.length >= 1);
+});
+
+test('checkN5 — drive-letter path fails', () => {
+  assert.equal(checkN5('Save to C:\\Users\\x\\file.md').pass, false);
+});

tests/kb-eval/test-skill-score.test.mjs

@@ -21,6 +21,11 @@ function perfectEval(overrides = {}) {
       refCountConsistency: { consistent: true, mismatches: [] },
       K9_timeSensitiveHints: { timeSensitiveTokenHits: 0 },
       K10_siblingScopeOverlap: { maxCombined: 2.0, worstSibling: 'x', pass: true, threshold: 7.0 },
+      N1_nameValidity: { pass: true },
+      N2_descriptionLength: { pass: true, length: 500 },
+      N3_refNestingDepth: { pass: true, nested: [] },
+      N4_refToc: { largeFiles: 5, withToc: 5, ratio: 1, pass: true },
+      N5_forwardSlashPaths: { pass: true, windowsPaths: [] },
     },
     judgeInputs: { description: 'desc', bodyLines: 120 },
     judge: {
@@ -126,6 +131,47 @@ test('scoreSkill — every improvement carries a concrete fix string', () => {
   assert.ok(k3 && typeof k3.fix === 'string' && k3.fix.length > 0);
 });
 
+test('scoreSkill — N1-N5 deterministic criteria are all scored on a perfect eval', () => {
+  const r = scoreSkill(perfectEval());
+  for (const key of ['N1', 'N2', 'N3', 'N4', 'N5']) {
+    const c = r.criteria.find((x) => x.key === key);
+    assert.ok(c && c.available, `${key} should be an available criterion`);
+    assert.equal(c.source, 'det', `${key} is deterministic`);
+    assert.equal(c.floor, false, `${key} is not a floor criterion`);
+  }
+  assert.equal(r.score, 100, 'all N1-N5 passing keeps the perfect score');
+});
+
+test('scoreSkill — N4 (TOC) gives partial credit proportional to coverage ratio', () => {
+  const r = scoreSkill(perfectEval({
+    deterministic: { N4_refToc: { largeFiles: 4, withToc: 2, ratio: 0.5, pass: false } },
+  }));
+  const n4 = r.criteria.find((c) => c.key === 'N4');
+  assert.ok(Math.abs(n4.sub - 0.5) < 1e-9, `N4 sub was ${n4.sub}`);
+  assert.equal(r.floored, false, 'N4 is not a floor criterion');
+  assert.ok(r.score < 100 && r.score > FLOOR_CAP, `expected high-but-imperfect, got ${r.score}`);
+  assert.ok(r.improvements.some((i) => i.key === 'N4'));
+});
+
+test('scoreSkill — an invalid name (N1) is a non-floor miss that lands in improvements', () => {
+  const r = scoreSkill(perfectEval({
+    deterministic: { N1_nameValidity: { pass: false } },
+  }));
+  const n1 = r.criteria.find((c) => c.key === 'N1');
+  assert.equal(n1.sub, 0);
+  assert.equal(r.floored, false, 'N1 does not floor the score');
+  assert.ok(r.meetsTarget, 'a single non-floor binary miss should not drop below 90');
+  assert.ok(r.improvements.some((i) => i.key === 'N1' && typeof i.fix === 'string'));
+});
+
+test('scoreSkill — nested references (N3) reduce the score', () => {
+  const r = scoreSkill(perfectEval({
+    deterministic: { N3_refNestingDepth: { pass: false, nested: [{ file: 'references/a.md', links: ['b.md'] }] } },
+  }));
+  assert.ok(r.score < 100);
+  assert.ok(r.improvements.some((i) => i.key === 'N3'));
+});
+
 test('scoreSkill — tolerates a null/garbage eval object without throwing', () => {
   assert.equal(scoreSkill(null), null);
   assert.equal(scoreSkill({}), null);