docs: publish target AI adoption strategy and synthetic measurement examples

scripts/ai-kpi.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/** SYNTHETIC reference only. No collectors, network access or production authorization.
+ * Input is a deliberately simplified, reconciled fixture, NOT a production event schema.
+ * Conflicts fail closed (no output); reconciliation/quarantine storage is not implemented.
+ */
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+export const LABEL = 'SYNTHETIC — illustrative, not Eldorado observations';
+export const CALCULATION_VERSION = 'synthetic-1.0.0';
+export const ratio = (n, d, scale = 100) => d === 0 ? null : n / d * scale;
+export function time(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|\+00:00)$/.test(value)) throw new Error('UTC timestamp required');
+  const t = Date.parse(value);
+  if (!Number.isFinite(t) || new Date(t).toISOString().slice(0,19) !== value.slice(0,19)) throw new Error('Invalid timestamp');
+  return t;
+}
+const canonical = value => JSON.stringify(value, (_, v) => v && typeof v === 'object' && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a],[b]) => a.localeCompare(b))) : v);
+const without = (row, keys) => Object.fromEntries(Object.entries(row).filter(([k]) => !keys.includes(k)));
+export function dedup(events) {
+  const kept = new Map();
+  for (const e of events) {
+    if (!e.producer || !e.event_id) throw new Error('Missing transport identity');
+    if (time(e.received_at) < time(e.occurred_at)) throw new Error('Receipt before occurrence');
+    const key = canonical([e.producer, e.event_id]), prior = kept.get(key);
+    if (prior && canonical(without(prior,['received_at'])) !== canonical(without(e,['received_at']))) throw new Error('Conflicting duplicate requires quarantine');
+    if (!prior || time(e.received_at) < time(prior.received_at)) kept.set(key,e);
+  }
+  return [...kept.values()];
+}
+function result(n, d, as_of, {unit = '%', scale = 100, unknown = 0, exclusions = {}, ...extra} = {}) {
+  return {label:LABEL, as_of, calculation_version:CALCULATION_VERSION, numerator:n, denominator:d, unit, value_or_null:ratio(n,d,scale), unknown_count:unknown, exclusions, coverage:{known_percent:ratio(d-unknown,d)}, warnings:unknown ? ['Unknown records remain visible; this is not a failure/non-use rate.'] : [], ...extra};
+}
+function taskCohort(events, start, end, as_of) {
+  const lo=time(start), hi=time(end), cutoff=time(as_of);
+  if (lo >= hi) throw new Error('Invalid half-open window');
+  const starts=new Map(), terminal=new Map();
+  for (const e of dedup(events)) {
+    if (time(e.occurred_at)>cutoff || time(e.received_at)>cutoff) continue;
+    if (e.event_type.startsWith('task.') && !e.task_id) throw new Error('Missing task ID');
+    if (e.event_type==='task.started') {
+      if (!Number.isFinite(e.horizon_hours) || e.horizon_hours<0) throw new Error('Missing/invalid observation horizon');
+      const prior=starts.get(e.task_id);
+      if (prior && (time(prior.occurred_at)!==time(e.occurred_at) || prior.horizon_hours!==e.horizon_hours)) throw new Error('Conflicting semantic task start');
+      starts.set(e.task_id,e);
+    } else if (['task.accepted','task.failed','task.abandoned','task.cancelled'].includes(e.event_type)) {
+      if (e.event_type==='task.accepted' && e.independent_evidence!==true) continue;
+      const prior=terminal.get(e.task_id);
+      if (prior && prior.event_type!==e.event_type) throw new Error('Conflicting task terminal state');
+      if (!prior || time(e.occurred_at)<time(prior.occurred_at)) terminal.set(e.task_id,e);
+    }
+  }
+  for (const [id,e] of terminal) if (starts.has(id) && time(e.occurred_at)<time(starts.get(id).occurred_at)) throw new Error('Terminal before start');
+  const eligible = new Set([...starts].filter(([,e]) => time(e.occurred_at)>=lo && time(e.occurred_at)<hi && time(e.occurred_at)+e.horizon_hours*3600000<=cutoff).map(([id])=>id));
+  return {starts, terminal, eligible};
+}
+// Snapshot rows are pre-reconciled at fixture as_of. Optional receipt/occurrence
+// timestamps support late-record tests; missing timestamps are NOT inferred events.
+function unique(rows, fields=['id']) {
+  const map=new Map();
+  for (const r of rows) {
+    if (fields.some(k=>typeof r[k]!=='string' || !r[k])) throw new Error('Missing semantic identity');
+    const key=canonical(fields.map(k=>r[k])), payload=without(r,['producer','event_id','received_at']);
+    if (map.has(key) && canonical(without(map.get(key),['producer','event_id','received_at']))!==canonical(payload)) throw new Error('Semantic conflict requires reconciliation');
+    const prior=map.get(key);
+    if (!prior || (r.received_at && prior.received_at && time(r.received_at)<time(prior.received_at))) map.set(key,r);
+  }
+  return [...map.values()];
+}
+const visible = (r, as_of) => (!r.received_at || time(r.received_at)<=time(as_of)) && (!r.occurred_at || time(r.occurred_at)<=time(as_of));
+const within = (t,start,end) => time(t)>=time(start) && time(t)<time(end);
+function horizon(r) {
+  if (!Number.isFinite(r.followup_hours) || r.followup_hours<0) throw new Error('Missing/invalid followup horizon');
+  return r.followup_hours*3600000;
+}
+export function association(rows) {
+  const map=new Map();
+  for (const r of rows) {
+    const tuple={skill_id:r.skill_id,revision:r.revision ?? null,version_status:!Object.hasOwn(r,'revision') ? 'missing' : r.revision===null ? 'unknown' : 'known',client:r.client,missing_reason:r.missing_reason ?? null};
+    if (!map.has(r.task_id)) map.set(r.task_id,new Map());
+    map.get(r.task_id).set(canonical(tuple),tuple);
+  }
+  return Object.fromEntries([...map].map(([id, tuples])=>[id,[...tuples.values()].sort((a,b)=>canonical(a).localeCompare(canonical(b)))]));
+}
+export function deployments(rows) {
+  const effects=unique(rows,['service_id','deployment_id']).filter(r=>r.environment==='production' && r.production_effect===true);
+  return {effects:effects.length,successful:effects.filter(r=>r.succeeded===true).length,change_fail_rate:ratio(effects.filter(r=>r.intervention===true).length,effects.length),rework_rate:ratio(effects.filter(r=>r.planned===false && Boolean(r.incident_id)).length,effects.length)};
+}
+export function matureDefects(changes,defects,as_of,start='0001-01-01T00:00:00Z',end=as_of) {
+  const eligible=unique(changes).filter(c=>visible(c,as_of) && within(c.accepted_at,start,end) && time(c.accepted_at)+horizon(c)<=time(as_of));
+  const affected=new Set();
+  for (const d of unique(defects)) {
+    const c=eligible.find(c=>c.id===d.change_id);
+    if (c && d.confirmed===true && visible(d,as_of) && time(d.detected_at)>=time(c.accepted_at) && time(d.detected_at)<=time(c.accepted_at)+horizon(c)) affected.add(c.id);
+  }
+  return [affected.size,eligible.length];
+}
+export function survey(rows,invited,as_of) {
+  if (!Number.isInteger(invited) || invited<0) throw new Error('Invalid invitation count');
+  const all=unique(rows), valid=all.filter(r=>Number.isInteger(r.score) && r.score>=1 && r.score<=5);
+  if (all.length>invited) throw new Error('Responses exceed invitations');
+  const suppressed=valid.length<5;
+  return result(suppressed?null:valid.reduce((n,r)=>n+r.score,0),valid.length,as_of,{unit:'points (1–5)',scale:1,value_or_null:suppressed?null:ratio(valid.reduce((n,r)=>n+r.score,0),valid.length,1),suppressed,exclusions:{invalid_answers:all.length-valid.length},coverage:{response_percent:ratio(valid.length,invited)},distribution:suppressed?null:Object.fromEntries([1,2,3,4,5].map(s=>[s,valid.filter(r=>r.score===s).length])),warnings:suppressed?['People cohort below five suppressed.']:[]});
+}
+export function calculate(f) {
+  if (f.synthetic!==true || f.schema_version!=='1.0') throw new Error('Explicit synthetic schema 1.0 fixture required');
+  const {start,end,as_of}=f, kpis={};
+  kpis['validated-task-success']=success(f.events,start,end,as_of);
+  const trials=unique(f.selection).filter(r=>visible(r,as_of));
+  const scored=trials.filter(r=>typeof r.relevant==='boolean' && typeof r.activated==='boolean');
+  const tp=scored.filter(r=>r.relevant && r.activated).length;
+  for (const [id,den] of [['selection-precision',scored.filter(r=>r.activated).length],['selection-recall',scored.filter(r=>r.relevant).length]]) {
+    kpis[id]=result(tp,den,as_of,{unknown:trials.length-scored.length,coverage:{scorable_percent:ratio(scored.length,trials.length)},exclusions:{unscorable:trials.length-scored.length}});
+  }
+  const effects=unique(f.deployments,['service_id','deployment_id']).filter(r=>visible(r,as_of) && r.environment==='production' && r.production_effect===true && within(r.deployed_at,start,end));
+  const mature=effects.filter(r=>time(r.deployed_at)+horizon(r)<=time(as_of));
+  kpis['change-fail-rate']=result(mature.filter(r=>r.intervention===true).length,mature.length,as_of,{unknown:mature.filter(r=>typeof r.intervention!=='boolean').length,exclusions:{immature:effects.length-mature.length}});
+  kpis['deployment-rework-rate']=result(effects.filter(r=>r.planned===false && Boolean(r.incident_id)).length,effects.length,as_of,{unknown:effects.filter(r=>typeof r.planned!=='boolean' || (r.planned===false && !Object.hasOwn(r,'incident_id'))).length});
+  const [affected,accepted]=matureDefects(f.changes,f.defects,as_of,start,end);
+  const matureChanges=unique(f.changes).filter(r=>visible(r,as_of) && within(r.accepted_at,start,end) && time(r.accepted_at)+horizon(r)<=time(as_of));
+  kpis['escaped-quality-rate']=result(affected,accepted,as_of,{unknown:matureChanges.filter(r=>r.linkage_complete!==true).length,exclusions:{outside_window_immature_or_late:f.changes.length-matureChanges.length},pending_triage_count:unique(f.defects).filter(r=>visible(r,as_of) && r.confirmed!==true).length});
+  const attempts=unique(f.attempts).filter(r=>visible(r,as_of));
+  kpis['policy-effects']=result(attempts.filter(r=>r.actual_effect===true).length,attempts.length,as_of,{unknown:attempts.filter(r=>typeof r.actual_effect!=='boolean').length,blocked_count:attempts.filter(r=>r.blocked===true).length});
+  const {eligible}=taskCohort(f.events,start,end,as_of);
+  const costs=unique(f.costs).filter(r=>visible(r,as_of) && (eligible.has(r.task_id) || r.task_id==='shared_pool'));
+  if (costs.some(r=>r.currency!==f.currency || !Number.isFinite(r.amount) || r.amount<0)) throw new Error('Invalid cost or mixed currency: approved conversion required');
+  const missing=f.expected_cost_buckets.filter(b=>!costs.some(r=>r.bucket===b));
+  kpis['cost-per-accepted-outcome']=result(costs.reduce((sum,r)=>sum+r.amount,0),kpis['validated-task-success'].numerator,as_of,{scale:1,unit:`${f.currency}/accepted outcome`,partial_estimate:missing.length>0,coverage:{missing_cost_buckets:missing},warnings:missing.length?['Partial estimate, not total cost; missing cost buckets.']:[]});
+  kpis['human-experience']=survey(f.survey.responses.filter(r=>visible(r,as_of)),f.survey.invited,as_of);
+  return {label:LABEL,as_of,calculation_version:CALCULATION_VERSION,window:{start,end},kpis,associations:association(f.associations),not_implemented:['supported-bundle-coverage','useful-adoption','change-lead-time','deployment-frequency','failed-deployment-recovery-time','maintenance-health','department-outcome'],limitations:['Synthetic simplified reconciled snapshots only; not the full production event envelope.','Snapshot rows without timestamps are assumed frozen at as_of, not missing-event evidence.','No causal attribution, uncertainty intervals, authorization or telemetry collection.','Survey implements primary item only; no cross-slice disclosure protection.','Defect severity strata and policy severity counts are not implemented.']};
+}
+if (process.argv[1] && import.meta.url===pathToFileURL(process.argv[1]).href) {
+  try {
+    if (process.argv.length>3) throw new Error('Usage: node scripts/ai-kpi.mjs [synthetic-fixture.json]');
+    const source=process.argv[2] ?? new URL('./fixtures/ai-kpi-synthetic.json',import.meta.url);
+    console.log(JSON.stringify(calculate(JSON.parse(readFileSync(source,'utf8'))),null,2));
+  } catch (error) { console.error(`Synthetic KPI calculation failed: ${error.message}`); process.exitCode=1; }
+}
+export function success(events,start,end,as_of) {
+  const {starts,terminal,eligible}=taskCohort(events,start,end,as_of);
+  const n=[...eligible].filter(id=>terminal.get(id)?.event_type==='task.accepted').length;
+  const unknown=[...eligible].filter(id=>!terminal.has(id)).length;
+  return result(n,eligible.size,as_of,{unknown, known_outcome_coverage:ratio(eligible.size-unknown,eligible.size), orphan_terminal_count:[...terminal.keys()].filter(id=>!starts.has(id)).length, excluded_start_count:starts.size-eligible.size, exclusions:{outside_window_or_immature:starts.size-eligible.size}});
+}

