ms-ai-architect/scripts/kb-update/backfill-status.mjs

#!/usr/bin/env node
// Backfill **Status:** on English-dialect reference files that carry NO status label
// (R21 + Enhet 3 — base-field pre-pass, ⊥ R7). Single mechanism for the whole corpus.
//
// Scope (ground-truth measured 2026-07-06 → extended 2026-07-07):
//   R21     — 14 advisor/architecture files (the clean not-due remainder; 3 Norwegian-dialect
//             and 4 dual-header ai-act-* files were held back — see below).
//   Enhet 3 — +25 non-advisor files whose header carries no **Status:** at all (audit dialect
//             'none' for Status). Measured 25 — NOT the roadmap's "27": 2 of that count are
//             files whose bold **Status:** sits PAST byte 500 (present, but invisible to the
//             500-byte header parser), a separate header-slanking residual, not a missing field.
//   Still OUT — the 4 ms-ai-governance/responsible-ai/ai-act-* files carry a PLAIN-TEXT
//             `Status: GA` in a dual-header block. Inserting a derived bold **Status:** there
//             would duplicate/contradict the authored value; they are handled by the plain→bold
//             dedup driver (dedup-plain-header.mjs), which PRESERVES `GA` rather than deriving.
//
// This applier writes ONLY a derived bold **Status:** line — never a date, never into a
// dual-header ai-act file. Value rule (operator-approved vocabulary): statusForFile() — a
// filename-token map within {Reference, Established Practice}. Reuses the tested insertMetaField
// primitive, with a hard per-file invariant asserted BEFORE any write (exactly one line
// inserted, it is the Status line, body byte-identical). Idempotent: a file already carrying
// **Status:** in its header window is skipped, so a re-run — including the 14 R21 files already
// applied — is a no-op. Aborts and writes nothing on any drift or invariant breach.
//
// Recovery contract: writes are crash-safe (atomicWriteSync tmp+rename — a reader sees the old
// file or the new one, never a partial); an interrupted run is recovered by re-running (idempotent).
//
// Usage:  node scripts/kb-update/backfill-status.mjs [--dry]
import { readFileSync, existsSync, realpathSync } from 'node:fs';
import { join, dirname, basename } from 'node:path';
import { fileURLToPath } from 'node:url';
import { insertMetaField } from './lib/transform.mjs';
import { atomicWriteSync } from './lib/atomic-write.mjs';

const __dirname = dirname(fileURLToPath(import.meta.url));
const PLUGIN_ROOT = join(__dirname, '..', '..');

export const ALLOWED_STATUS = ['Reference', 'Established Practice'];

// Status label is absent in the header region ⇒ the file needs backfilling. Mirrors
// audit-corpus-headers.mjs RE_STATUS (the same guard the header audit reads).
const RE_STATUS = /\*\*Status:\*\*\s*\S/i;

/**
 * Deterministic descriptive-class rule for a not-due reference file (pure).
 * Reusable artifacts (templates, lookup matrices, benchmark tables, registers) are a
 * `Reference`; methodology / patterns / checklists / obligation guides are `Established
 * Practice`. Keys on the BASENAME only, so an ancestor folder token never flips a file.
 * @param {string} relOrBase — plugin-relative path or bare basename
 * @returns {'Reference'|'Established Practice'}
 */
export function statusForFile(relOrBase) {
  const base = basename(String(relOrBase ?? ''));
  return /(?:template|matrix|benchmarks|register)/i.test(base) ? 'Reference' : 'Established Practice';
}

