docs: [verified] move metric contracts under Measurement

scripts/browser/measurement-pages.cjs

@@ -0,0 +1,79 @@
+const {chromium} = require('playwright');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+(async () => {
+  const base = process.argv[2] || 'http://127.0.0.1:4173';
+  const prefix = '/eldorado-v1/documentation';
+  const manifest = JSON.parse(fs.readFileSync('research/ai-adoption/measurement-migration.json','utf8'));
+  const output = `.cache/metric-pages-${process.argv[3] || 'local'}`;
+  fs.mkdirSync(output,{recursive:true});
+  const browser = await chromium.launch({headless:true,executablePath:process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE,args:['--no-sandbox']});
+  const results = [];
+  try {
+    for (const width of [1440,390]) {
+      const context = await browser.newContext({viewport:{width,height:900}});
+      try {
+        const page = await context.newPage();
+        const errors = [];
+        page.on('pageerror',e => errors.push(e.message));
+        for (const m of manifest.metrics) {
+          const url = `${base}${prefix}${m.url}`;
+          assert.equal((await page.goto(url,{waitUntil:'networkidle'})).status(),200);
+          assert.equal(await page.locator('article h1').innerText(),m.title);
+          assert.equal(await page.locator('link[rel="canonical"]').getAttribute('href'),`https://pages.apps.lego-cloud.eu${prefix}${m.url}`);
+          const table = page.locator('article table');
+          assert.equal(await table.count(),1);
+          assert.equal(await table.locator('tbody tr').count(),11);
+          const article = await page.locator('article').innerText();
+          assert(article.includes(m.status === 'prototype' ? 'Prototype calculation' : 'Unimplemented metric'));
+          assert(article.includes('no live telemetry'));
+          assert.equal(await page.locator('.breadcrumbs a').filter({hasText:'Measurement'}).getAttribute('href'),`${prefix}/strategy/measurement/`);
+          assert(!await page.evaluate(() => document.documentElement.scrollWidth > innerWidth));
+          await page.goto(`${base}${prefix}/strategy/reference/measurement-contracts/#${m.oldAnchor}`,{waitUntil:'networkidle'});
+          await page.waitForURL(url);
+          await page.locator('article h1').waitFor();
+          results.push({width,metric:m.oldAnchor,canonical:true,redirect:true,fields:11});
+        }
+        for (const suffix of ['', '#unknown-anchor', '#__proto__']) {
+          await page.goto(`${base}${prefix}/strategy/reference/measurement-contracts/${suffix}`,{waitUntil:'networkidle'});
+          await page.waitForURL(`${base}${prefix}/strategy/measurement/`);
+        }
+        for (const [anchor,target] of [
+          ['collection-and-safeguards','collection-and-safeguards/'],
+          ['decide-what-counts-before-counting','collection-and-safeguards/#decide-what-counts-before-counting'],
+          ['baseline-and-interpretation','collection-and-safeguards/#baseline-and-interpretation'],
+          ['event-and-privacy-contract','collection-and-safeguards/#event-and-privacy-contract'],
+          ['run-the-synthetic-measurement-example','synthetic-example/'],
+          ['metric-contracts','#metric-definitions'],
+        ]) {
+          await page.goto(`${base}${prefix}/strategy/reference/measurement-contracts/#${anchor}`,{waitUntil:'networkidle'});
+          await page.waitForURL(`${base}${prefix}/strategy/measurement/${target}`);
+          if (target.includes('#')) await page.locator(`#${target.split('#')[1]}`).waitFor();
+        }
+        await page.goto(`${base}${prefix}/strategy/measurement/supported-bundle-coverage/`,{waitUntil:'networkidle'});
+        await page.locator('.breadcrumbs a').filter({hasText:'Measurement'}).click();
+        await page.waitForURL(`${base}${prefix}/strategy/measurement/`);
+        if (width < 997) await page.getByRole('button',{name:'Toggle navigation bar'}).click();
+        const menu = page.locator('.theme-doc-sidebar-menu').filter({visible:true});
+        const category = menu.locator('.theme-doc-sidebar-item-category').filter({has:page.getByRole('link',{name:'Measurement',exact:true})}).last();
+        const caret = category.locator(':scope > .menu__list-item-collapsible > button.menu__caret');
+        await caret.click();
+        await category.getByRole('link',{name:'Validated task success',exact:true}).waitFor({state:'hidden'});
+        await caret.focus(); await page.keyboard.press('Enter');
+        await category.getByRole('link',{name:'Validated task success',exact:true}).waitFor({state:'visible'});
+        await menu.getByRole('link',{name:'Measurement',exact:true}).click();
+        await page.waitForURL(`${base}${prefix}/strategy/measurement/`);
+        await page.locator('article h1').waitFor();
+        if (width < 997) await page.getByRole('button',{name:'Close navigation bar'}).waitFor({state:'hidden'});
+        await page.locator('#metric-definitions').scrollIntoViewIfNeeded();
+        await page.screenshot({path:`${output}/${width}-index.png`});
+        await page.goto(`${base}${prefix}/strategy/measurement/supported-bundle-coverage/`,{waitUntil:'networkidle'});
+        await page.screenshot({path:`${output}/${width}-metric.png`,fullPage:true});
+        assert.deepEqual(errors,[]);
+      } finally {await context.close();}
+    }
+    assert.equal(results.length,32);
+    fs.writeFileSync(`${output}/results.json`,JSON.stringify(results,null,2));
+    console.log('PASS: 16 metric pages × 2 widths; canonical metadata, contract fields, status, all legacy metric/shared/fallback redirects and linked Measurement keyboard navigation');
+  } finally {await browser.close();}
+})().catch(e => {console.error(e);process.exitCode=1;});