scripts/ai-kpi.test.mjs

@@ -0,0 +1,147 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+const moduleUrl = new URL('./ai-kpi.mjs', import.meta.url);
+import { spawnSync } from 'node:child_process';
+import * as api from './ai-kpi.mjs';
+const fixture = () => JSON.parse(readFileSync(new URL('./fixtures/ai-kpi-synthetic.json', import.meta.url)));
+test('CLI report exposes implemented KPI contracts and explicit omissions', async () => {
+  const m = await import(moduleUrl);
+  assert.equal(typeof m.calculate, 'function');
+  const r = m.calculate(fixture());
+  assert.equal(Object.keys(r.kpis).length, 9);
+  assert.equal(r.not_implemented.length, 7);
+  assert.equal(r.kpis['cost-per-accepted-outcome'].value_or_null, 60);
+  assert.equal(r.kpis['selection-precision'].value_or_null, 50);
+  assert.equal(r.kpis['selection-recall'].value_or_null, 50);
+  assert.equal(r.kpis['change-fail-rate'].value_or_null, 100);
+  assert.equal(r.kpis['deployment-rework-rate'].value_or_null, 100);
+  assert.equal(r.kpis['escaped-quality-rate'].value_or_null, 100);
+  assert.equal(r.kpis['policy-effects'].value_or_null, 50);
+  assert.equal(r.kpis['human-experience'].value_or_null, 4);
+});
+function event(id,task,kind,day=1,extra={}) {
+  const timestamp=`2026-01-${String(day).padStart(2,'0')}T00:00:00Z`;
+  return {producer:'synthetic',event_id:id,task_id:task,event_type:kind,occurred_at:timestamp,received_at:timestamp,...extra};
+}
+const run = (events,as_of=fixture().as_of) => api.success(events,fixture().start,fixture().end,as_of);
+test('transport duplicates and redelivery use earliest receipt in either order',()=>{
+  const f=fixture(), duplicate={...f.events[0],received_at:'2026-01-06T00:00:00Z'};
+  assert.deepEqual(run([...f.events,f.events[0]]),run(f.events));
+  assert.deepEqual(run([...f.events,duplicate]),run(f.events));
+  assert.deepEqual(run([duplicate,...f.events]),run(f.events));
+});
+test('transport conflicts fail closed',()=>assert.throws(()=>run([...fixture().events,{...fixture().events[0],task_id:'other'}]),/Conflicting duplicate/));
+test('retry and cross-feed semantic duplicate never add tasks',()=>{
+  const f=fixture();
+  assert.equal(run([...f.events,event('retry','accepted','attempt.started',2),event('retry-fail','accepted','attempt.failed',2),{...f.events[0],producer:'mirror',event_id:'mirror-start'}]).denominator,4);
+});
+test('immature task and half-open end excluded',()=>{
+  const r=run([...fixture().events,event('boundary','boundary','task.started',5,{horizon_hours:0})]);
+  assert.equal(r.excluded_start_count,2);
+  assert.equal(r.denominator,4);
+});
+test('all implemented zero denominator values are null',()=>{
+  const f=fixture();
+  for (const k of ['events','selection','deployments','changes','defects','attempts','costs','associations']) f[k]=[];
+  f.survey={invited:0,responses:[]};
+  for (const r of Object.values(api.calculate(f).kpis)) assert.equal(r.value_or_null,null);
+});
+test('orphan terminal does not increase accepted count',()=>{
+  const r=run([...fixture().events,event('orphan','absent','task.accepted',2,{independent_evidence:true})]);
+  assert.equal(r.orphan_terminal_count,1); assert.equal(r.numerator,1);
+});
+test('late arrival restates only when received',()=>{
+  const events=[...fixture().events,event('late','unknown','task.accepted',3,{independent_evidence:true,received_at:'2026-01-06T00:00:00Z'})];
+  assert.equal(run(events).numerator,1);
+  assert.equal(run(events,'2026-01-06T00:00:00Z').numerator,2);
+});
+test('unknown, absent and mixed versions retained without latest inference',()=>{
+  const rows=['a','b','a',null].map(revision=>({task_id:'t',skill_id:'s',revision,client:'Cline'}));
+  rows.push({task_id:'t',skill_id:'s',client:'Cline'});
+  const r=api.association(rows).t;
+  assert.equal(r.length,4);
+  assert.equal(r.filter(x=>x.version_status==='known').length,2);
+  assert.deepEqual(new Set(r.filter(x=>x.revision===null).map(x=>x.version_status)),new Set(['missing','unknown']));
+});
+test('invalid timestamps, UTC offsets, receipt order and terminal order rejected',()=>{
+  for(const t of ['no','2026-02-30T00:00:00Z','2026-01-01T00:00:00+01:00']) assert.throws(()=>api.time(t));
+  assert.throws(()=>run([event('s','t','task.started',2,{horizon_hours:24}),event('a','t','task.accepted',1,{independent_evidence:true})]),/Terminal before start/);
+  assert.throws(()=>api.dedup([event('s','t','task.started',2,{received_at:'2026-01-01T00:00:00Z'})]),/Receipt before/);
+});
+test('missing horizon is not silently mature',()=>assert.throws(()=>run([event('s','t','task.started')]),/horizon/));
+test('conflicting terminal and semantic start require reconciliation',()=>{
+  assert.throws(()=>run([...fixture().events,event('conflict','accepted','task.failed',3)]),/Conflicting task terminal/);
+  assert.throws(()=>run([...fixture().events,event('conflict','accepted','task.started',2,{horizon_hours:48})]),/semantic task start/);
+});
+test('no independent acceptance evidence means unknown, not accepted',()=>{
+  const r=run([event('s','t','task.started',1,{horizon_hours:24}),event('a','t','task.accepted',2)]);
+  assert.equal(r.numerator,0); assert.equal(r.unknown_count,1);
+});
+test('pre-start cancellation excluded; post-start cancellation remains denominator',()=>{
+  const r=run([event('pre','never','task.cancelled',1,{before_start:true}),event('s','started','task.started',1,{horizon_hours:24}),event('post','started','task.cancelled',2,{before_start:false})]);
+  assert.deepEqual([r.numerator,r.denominator,r.unknown_count],[0,1,0]);
+});
+test('deployment retries collapse; unknown rework not treated as planned',()=>{
+  const row=fixture().deployments[0];
+  assert.deepEqual(api.deployments([row,{...row,producer:'mirror',event_id:'2'}]),{effects:1,successful:1,change_fail_rate:100,rework_rate:100});
+  assert.equal(api.deployments([{...row,planned:null}]).rework_rate,0);
+  const f=fixture(); f.deployments[0].planned=null;
+  const r=api.calculate(f).kpis['deployment-rework-rate'];
+  assert.equal(r.denominator,1); assert.equal(r.unknown_count,1);
+  assert.throws(()=>api.deployments([row,{...row,planned:true}]),/Semantic conflict/);
+});
+test('mature deployment denominator retains unsuccessful production effects',()=>{
+  const f=fixture(); f.deployments[0].succeeded=false;
+  assert.equal(api.calculate(f).kpis['change-fail-rate'].denominator,1);
+  f.deployments[0].followup_hours=1000;
+  assert.equal(api.calculate(f).kpis['change-fail-rate'].denominator,0);
+});
+test('mature defect followup is linked, bounded and deduplicated',()=>{
+  const f=fixture();
+  f.changes.push({id:'new',accepted_at:'2026-01-04T00:00:00Z',followup_hours:48});
+  f.defects.push({...f.defects[0],id:'new-defect',change_id:'new'});
+  assert.deepEqual(api.matureDefects(f.changes,[...f.defects,f.defects[0]],f.as_of),[1,1]);
+  f.defects[0].detected_at='2026-01-04T00:00:00Z';
+  assert.deepEqual(api.matureDefects(f.changes,f.defects,f.as_of),[0,1]);
+});
+test('cost includes failed attempts, flags partial buckets and rejects mixed currencies',()=>{
+  const f=fixture(); let r=api.calculate(f).kpis['cost-per-accepted-outcome'];
+  assert.equal(r.numerator,60); assert.equal(r.partial_estimate,true);
+  f.costs.push({...f.costs[0]});
+  assert.equal(api.calculate(f).kpis['cost-per-accepted-outcome'].numerator,60);
+  f.costs.pop(); // Currency validation is separate from conflicting duplicate validation.
+  f.costs[0].currency='USD'; assert.throws(()=>api.calculate(f),/mixed currency/);
+});
+test('blocked attempts are not prohibited effects; unknown audits remain denominator',()=>{
+  const f=fixture(); f.attempts.push({id:'unknown'});
+  const r=api.calculate(f).kpis['policy-effects'];
+  assert.deepEqual([r.numerator,r.denominator,r.blocked_count,r.unknown_count],[1,3,1,1]);
+});
+test('survey suppresses small groups including sum and distribution',()=>{
+  const f=fixture(), r=api.survey(f.survey.responses.slice(0,4),10,f.as_of);
+  assert.equal(r.value_or_null,null); assert.equal(r.numerator,null); assert.equal(r.distribution,null);
+});
+test('required output fields accompany every implemented KPI',()=>{
+  const required=['label','as_of','calculation_version','numerator','denominator','unit','value_or_null','unknown_count','exclusions','coverage','warnings'];
+  for (const r of Object.values(api.calculate(fixture()).kpis)) for(const key of required) assert.ok(Object.hasOwn(r,key),key);
+});
+test('non-synthetic and unknown fixture schemas rejected',()=>{
+  assert.throws(()=>api.calculate({...fixture(),synthetic:false}),/synthetic/);
+  assert.throws(()=>api.calculate({...fixture(),schema_version:'future'}),/schema/);
+});
+test('CLI executes default and explicit fixture and fails visibly for missing input',()=>{
+  for(const args of [[],[new URL('./fixtures/ai-kpi-synthetic.json',import.meta.url).pathname]]) {
+    const r=spawnSync(process.execPath,[moduleUrl.pathname,...args],{encoding:'utf8'});
+    assert.equal(r.status,0,r.stderr); assert.equal(JSON.parse(r.stdout).kpis['validated-task-success'].value_or_null,25);
+  }
+  const r=spawnSync(process.execPath,[moduleUrl.pathname,'/nonexistent/synthetic-fixture.json'],{encoding:'utf8'});
+  assert.equal(r.status,1); assert.equal(r.stdout,''); assert.match(r.stderr,/failed/);
+});
+test('synthetic task calculator exists and retains failed, abandoned, unknown tasks', async () => {
+  assert.ok(existsSync(moduleUrl), 'calculator implementation is required');
+  const { success } = await import(moduleUrl);
+  const f = JSON.parse(readFileSync(new URL('./fixtures/ai-kpi-synthetic.json', import.meta.url)));
+  const r = success(f.events, f.start, f.end, f.as_of);
+  assert.deepEqual([r.numerator, r.denominator, r.unknown_count, r.value_or_null, r.known_outcome_coverage], [1,4,1,25,75]);
+});