// Frozen manifest — the 39 scope-confirmed targets (missing-**Status:** ∩ English-dialect ∩
// not a dual-header ai-act file), verified against ground truth (R21: 14 advisor 2026-07-06;
// Enhet 3: +25 non-advisor 2026-07-07). Each value is derived by statusForFile() and re-asserted
// below, so the manifest can never drift from the rule.
const TARGET_PATHS = [
  // R21 — 14 advisor/architecture files (already applied; re-run skips them idempotently).
  'skills/ms-ai-advisor/references/architecture/adr-template.md',
  'skills/ms-ai-advisor/references/architecture/ai-utredning-template.md',
  'skills/ms-ai-advisor/references/architecture/alternativanalyse-methodology.md',
  'skills/ms-ai-advisor/references/architecture/capacity-feasibility-benchmarks.md',
  'skills/ms-ai-advisor/references/architecture/cost-models.md',
  'skills/ms-ai-advisor/references/architecture/decision-trees.md',
  'skills/ms-ai-advisor/references/architecture/diagram-prompt-templates.md',
  'skills/ms-ai-advisor/references/architecture/licensing-matrix.md',
  'skills/ms-ai-advisor/references/architecture/migration-patterns.md',
  'skills/ms-ai-advisor/references/architecture/poc-template.md',
  'skills/ms-ai-advisor/references/architecture/public-sector-checklist.md',
  'skills/ms-ai-advisor/references/architecture/regional-availability-verification.md',
  'skills/ms-ai-advisor/references/architecture/security.md',
  'skills/ms-ai-advisor/references/architecture/source-traceability-assumption-register.md',
  // Enhet 3 — 25 non-advisor files with no **Status:** at all (all → Established Practice).
  'skills/ms-ai-engineering/references/mlops-genaiops/cost-optimization-mlops-pipelines.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/feedback-loops-continuous-improvement.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/genaiops-llm-specific-practices.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/governance-audit-ml-operations.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/inferencing-optimization-caching.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/infrastructure-as-code-mlops.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/llm-evaluation-production.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/mlops-security-access-control.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/mlops-teams-collaboration-tools.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/model-deployment-strategies-azure.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/monitoring-observability-ml-systems.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/prompt-flow-production-deployment.md',
  'skills/ms-ai-engineering/references/mlops-genaiops/responsible-ai-mlops-integration.md',
  'skills/ms-ai-governance/references/monitoring-observability/anomaly-detection-ai-systems.md',
  'skills/ms-ai-governance/references/monitoring-observability/azure-monitor-setup-ai-workloads.md',
  'skills/ms-ai-governance/references/monitoring-observability/log-analytics-kql-ai-queries.md',
  'skills/ms-ai-governance/references/monitoring-observability/token-usage-tracking-attribution.md',
  'skills/ms-ai-governance/references/responsible-ai/ai-center-of-excellence-setup.md',
  'skills/ms-ai-governance/references/responsible-ai/ai-governance-structure-framework.md',
  'skills/ms-ai-governance/references/responsible-ai/red-teaming-ai-models.md',
  'skills/ms-ai-security/references/ai-security-engineering/ai-red-team-operations-practical.md',
  'skills/ms-ai-security/references/ai-security-engineering/data-leakage-prevention-ai.md',
  'skills/ms-ai-security/references/ai-security-engineering/secure-model-deployment-hardening.md',
  'skills/ms-ai-security/references/ai-security-engineering/security-copilot-integration.md',
  'skills/ms-ai-security/references/ai-security-engineering/supply-chain-security-ai-models.md',
];
export const MANIFEST = TARGET_PATHS.map((path) => ({ path, status: statusForFile(path) }));

function run({ dry }) {
  const planned = [];
  const skipped = [];
  const missing = [];

  for (const { path: rel, status } of MANIFEST) {
    if (!ALLOWED_STATUS.includes(status)) throw new Error(`ABORT ${rel}: status '${status}' not in allowed set`);
    if (status !== statusForFile(rel)) throw new Error(`ABORT ${rel}: manifest/rule mismatch`);
    const abs = join(PLUGIN_ROOT, rel);
    if (!existsSync(abs)) { missing.push(rel); continue; }
    const old = readFileSync(abs, 'utf8');
    if (RE_STATUS.test(old.slice(0, 500))) { skipped.push(rel); continue; } // idempotent

    const out = insertMetaField(old, 'Status', status);
    // Hard invariant: exactly one line inserted (the Status line), body byte-identical.
    const o = old.split('\n');
    const n = out.split('\n');
    if (n.length !== o.length + 1) throw new Error(`ABORT ${rel}: not exactly one line inserted`);
    let d = 0;
    while (d < o.length && o[d] === n[d]) d++;
    if (n[d] !== `**Status:** ${status}`) throw new Error(`ABORT ${rel}: inserted line mismatch → ${JSON.stringify(n[d])}`);
    if (o.slice(d).join('\n') !== n.slice(d + 1).join('\n')) throw new Error(`ABORT ${rel}: body not byte-identical below the insertion`);
    planned.push({ rel, status, out });
  }

  if (missing.length) {
    console.error(`ABORT — ${missing.length} manifest target(s) not found (corpus drift):`);
    missing.forEach((m) => console.error('  ' + m));
    process.exit(1);
  }
  if (planned.length + skipped.length !== MANIFEST.length) {
    throw new Error(`ABORT — accounted ${planned.length + skipped.length} ≠ manifest ${MANIFEST.length}`);
  }

  const byStatus = {};
  for (const p of planned) byStatus[p.status] = (byStatus[p.status] || 0) + 1;
  console.log(`Manifest: ${MANIFEST.length} | to insert: ${planned.length} | already present (skipped): ${skipped.length}`);
  for (const [s, n] of Object.entries(byStatus).sort()) console.log(`  ${n}  Status: ${s}`);

  if (dry) {
    console.log('\n(dry run — no writes)');
    for (const p of planned) console.log(`  + ${p.rel}  →  **Status:** ${p.status}`);
    return;
  }
  for (const p of planned) atomicWriteSync(join(PLUGIN_ROOT, p.rel), p.out);
  console.log(`\nWrote ${planned.length} files.`);
}

const isMain = (() => {
  try {
    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
  } catch {
    return false;
  }
})();
if (isMain) run({ dry: process.argv.includes('--dry') });