scripts/browser/sidebar-coverage.cjs

@@ -43,18 +43,19 @@ const fs = require('node:fs');
         }
         const reference = '/eldorado-v1/documentation/strategy/reference/measurement-contracts/';
         await page.goto(`${base}${reference}#supported-bundle-coverage`, {waitUntil:'networkidle'});
-        await page.locator('#supported-bundle-coverage').waitFor();
+        await page.waitForURL(`${base}/eldorado-v1/documentation/strategy/measurement/supported-bundle-coverage/`);
+        await page.getByRole('heading', {level:1, name:'Supported bundle coverage', exact:true}).waitFor();
         assert((await page.locator('article').innerText()).includes('Supported bundle coverage'));
         assert.equal(await page.locator('.breadcrumbs a').filter({hasText:'Stage - 01 - Skills Adoption'}).getAttribute('href'), '/eldorado-v1/documentation/strategy/stage-01-skills-adoption/');
-        assert((await page.locator('.breadcrumbs').innerText()).includes('Reference'));
+        assert((await page.locator('.breadcrumbs').innerText()).includes('Measurement'));
         await open();
-        await menu.getByRole('link', {name:'Measurement Contracts', exact:true}).waitFor({state:'visible'});
+        await menu.getByRole('link', {name:'Supported bundle coverage', exact:true}).waitFor({state:'visible'});
         await page.screenshot({path:`${output}/${width}-reference.png`, animations:'disabled'});
         assert.deepEqual(errors, []);
       } finally {await context.close();}
     }
     assert.equal(results.length, documents.length * 3);
     fs.writeFileSync(`${output}/results.json`, JSON.stringify(results,null,2));
-    console.log(`PASS: all ${documents.length} docs have visible unique sidebar entries at 3 viewports; Contribution links, Reference breadcrumbs and reported anchor work`);
+    console.log(`PASS: all ${documents.length} docs have visible unique sidebar entries at 3 viewports; Contribution links, Measurement breadcrumbs and reported anchor redirect work`);
   } finally {await browser.close();}
 })().catch(e => {console.error(e); process.exitCode = 1;});

scripts/browser/skills-measurement.cjs

@@ -18,11 +18,12 @@ const fs = require('node:fs');
       assert.equal(await page.locator('h1').innerText(), 'Skills Measurement');
       assert((await page.title()).startsWith('Skills Measurement |'));
       assert.equal(await page.locator('.strategy-content details').count(), 0);
-      assert.equal(await page.locator('.strategy-content h2').count(), 4);
+      assert.equal(await page.locator('.strategy-content h2').count(), 5);
       if (width < 700) await page.getByRole('button', {name:'Toggle navigation bar'}).click();
       const menu = page.locator('.theme-doc-sidebar-menu .menu__link').filter({visible:true});
       await menu.first().waitFor({state:'visible'});
-      assert.deepEqual(await menu.allTextContents(), ['Target','Roadmap','Stage - 01 - Skills Adoption','Governance','Quality','Adoption','Measurement','Maintenance','Reference','Stage - 02 - Autonomous Agent']);
+      const metrics = JSON.parse(fs.readFileSync('research/ai-adoption/measurement-migration.json','utf8')).metrics;
+      assert.deepEqual(await menu.allTextContents(), ['Target','Roadmap','Stage - 01 - Skills Adoption','Governance','Quality','Adoption','Measurement',...metrics.map(m => m.title),'Collection and safeguards','Run the synthetic measurement example','Maintenance','Stage - 02 - Autonomous Agent']);
       if (width < 700) await page.getByRole('button', {name:'Close navigation bar'}).click();
       const panel = page.locator('.archify-panel--story');
       const iframe = panel.locator(width > 700 ? '.story-desktop' : '.story-mobile');
@@ -65,15 +66,14 @@ const fs = require('node:fs');
       await page.locator('.strategy-content h2').nth(1).scrollIntoViewIfNeeded();
       await page.screenshot({path:`${output}/${width}-pilot.png`});
       await page.screenshot({path:`${output}/${width}-full.png`, fullPage:true});
-      const links = await page.locator('.strategy-content a[href*="measurement-contracts"]').evaluateAll(nodes => nodes.map(n => n.href));
+      const links = await page.locator('.strategy-content a[href*="/measurement/"]').evaluateAll(nodes => nodes.map(n => n.href));
       for (const href of [...new Set(links)]) {
         const navigation = await page.goto(href, {waitUntil:'networkidle'});
         if (navigation) assert.equal(navigation.status(), 200);
         assert.equal(page.url(), href);
         if (new URL(href).hash) await page.locator(new URL(href).hash).waitFor({state:'visible'});
       }