scripts/fixtures/ai-kpi-synthetic.json

@@ -0,0 +1,37 @@
+{
+  "synthetic": true,
+  "label": "SYNTHETIC — illustrative, not Eldorado observations",
+  "schema_version": "1.0",
+  "start": "2026-01-01T00:00:00Z",
+  "end": "2026-01-05T00:00:00Z",
+  "as_of": "2026-01-05T00:00:00Z",
+  "events": [
+    {"producer":"synthetic","event_id":"sa","task_id":"accepted","event_type":"task.started","occurred_at":"2026-01-01T00:00:00Z","received_at":"2026-01-01T00:00:00Z","horizon_hours":48},
+    {"producer":"synthetic","event_id":"sf","task_id":"failed","event_type":"task.started","occurred_at":"2026-01-01T00:00:00Z","received_at":"2026-01-01T00:00:00Z","horizon_hours":48},
+    {"producer":"synthetic","event_id":"sb","task_id":"abandoned","event_type":"task.started","occurred_at":"2026-01-01T00:00:00Z","received_at":"2026-01-01T00:00:00Z","horizon_hours":48},
+    {"producer":"synthetic","event_id":"su","task_id":"unknown","event_type":"task.started","occurred_at":"2026-01-01T00:00:00Z","received_at":"2026-01-01T00:00:00Z","horizon_hours":48},
+    {"producer":"synthetic","event_id":"a","task_id":"accepted","event_type":"task.accepted","occurred_at":"2026-01-02T00:00:00Z","received_at":"2026-01-02T00:00:00Z","independent_evidence":true},
+    {"producer":"synthetic","event_id":"f","task_id":"failed","event_type":"task.failed","occurred_at":"2026-01-02T00:00:00Z","received_at":"2026-01-02T00:00:00Z"},
+    {"producer":"synthetic","event_id":"b","task_id":"abandoned","event_type":"task.abandoned","occurred_at":"2026-01-02T00:00:00Z","received_at":"2026-01-02T00:00:00Z"},
+    {"producer":"synthetic","event_id":"new","task_id":"immature","event_type":"task.started","occurred_at":"2026-01-04T00:00:00Z","received_at":"2026-01-04T00:00:00Z","horizon_hours":48}
+  ],
+  "selection": [
+    {"id":"trial-a","relevant":true,"activated":true},
+    {"id":"trial-b","relevant":false,"activated":true},
+    {"id":"trial-c","relevant":true,"activated":false},
+    {"id":"trial-d","relevant":null,"activated":null}
+  ],
+  "deployments": [{"service_id":"service-a","deployment_id":"deploy-a","environment":"production","production_effect":true,"succeeded":true,"intervention":true,"planned":false,"incident_id":"incident-a","deployed_at":"2026-01-02T00:00:00Z","followup_hours":24}],
+  "changes": [{"id":"change-a","accepted_at":"2026-01-01T00:00:00Z","followup_hours":48,"linkage_complete":true}],
+  "defects": [{"id":"defect-a","change_id":"change-a","confirmed":true,"detected_at":"2026-01-02T00:00:00Z"}],
+  "attempts": [{"id":"attempt-a","actual_effect":false,"blocked":true},{"id":"attempt-b","actual_effect":true,"blocked":false}],
+  "costs": [{"id":"cost-a","task_id":"accepted","amount":40,"currency":"EUR","bucket":"compute"},{"id":"cost-f","task_id":"failed","amount":20,"currency":"EUR","bucket":"compute"}],
+  "currency":"EUR",
+  "expected_cost_buckets":["compute","licenses","tooling","review","rework"],
+  "survey": {"invited":10,"responses":[{"id":"token-a","score":4},{"id":"token-b","score":5},{"id":"token-c","score":3},{"id":"token-d","score":4},{"id":"token-e","score":4}]},
+  "associations": [
+    {"task_id":"accepted","skill_id":"synthetic-skill","revision":"revision-a","client":"Cline"},
+    {"task_id":"accepted","skill_id":"synthetic-skill","revision":"revision-b","client":"Cline"},
+    {"task_id":"unknown","skill_id":"synthetic-skill","revision":null,"client":"Claude Code","missing_reason":"not_exposed"}
+  ]
+}