-      assert.equal(await page.locator('.strategy-content h3').count(), 19);
-      assert((await page.locator('.strategy-content').innerText()).includes('9 prototype calculations and 7 unimplemented metrics'));
+      assert.equal(new Set(links.map(h => new URL(h).pathname)).size, 18);
       assert(!await page.evaluate(() => document.documentElement.scrollWidth > innerWidth));
       assert.deepEqual(errors, []);
       results.push({width, geometry, links:links.length, title:true, sidebar:true, controls:true, export:true, reference:true});

scripts/browser/strategy-navigation.cjs

@@ -8,9 +8,12 @@ const fs = require('node:fs');
   const prefix = '/eldorado-v1/documentation/strategy/';
   const first = 'Stage - 01 - Skills Adoption';
   const second = 'Stage - 02 - Autonomous Agent';
-  const topics = ['Governance','Quality','Adoption','Measurement','Maintenance','Reference'];
-  const ids = ['target-operating-model','roadmap','stage-01-skills-adoption','skills-governance','skills-quality','skills-adoption','measurement','skills-maintenance','reference/measurement-contracts','stage-02-autonomous-agent'];
-  const titles = ['Target','Roadmap',first,'Skills governance','Skills quality','Skills adoption','Skills Measurement','Skills maintenance','Skills KPI reference',second];
+  const topics = ['Governance','Quality','Adoption','Measurement','Maintenance'];
+  const metrics = JSON.parse(fs.readFileSync('research/ai-adoption/measurement-migration.json','utf8')).metrics;
+  const childIds = [...metrics.map(m => m.docId),'measurement/collection-and-safeguards','measurement/synthetic-example'];
+  const childTitles = [...metrics.map(m => m.title),'Collection and safeguards','Run the synthetic measurement example'];
+  const ids = ['target-operating-model','roadmap','stage-01-skills-adoption','skills-governance','skills-quality','skills-adoption','measurement',...childIds,'skills-maintenance','stage-02-autonomous-agent'];
+  const titles = ['Target','Roadmap',first,'Skills governance','Skills quality','Skills adoption','Skills Measurement',...childTitles,'Skills maintenance',second];
   const browser = await chromium.launch({headless:true, executablePath:process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE, args:['--no-sandbox']});
   const results = [];
   try {
@@ -39,11 +42,12 @@ const fs = require('node:fs');
         await category.getByRole('link', {name:'Governance', exact:true}).waitFor({state:'visible'});
         assert.deepEqual(await visibleLabels(), ['Target','Roadmap',first,...topics,second]);
         assert.deepEqual(await category.locator('ul .menu__link').filter({visible:true}).allTextContents(), topics);
-        const reference = category.getByRole('button', {name:'Reference', exact:true});
+        const measurement = category.locator('.theme-doc-sidebar-item-category').filter({has:page.getByRole('link', {name:'Measurement', exact:true})});
+        const reference = measurement.locator(':scope > .menu__list-item-collapsible > button.menu__caret');
         await reference.focus();
         await page.keyboard.press('Enter');
-        await category.getByRole('link', {name:'Measurement Contracts', exact:true}).waitFor({state:'visible'});
-        assert.deepEqual(await visibleLabels(), ['Target','Roadmap',first,...topics,'Measurement Contracts',second]);
+        await category.getByRole('link', {name:'Validated task success', exact:true}).waitFor({state:'visible'});
+        assert.deepEqual(await visibleLabels(), ['Target','Roadmap',first,...topics.slice(0,4),...childTitles,'Maintenance',second]);
         await reference.click();
         await page.screenshot({path:`${output}/${width}-expanded.png`, animations:'disabled'});
         await caret.click();
@@ -68,10 +72,12 @@ const fs = require('node:fs');
           else assert.equal(await prev.count(), 0);
           if (index < ids.length-1) assert.equal(await next.getAttribute('href'), `${prefix}${ids[index+1]}/`);
           else assert.equal(await next.count(), 0);
-          if (index >= 3 && index <= 7) {
+          if (index >= 3 && index < ids.length - 1) {
             assert.equal(await page.locator('.breadcrumbs a').filter({hasText:first}).getAttribute('href'), `${prefix}stage-01-skills-adoption/`);
             menu = await openMenu();
-            assert.deepEqual(await visibleLabels(), ['Target','Roadmap',first,...topics,second]);
+            const expectedTopics = id === 'measurement' || id.startsWith('measurement/') ? [...topics.slice(0,4),...childTitles,'Maintenance'] : topics;
+            assert.deepEqual(await visibleLabels(), ['Target','Roadmap',first,...expectedTopics,second]);
+            if (id.startsWith('measurement/')) assert.equal(await page.locator('.breadcrumbs a').filter({hasText:'Measurement'}).getAttribute('href'), `${prefix}measurement/`);
             await closeMenu();
           }
           assert(!await page.evaluate(() => document.documentElement.scrollWidth > innerWidth), `${width}: overflow on ${id}`);
@@ -84,6 +90,6 @@ const fs = require('node:fs');
       } finally {await context.close();}
     }
     assert.equal(results.length, 4);
-    console.log('PASS: 4 desktop/mobile viewports; all 10 routes; linked category, keyboard expansion, nested Reference, breadcrumbs, next/previous and no overflow/errors');
+    console.log(`PASS: 4 desktop/mobile viewports; all ${ids.length} routes; linked Measurement category, keyboard expansion, breadcrumbs, next/previous and no overflow/errors`);
   } finally {await browser.close();}
 })().catch(error => {console.error(error); process.exitCode = 1;});

scripts/browser/strategy-story.cjs

@@ -24,7 +24,7 @@ const fs=require('node:fs');
    assert.equal(geometry.nodes.length,(source.components||source.nodes).length,id);
    for(const n of geometry.nodes) assert(n.x>=0 && n.y>=0 && n.right<=geometry.width+1 && n.bottom<=geometry.height+1,`${id} ${width} clipped ${JSON.stringify(n)} / ${geometry.height}`);
    const data=await page.locator('.strategy-content').evaluate(el=>({words:el.innerText.trim().split(/\s+/).length,overflow:document.documentElement.scrollWidth>innerWidth,openDetails:el.querySelectorAll('details[open]').length}));
-   assert(data.words<=(id==='measurement'?1100:id==='roadmap'?600:200),id);assert(!data.overflow,id);assert.equal(data.openDetails,0,id);
+   assert(data.words<=(id==='measurement'?1500:id==='roadmap'?600:200),id);assert(!data.overflow,id);assert.equal(data.openDetails,0,id);
    await page.evaluate(()=>scrollTo({top:0,behavior:'instant'}));await page.screenshot({path:`.cache/story-${label}/${width}-${id}.png`,fullPage:true});
    const opener=panel.getByRole('button',{name:/^Expand /});await opener.click();
    const close=panel.getByRole('button',{name:'Close full-screen diagram',exact:true});await close.waitFor({state:'visible'});
@@ -44,7 +44,8 @@ const fs=require('node:fs');
    results.push({id,width,...data,geometry,modalClick:true,modalEscape:true,focusRestored:true,details:id!=='measurement'});fs.writeFileSync(`.cache/story-${label}/results.json`,JSON.stringify(results,null,2));
   }
   await page.goto(`${base}/eldorado-v1/documentation/strategy/reference/measurement-contracts/#validated-task-success`,{waitUntil:'networkidle'});
-  const heading=page.locator('#validated-task-success');await heading.waitFor({state:'visible'});
+  await page.waitForURL(`${base}/eldorado-v1/documentation/strategy/measurement/validated-task-success/`);
+  await page.getByRole('heading',{level:1,name:'Validated task success',exact:true}).waitFor();
   assert.equal(await page.locator('.strategy-content details').count(),0,'reference is directly readable');
   await context.close();
  }

scripts/measurement-pages.mjs

@@ -0,0 +1,38 @@
+import assert from 'node:assert/strict';
+import {readFileSync, readdirSync} from 'node:fs';
+import {runInNewContext} from 'node:vm';
+const read = p => readFileSync(p, 'utf8');
+
+export function verifyMeasurementPages() {
+  const manifest = JSON.parse(read('research/ai-adoption/measurement-migration.json'));
+  const {documents, exclusions} = JSON.parse(read('.cache/sidebar-coverage.json'));
+  const prefix = '/eldorado-v1/documentation';
+  const legacy = 'strategy/reference/measurement-contracts/index.html';
+  assert.equal(exclusions.filter(e => e.file === legacy).length, 1);
+  assert(!documents.some(d => d.id === 'reference/measurement-contracts'));
+  const search = readdirSync('build').filter(f => /^search-index.*\.json$/.test(f)).map(f => read(`build/${f}`)).join('\n');
+  assert(!search.includes('/strategy/reference/measurement-contracts/'));
+  const children = [...manifest.metrics.map(m => ({...m,slug:m.oldAnchor})),
+    {slug:'collection-and-safeguards',title:'Collection and safeguards'},
+    {slug:'synthetic-example',title:'Run the synthetic measurement example'},
+  ];
+  for (const child of children) {
+    const route = `${prefix}/strategy/measurement/${child.slug}/`;
+    const doc = documents.filter(d => `${d.route}/` === route);
+    assert.equal(doc.length,1);
+    assert.equal(doc[0].id, `measurement/${child.slug}`);
+    const page = read(`build/strategy/measurement/${child.slug}/index.html`);
+    const canonical = [...page.matchAll(/<link\b[^>]*rel="canonical"[^>]*>/g)];
+    assert.equal(canonical.length,1);
+    assert(canonical[0][0].includes(`href="https://pages.apps.lego-cloud.eu${route}"`));
+    assert(search.includes(route), `Missing search route: ${route}`);
+    assert(!page.includes(`${prefix}/strategy/reference/measurement-contracts/`));
+  }
+  const script = read(`build/${legacy}`).match(/<script>([\s\S]*?)<\/script>/)[1];
+  for (const m of manifest.metrics) {
+    let destination;
+    runInNewContext(script,{window:{location:{hash:`#${m.oldAnchor}`,replace:url => {destination=url;}}}});
+    assert.equal(destination,`${prefix}${m.url}`);
+  }
+  console.log('PASS: 18 canonical Measurement children, exact IDs, search membership and 16 hash redirects; no legacy document/index duplication');
+}