scripts/strategy.test.mjs

@@ -0,0 +1,40 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {readFileSync, readdirSync} from 'node:fs';
+const read = p => readFileSync(p, 'utf8');
+const model = JSON.parse(read('research/ai-adoption/strategy-model.json'));
+test('eight fixed strategy pages preserve target boundary and separate evidence', () => {
+  assert.equal(model.pages.length, 8);
+  assert.equal(readdirSync('docs/strategy').length, 8);
+  for (const {id} of model.pages) {
+    const page = read(`docs/strategy/${id}.mdx`);
+    assert(page.includes(`id: ${id}`));
+    assert(page.includes('Target operating model'));
+    assert(!/## Sources|\[\d+\]|Internal evidence mapping/.test(page));
+    assert(read('sidebars/strategy.ts').includes(`'${id}'`));
+  }
+  for (const teams of Object.values(model.organization)) for (const name of teams) {
+    assert(read('docs/organization/structure.mdx').includes(name));
+    assert(read('docs/strategy/target-operating-model.mdx').includes(name));
+  }
+});
+test('every metric has an actionable reader-facing contract', () => {
+  const page = read('docs/strategy/measurement.mdx');
+  assert.equal(model.kpis.length,16);
+  for (const k of model.kpis) {
+    const section=page.split(`### ${k.name}\n`)[1]?.split('\n### ')[0];
+    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'));
+});
+test('diagram preserves independent release approval and no agent production authority', () => {
+  const d=JSON.parse(read('diagrams/ai-adoption-target.architecture.json'));
+  assert(d.meta.title.startsWith('TO-BE'));
+  assert.equal(d.components.filter(n=>n.id==='coordinator').length,1);
+  assert.deepEqual(d.connections.filter(e=>e.to==='release').map(e=>e.from),['approval']);
+  for (const [from,to] of [['registry','coordinator'],['registry','clients'],['clients','gates'],['gates','approval'],['release','audit'],['audit','people']]) assert(d.connections.some(e=>e.from===from&&e.to===to));
+  assert(!d.connections.some(e=>['clients','coordinator'].includes(e.from)&&['release','approval'].includes(e.to)));
+  assert(d.boundaries.some(b=>b.wraps.includes('gates')&&b.wraps.includes('release')));
+});

scripts/verify.mjs

@@ -16,6 +16,21 @@ const workflow = read('.gitea/workflows/pages.yml');
 assert(workflow.includes('mountpoint -q'));
 assert(workflow.includes("gitea.event_name == 'push' && gitea.ref == 'refs/heads/main'"));
 if (process.argv.includes('--build')) {
+  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');
+  for (const {id, title} of model.pages) {
+    const route = `strategy/${id === 'index' ? '' : `${id}/`}index.html`;
+    const page = read(join('build',route));
+    assert(page.includes(title) && page.includes('Target operating model'), route);
+    assert(indexes.includes(title), `Missing indexed Strategy page: ${id}`);
+    for (const match of page.matchAll(/href="(\/eldorado-v1\/documentation\/[^"?#]*)/g)) {
+      const local = decodeURIComponent(match[1].replace('/eldorado-v1/documentation/',''));
+      assert(existsSync(join('build', local.endsWith('/') ? `${local}index.html` : local)), `Broken built link: ${local}`);
+    }
+  }
+  assert(!existsSync('build/research'), 'Background research must remain private source');
+  assert(!readdirSync('build/diagrams', {recursive:true}).some(f => f.endsWith('.json')), 'No public diagram JSON');
+  assert(read('build/diagrams/ai-adoption-target/index.html').includes('TO-BE'));
   for (const route of ['index.html','docs/overview/index.html','docs/maintain/index.html','docs/reference/index.html','404.html','organization/structure/index.html','organization/collaboration/index.html','organization/sdlc/index.html','strategy/index.html','contribution/index.html','contribution/diagrams/index.html','diagrams/organization-structure/index.html']) {
     assert(existsSync(join('build',route)), `Missing route: ${route}`);
   }