scripts/measurement-pages.test.mjs

@@ -0,0 +1,42 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {readFileSync, existsSync, readdirSync} from 'node:fs';
+import {createHash} from 'node:crypto';
+import {calculate} from './ai-kpi.mjs';
+const read = p => readFileSync(p, 'utf8');
+
+test('each original metric survives exactly once on its own canonical Measurement page', () => {
+  const manifest = JSON.parse(read('research/ai-adoption/measurement-migration.json'));
+  const model = JSON.parse(read('research/ai-adoption/strategy-model.json'));
+  const report = calculate(JSON.parse(read('scripts/fixtures/ai-kpi-synthetic.json')));
+  assert.equal(manifest.metrics.length, 16);
+  assert.deepEqual(manifest.metrics.map(m => m.title), model.kpis.map(k => k.name));
+  assert.equal(new Set(manifest.metrics.map(m => m.docId)).size, 16);
+  assert.equal(manifest.metrics.filter(m => m.status === 'prototype').length, 9);
+  assert.equal(manifest.metrics.filter(m => m.status === 'unimplemented').length, 7);
+  const overview = read('docs/strategy/measurement/index.mdx');
+  for (const metric of manifest.metrics) {
+    const page = read(`docs/strategy/${metric.docId}.mdx`);
+    assert.equal(metric.url, `/strategy/${metric.docId}/`);
+    assert.equal(metric.oldAnchor, metric.docId.split('/').at(-1));
+    assert(page.includes(`slug: /${metric.docId}`));
+    assert(overview.includes(`./${metric.oldAnchor}.mdx`));
+    assert(page.includes('./collection-and-safeguards.mdx'));
+    assert(page.includes('not installed collection'));
+    assert(page.includes(metric.status === 'prototype' ? 'Prototype calculation' : 'Unimplemented metric'));
+    assert.equal(Object.hasOwn(report.kpis, metric.calculationId), metric.status === 'prototype');
+    const contract = page.split('{/* contract:start */}\n')[1]?.split('\n{/* contract:end */}')[0];
+    assert(contract, metric.title);
+    assert.equal(createHash('sha256').update(contract).digest('hex'), metric.contractSha256, metric.title);
+    for (const field of ['Numerator','Denominator','Expression','Aggregation','Unit','Eligible population','Exclusions','Events and source','Owner / cadence','Missing evidence','Gaming and limits']) assert.equal(contract.split(`| ${field} |`).length, 2, `${metric.title}: ${field}`);
+  }
+  assert.equal(readdirSync('docs/strategy/measurement').filter(p => p.endsWith('.mdx')).length, 19);
+  assert(!existsSync('docs/strategy/reference/measurement-contracts.mdx'));
+  for (const part of manifest.shared) {
+    const page = read(`docs/strategy/measurement/${part.slug}.mdx`);
+    const body = page.split('{/* preserved:start */}\n')[1]?.split('\n{/* preserved:end */}')[0];
+    // Only the cross-page navigation wording changes; hash all original substance.
+    const original = body.replace('Use the [metric definitions](./index.mdx#metric-definitions)', 'Use the metric contracts below');
+    assert.equal(createHash('sha256').update(original).digest('hex'), part.sha256);
+  }
+});

scripts/roadmap.test.mjs

@@ -13,7 +13,7 @@ test('Roadmap has three visual levels and preserves human direction and Delivery
   const visible = page.split('<details>')[0];
   assert.deepEqual([...visible.matchAll(/<ArchifyDiagram name="([^"]+)"/g)].map(m => m[1]), Object.keys(views));
   assert.deepEqual([...visible.matchAll(/^## (.+)$/gm)].map(m => m[1]), ['Two stages toward Target', 'Stage 1: Delivery first', 'Improve within each phase', 'Delivery in practice']);
-  for (const marker of ['Humans direct, guide and review throughout', 'standardizes skills', 'foundation for Stage 2', 'future Autonomous Agent', 'not deployed autonomy', 'order is not yet decided', 'Delivery keeps improving', 'not as six global roadmap stages', 'what skills exist, how they relate, when they are used and how they work together', 'codebase structure', 'existing principles', 'system-logic source', 'tests', 'builds and packaging', 'deployments', 'practices, tooling, controls and problems', 'metrics/KPIs and a baseline', 'friction and feedback', './measurement.mdx', './target-operating-model.mdx']) assert(visible.includes(marker), marker);
+  for (const marker of ['Humans direct, guide and review throughout', 'standardizes skills', 'foundation for Stage 2', 'future Autonomous Agent', 'not deployed autonomy', 'order is not yet decided', 'Delivery keeps improving', 'not as six global roadmap stages', 'what skills exist, how they relate, when they are used and how they work together', 'codebase structure', 'existing principles', 'system-logic source', 'tests', 'builds and packaging', 'deployments', 'practices, tooling, controls and problems', 'metrics/KPIs and a baseline', 'friction and feedback', './measurement/index.mdx', './target-operating-model.mdx']) assert(visible.includes(marker), marker);
   for (const marker of ['revocation','exact-artifact approvals','idempotency','human takeover','sensitive decisions','security findings','reproducible baseline']) assert(page.includes(marker), marker);
   assert(!/## [1-5]\.|Prepare foundations|Sustain and improve/.test(page));
 });

scripts/sidebar-coverage.mjs

@@ -82,6 +82,11 @@ export async function verifySidebarCoverage() {
     else if (file === 'strategy/index.html') {
       assert(readFileSync(join('build',file),'utf8').includes('http-equiv="refresh"'), 'Strategy alias must remain a redirect');
       reason = 'Legacy Strategy redirect alias to Target';
+    } else if (file === 'strategy/reference/measurement-contracts/index.html') {
+      const body = readFileSync(join('build',file),'utf8');
+      assert(body.includes('window.location.replace') && body.includes('name="robots" content="noindex"') && !body.includes('<article'), 'Metric alias must remain a non-indexed redirect');
+      assert.equal(body, readFileSync(join('static',file),'utf8'));
+      reason = 'Legacy measurement-contracts hash-aware redirect to canonical Measurement pages';
     } else if (file.startsWith('diagrams/') && readFileSync(join('build',file),'utf8').includes('<svg')) {
       assert.equal(readFileSync(join('build',file),'utf8'), readFileSync(join('static',file),'utf8'), `Viewer must match generated static asset: ${file}`);
       reason = 'Standalone diagram viewer asset, not documentation';

scripts/skills-measurement.test.mjs

@@ -5,20 +5,21 @@ import {calculate} from './ai-kpi.mjs';
 const read = path => readFileSync(path, 'utf8');
 
 test('Skills Measurement is an open adoption collection plan, not a hidden catalogue', () => {
-  const page = read('docs/strategy/measurement.mdx');
+  const page = read('docs/strategy/measurement/index.mdx');
   assert.match(page, /title: Skills Measurement\nsidebar_label: Measurement/);
   for (const heading of ['Establish the baseline', 'Measure the pilot', 'Extend collection as adoption grows', 'Keep the collection running']) assert(page.includes(heading), heading);
   assert(!page.includes('<details>'));
-  assert(page.includes('./reference/measurement-contracts.mdx'));
+  assert(page.includes('./collection-and-safeguards.mdx'));
   assert(!page.includes('Is AI-assisted work worth continuing?'));
   for (const word of ['Recommended', 'not installed', 'unknown', 'review', 'CI', 'revision', 'Monthly', 'Weekly']) assert(page.includes(word), word);
 });
 
 test('all sixteen metric definitions remain in the reference with explicit implementation limits', () => {
-  const page = read('docs/strategy/reference/measurement-contracts.mdx');
+  const manifest = JSON.parse(read('research/ai-adoption/measurement-migration.json'));
+  const page = read('docs/strategy/measurement/index.mdx') + read('docs/strategy/measurement/collection-and-safeguards.mdx');
   const model = JSON.parse(read('research/ai-adoption/strategy-model.json'));
   for (const k of model.kpis) {
-    const section = page.split(`### ${k.name}\n`)[1]?.split('\n### ')[0];
+    const section = read(`docs/strategy/${manifest.metrics.find(m => m.title === k.name).docId}.mdx`);
     assert(section, k.name);
     for (const field of ['Numerator','Denominator','Expression','Aggregation','Unit','Eligible population','Exclusions','Events and source','Owner / cadence','Missing evidence','Gaming and limits']) assert(section.includes(`| ${field} |`));
   }
@@ -26,7 +27,7 @@ test('all sixteen metric definitions remain in the reference with explicit imple
 });
 
 test('published pilot arithmetic matches the executable fixture, including partial cost', () => {
-  const page = read('docs/strategy/measurement.mdx');
+  const page = read('docs/strategy/measurement/index.mdx');
   const fixture = JSON.parse(read('scripts/fixtures/ai-kpi-synthetic.json'));
   const report = calculate(fixture);
   const success = report.kpis['validated-task-success'];

scripts/skills-stories.test.mjs

@@ -10,7 +10,7 @@ const topics = ['governance','quality','adoption','measurement','maintenance'];
 test('all six Skills Adoption pages account for exactly five diagrams and ten sources',()=>{
  let count=0;
  for(const route of ['stage-01-skills-adoption',...topics.map(t=>t==='measurement'?t:`skills-${t}`)]){
-  const diagrams=[...read(`docs/strategy/${route}.mdx`).matchAll(/<ArchifyDiagram name="([^"]+)"/g)];
+  const diagrams=[...read(`docs/strategy/${route === 'measurement' ? 'measurement/index' : route}.mdx`).matchAll(/<ArchifyDiagram name="([^"]+)"/g)];
   assert.equal(diagrams.length,route.startsWith('stage-')?0:1);
   for(const [,name] of diagrams){assert(isSkillsStory(name));for(const suffix of ['','-mobile'])JSON.parse(read(`diagrams/${name}${suffix}.architecture.json`));count++;}
  }

scripts/strategy-navigation.test.mjs

@@ -17,9 +17,12 @@ test('Strategy has Target, Roadmap, a linked Skills Adoption category and Autono
       {type:'doc', id:'skills-governance', label:'Governance'},
       {type:'doc', id:'skills-quality', label:'Quality'},
       {type:'doc', id:'skills-adoption', label:'Adoption'},
-      {type:'doc', id:'measurement', label:'Measurement'},
+      {type:'category', label:'Measurement', collapsed:true, link:{type:'doc', id:'measurement/index'}, items:[
+        ...JSON.parse(read('research/ai-adoption/measurement-migration.json')).metrics.map(m => m.docId),
+        'measurement/collection-and-safeguards','measurement/synthetic-example',
+      ]},
       {type:'doc', id:'skills-maintenance', label:'Maintenance'},
-      {type:'category', label:'Reference', collapsed:true, items:[{type:'doc', id:'reference/measurement-contracts', label:'Measurement Contracts'}]},
+
     ],
   }, 'stage-02-autonomous-agent']);
   assert.match(read('docs/strategy/target-operating-model.mdx'), /^sidebar_label: Target$/m);
@@ -36,10 +39,10 @@ test('stage overviews explain the foundation and future without replacing topic
     assert(page.includes(`id: ${id}\ntitle: ${title}`));
     for (const link of ['./roadmap.mdx', './target-operating-model.mdx']) assert(page.includes(link));
   }
-  for (const id of ['skills-governance','skills-quality','skills-adoption','measurement','skills-maintenance']) assert(first.includes(`./${id}.mdx`));
+  for (const id of ['skills-governance','skills-quality','skills-adoption','measurement/index','skills-maintenance']) assert(first.includes(`./${id}.mdx`));
   for (const marker of ['human + AI Agent','Delivery first','order is not yet decided','KPIs','baseline','topology','feedback','new current situation']) assert(first.includes(marker), marker);
   for (const marker of ['future','proven skills','measurements','working practices','direction and review','not deployed autonomy','approved KPI thresholds']) assert(second.includes(marker), marker);
-  assert.match(read('docs/strategy/measurement.mdx'), /^title: Skills Measurement\nsidebar_label: Measurement$/m);
+  assert.match(read('docs/strategy/measurement/index.mdx'), /^title: Skills Measurement\nsidebar_label: Measurement$/m);
 });
 
 test('old Strategy entry redirects to Target instead of maintaining a second document', () => {

scripts/strategy-story.test.mjs

@@ -6,25 +6,25 @@ const model = JSON.parse(read('research/ai-adoption/strategy-model.json'));
 
 test('every strategy page leads with a compact diagram story and closes its references', () => {
   for (const {id} of model.pages) {
-    const page = read(`docs/strategy/${id}.mdx`);
+    const page = read(`docs/strategy/${id === 'measurement' ? 'measurement/index' : id}.mdx`);
     const narrative = page.split('<div className="strategy-content">')[1].replace(/<details>[\s\S]*?<\/details>/g, '');
     assert.equal((narrative.match(/<ArchifyDiagram /g) || []).length, id === 'roadmap' ? 3 : 1, id);
     assert(narrative.includes(' story />'), id);
     assert(!page.includes('<details>') || page.indexOf(' story />') < page.indexOf('<details>'), id);
     assert(!/<details\s+open/.test(page), id);
     assert.equal((page.match(/<details>/g) || []).length, (page.match(/<\/details>/g) || []).length, id);
-    assert.equal((narrative.match(/^## /gm) || []).length, id === 'measurement' ? 4 : id === 'roadmap' ? 4 : 1, id);
+    assert.equal((narrative.match(/^## /gm) || []).length, id === 'measurement' ? 5 : id === 'roadmap' ? 4 : 1, id);
     assert((narrative.match(/^- /gm) || []).length <= 3, id);
     assert(narrative.includes('**Next:**'), id);
     assert(!narrative.includes('| ---'), id);
     const words = narrative.replace(/<[^>]*>/g, '').trim().split(/\s+/).length;
-    assert(words <= (id === 'measurement' ? 1100 : id === 'roadmap' ? 600 : 200), `${id}: ${words} default narrative words`);
+    assert(words <= (id === 'measurement' ? 1500 : id === 'roadmap' ? 600 : 200), `${id}: ${words} default narrative words`);
   }
 });
 
 test('mobile story diagrams preserve the same nodes and directed relationships', () => {
   for (const {id} of model.pages) {
-    const page = read(`docs/strategy/${id}.mdx`);
+    const page = read(`docs/strategy/${id === 'measurement' ? 'measurement/index' : id}.mdx`);
     const name = /<ArchifyDiagram name="([^"]+)"[^>]+ story/.exec(page)[1];
     if (name === 'strategy-roadmap') {
       const desktop = JSON.parse(read(`diagrams/${name}.workflow.json`));
@@ -44,12 +44,12 @@ test('mobile story diagrams preserve the same nodes and directed relationships',
 });
 
 test('all sixteen exact KPI formulas remain reachable in the linked reference', () => {
-  assert(read('docs/strategy/measurement.mdx').includes('./reference/measurement-contracts.mdx'));
-  const page = read('docs/strategy/reference/measurement-contracts.mdx');
-  const contracts = page.split('## Metric contracts')[1].split('## Run the synthetic')[0];
-  assert.equal((contracts.match(/^### /gm) || []).length, 16);
+  const manifest = JSON.parse(read('research/ai-adoption/measurement-migration.json'));
+  assert.equal(manifest.metrics.length, 16);
   for (const metric of model.kpis) {
-    const section = contracts.split(`### ${metric.name}\n`)[1]?.split('\n### ')[0];
+    const entry = manifest.metrics.find(m => m.title === metric.name);
+    assert(read('docs/strategy/measurement/index.mdx').includes(`./${entry.oldAnchor}.mdx`));
+    const section = read(`docs/strategy/${entry.docId}.mdx`);
     assert(section, metric.name);
     for (const label of ['Numerator','Denominator','Expression','Aggregation','Unit','Eligible population','Exclusions','Events and source','Owner / cadence','Missing evidence','Gaming and limits']) assert(section.includes(`| ${label} |`), `${metric.name}: ${label}`);
   }

scripts/strategy.test.mjs

@@ -6,13 +6,13 @@ const model = JSON.parse(read('research/ai-adoption/strategy-model.json'));
 test('seven existing strategy pages and two stage overviews preserve canonical routes', () => {
   assert.equal(model.pages.length, 7);
   assert.deepEqual(readdirSync('docs/strategy').filter(p => p.endsWith('.mdx')).sort(),
-    [...model.pages.map(({id}) => `${id}.mdx`), 'stage-01-skills-adoption.mdx', 'stage-02-autonomous-agent.mdx'].sort());
+    [...model.pages.filter(p => p.id !== 'measurement').map(({id}) => `${id}.mdx`), 'stage-01-skills-adoption.mdx', 'stage-02-autonomous-agent.mdx'].sort());
   for (const {id} of model.pages) {
-    const page = read(`docs/strategy/${id}.mdx`);
-    assert(page.includes(`id: ${id}`));
+    const page = read(`docs/strategy/${id === 'measurement' ? 'measurement/index' : id}.mdx`);
+    assert(page.includes(`id: ${id === 'measurement' ? 'index' : id}`));
     assert(page.includes('Target operating model'));
     assert(!/## Sources|\[\d+\]|Internal evidence mapping/.test(page));
-    assert(read('sidebars/strategy.ts').includes(`'${id}'`));
+    assert(read('sidebars/strategy.ts').includes(`'${id === 'measurement' ? 'measurement/index' : id}'`));
   }
   for (const teams of Object.values(model.organization)) for (const name of teams) {
     assert(read('docs/organization/structure.mdx').includes(name));
@@ -20,15 +20,15 @@ test('seven existing strategy pages and two stage overviews preserve canonical r
   }
 });
 test('every metric has an actionable reader-facing contract', () => {
-  const page = read('docs/strategy/reference/measurement-contracts.mdx');
+  const manifest = JSON.parse(read('research/ai-adoption/measurement-migration.json'));
   assert.equal(model.kpis.length,16);
   for (const k of model.kpis) {
-    const section=page.split(`### ${k.name}\n`)[1]?.split('\n### ')[0];
+    const section=read(`docs/strategy/${manifest.metrics.find(m => m.title === k.name).docId}.mdx`);
     assert(section,k.name);
     for (const field of ['Eligible population','Exclusions','Events and source','Owner / cadence','Missing evidence','Gaming and limits']) assert(section.includes(`| ${field} |`));
     assert(section.includes(k.owner));
   }
-  assert(page.includes('synthetic') && page.includes('not a production ingestion system'));
+  assert(read('docs/strategy/measurement/synthetic-example.mdx').includes('not a production ingestion system'));
 });
 test('diagram preserves independent release approval and no agent production authority', () => {
   const d=JSON.parse(read('diagrams/ai-adoption-target.architecture.json'));

scripts/verify.mjs

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import {readFileSync, readdirSync, existsSync} from 'node:fs';
 import {join} from 'node:path';
 import {verifySidebarCoverage} from './sidebar-coverage.mjs';
+import {verifyMeasurementPages} from './measurement-pages.mjs';
 const read = p => readFileSync(p, 'utf8');
 const config = read('docusaurus.config.ts');
 assert(config.includes("baseUrl: '/eldorado-v1/documentation/'"));
@@ -18,6 +19,7 @@ assert(workflow.includes('mountpoint -q'));
 assert(workflow.includes("gitea.event_name == 'push' && gitea.ref == 'refs/heads/main'"));
 if (process.argv.includes('--build')) {
   await verifySidebarCoverage();
+  verifyMeasurementPages();
   const model = JSON.parse(read('research/ai-adoption/strategy-model.json'));
   const indexes = readdirSync('build').filter(f => /^search-index.*\.json$/.test(f)).map(f => read(join('build',f))).join('\n');
   const redirect = read('build/strategy/index.html');