@thanbir-tamim/enterprise-project-intelligence-agent 0.1.1 → 0.2.0

package/skills/documentation-quality-auditor/scripts/audit-docs.mjs

@@ -1,52 +1,212 @@
 #!/usr/bin/env node
 /**
- * Reference documentation audit: broken internal references + unsupported strong claims,
- * operating on the inventory/evidence-index produced by project-documentation-discovery.
- * Pure function over structured input; no network calls.
+ * Deterministic documentation audit for documentation-quality-auditor.
+ *
+ * Checks (see ../references/audit-checks.md):
+ *   broken-internal-reference      link target file missing, or #anchor not a heading in the target
+ *   unresolvable-citation          [source: path#anchor] whose file/anchor does not exist
+ *   internal-looking-external-link private/internal host or IP (value redacted in output)
+ *   unsupported-claim              absolute/strong claim with no citation on the line
+ *   contradiction-candidate        same subject stated with different numeric values in different places
+ *   missing-required-section       expected heading absent (when requiredSections is supplied)
+ *   possibly-stale                 file older than staleAfterDays (when supplied) — mtime based
+ * It does not judge whether a citation semantically SUPPORTS a claim; that remains an LLM/human step.
+ *
+ * CLI: node audit-docs.mjs <corpusDir> [--required <file.json>] [--stale-after-days N] [--out report.json]
+ *      requiredSections JSON: { "<relative path or glob>": ["Heading A", "Heading B"] }
  */
 import { pathToFileURL } from "node:url";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join, dirname, normalize, relative } from "node:path";
 
-const STRONG_CLAIM_RE = /\b(always|never|guaranteed|100%|zero downtime|fully compliant)\b/i;
+// Absolute assurance phrases are always checked; bare absolutes (always/never/every/all) only when the
+// sentence also states a metric or a reliability/performance property. Imperatives ("Never fabricate X")
+// are rules, not factual claims, and negated assurances ("not a guarantee") are not claims either.
+const ASSURANCE_RE = /\b(guarantee[sd]?|100\s?%|zero[- ]downtime|fully compliant|never (?:fails?|goes down|loses?)|always (?:available|up|on))\b/i;
+const ABSOLUTE_RE = /\b(always|never|every|all|instant(?:ly)?)\b/i;
+const PROPERTY_RE = /\b(respon\w*|available|availability|uptime|latency|fail\w*|lose|loss|lost|accura\w*|secure|succe\w*|fast\w*|reliab\w*|scal\w*|real[- ]time)\b/i;
+const METRIC_RE = /\d+(?:\.\d+)?\s*(%|ms|milliseconds?|seconds?|s\b|minutes?|hours?|days?|rps|qps)/i;
+const IMPERATIVE_RE = /^\W*(?:\d+[.)]\s*)?(?:\[ \]\s*)?(?:\*\*)?(never|always|do not|don't|must|should|avoid|ensure|keep|use|treat|report|record|flag)\b/i;
+const MODAL_RE = /\b(must|should|shall|may|do not|don't|is not allowed|are not allowed)\s+(?:\w+\s+){0,2}(never|always)\b|\b(never|always)\s+(?:be\s+)?(?:\w+ed|bundle|embed|commit|invent|claim|present|state|draw|answer|resolve|upgrade|fabricate|copy|modify|substitute|surface|rely|allow|assume|guess|let|recommend|publish|silently)\b/i;
+const NEGATED_RE = /\b(not|no|never|cannot|can't|isn't|aren't|doesn't|without)\b[^.]{0,25}\b(guarantee\w*|100\s?%|proof)/i;
+export function isUnsupportedStrongClaim(sentence) {
+  if (CITATION_RE.test(sentence) || IMPERATIVE_RE.test(sentence) || NEGATED_RE.test(sentence) || MODAL_RE.test(sentence)) return false;
+  if (ASSURANCE_RE.test(sentence)) return true;
+  return ABSOLUTE_RE.test(sentence) && (METRIC_RE.test(sentence) || PROPERTY_RE.test(sentence));
+}
+const CITATION_RE = /\[(?:source|src)\s*:[^\]]+\]/i;
+const INTERNAL_HOST_RE = /\/\/(?:[^/\s)]*\.(?:internal|corp|local|lan|intranet)\b|localhost\b|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(?:1[6-9]|2\d|3[01])\.\d+\.\d+)/i;
+const UNIT_RE = /(\d+(?:\.\d+)?)\s*(%|ms|milliseconds?|seconds?|minutes?|hours?|days?|weeks?|months?|years?|gb|mb|tb|requests?|users?|tickets?|retries|attempts|times)\b/gi;
+const STOP = new Set("the a an and or of to for in on at by with is are be been was were it its this that these those than then after before into from as per each every all any no not only also can may must will should would could within up down over under about we our you your they their there here which who what when where how via them its they him her his she he one two".split(" "));
+
+export const slugify = (t) => t.toLowerCase().trim().replace(/[`*~]/g, "").replace(/[^a-z0-9 _-]/g, "").replace(/ /g, "-"); // GitHub-compatible
+const stem = (w) => w.replace(/(ing|ed|es|s|e|d)$/, "");
+const contentWords = (s) => new Set(s.toLowerCase().replace(/\[[^\]]*\]|\([^)]*\)|`[^`]*`/g, " ").split(/[^a-z]+/).filter((w) => w.length > 2 && !STOP.has(w)).map(stem));
+const unitKey = (u) => u.toLowerCase().replace(/^(milliseconds?)$/, "ms").replace(/s$/, "");
+
+function headingsOf(text) {
+  const out = []; let fence = false;
+  for (const l of text.split("\n")) {
+    if (/^\s*(```|~~~)/.test(l)) { fence = !fence; continue; }
+    if (fence) continue;
+    const m = /^(#{1,6})\s+(.*?)\s*#*\s*$/.exec(l); if (m) out.push(m[2]);
+  }
+  for (const m of text.matchAll(/<h[1-6][^>]*>(.*?)<\/h[1-6]>/gis)) out.push(m[1].replace(/<[^>]+>/g, ""));
+  return out;
+}
 
-export function auditDocs({ corpusPath, inventory, evidenceIndex, fileTexts }) {
+/** Splits text into sentences with the line each sentence starts on; wrapped lines are joined. */
+function sentencesWithLines(text) {
+  const units = []; let fence = false; let cur = null;
+  text.split("\n").forEach((line, i) => {
+    if (/^\s*(```|~~~)/.test(line)) { fence = !fence; cur = null; return; }
+    if (fence) return;
+    if (/^\s*#{1,6}\s/.test(line) || /^\s*<!--/.test(line) || !line.trim()) { cur = null; return; }
+    if (/^\s*\|/.test(line)) { cur = null; units.push({ text: line.replace(/\|/g, " ").trim(), marks: [{ pos: 0, line: i + 1 }], table: true }); return; }
+    const startsItem = /^\s*(?:[-*+]|\d+[.)]|>)\s+/.test(line);
+    const piece = line.replace(/^\s*(?:[-*+]|>)\s+/, "").trim();
+    if (cur && !startsItem) { cur.marks.push({ pos: cur.text.length + 1, line: i + 1 }); cur.text += " " + piece; }
+    else { cur = { text: piece, marks: [{ pos: 0, line: i + 1 }] }; units.push(cur); }
+  });
+  const out = [];
+  for (const u of units) {
+    const re = /(?<=[.!?;])\s+(?=[A-Z`*(])|\s+—\s+/g; let start = 0; let m;
+    const push = (end) => { const t = u.text.slice(start, end).trim(); if (t) { const line = [...u.marks].reverse().find((k) => k.pos <= start)?.line ?? u.marks[0].line; out.push({ line, text: t, table: u.table }); } };
+    while ((m = re.exec(u.text))) { push(m.index); start = m.index + m[0].length; }
+    push(u.text.length);
+  }
+  return out;
+}
+
+const globRe = (g) => new RegExp("^" + g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\u0000").replace(/\*/g, "[^/]*").replace(/\u0000/g, ".*") + "$");
+
+export function auditDocs({ corpusPath, fileTexts, requiredSections = {}, staleAfterDays = null, now = Date.now() }) {
   const findings = [];
+  const files = Object.keys(fileTexts || {});
+  const headingCache = new Map();
+  const headingSlugs = (rel) => {
+    if (!headingCache.has(rel)) {
+      const text = fileTexts[rel] ?? (existsSync(join(corpusPath, rel)) && statSync(join(corpusPath, rel)).isFile() ? readFileSync(join(corpusPath, rel), "utf8") : "");
+      headingCache.set(rel, new Set(headingsOf(text).map(slugify)));
+    }
+    return headingCache.get(rel);
+  };
+  const resolveTarget = (from, target) => {
+    const [pathPart, anchor] = target.split("#");
+    const candidates = pathPart ? [normalize(join(dirname(from), pathPart)), normalize(pathPart)] : [from];
+    const hit = candidates.find((c) => !c.startsWith("..") && existsSync(join(corpusPath, c)));
+    return { file: hit ?? null, anchor: anchor ? decodeURIComponent(anchor) : null, pathPart };
+  };
 
-  // Broken internal references: look for markdown-style links in fileTexts and verify they resolve.
-  for (const [relPath, text] of Object.entries(fileTexts || {})) {
-    const linkRe = /\]\(([^)]+)\)/g;
-    let m;
-    while ((m = linkRe.exec(text))) {
-      const target = m[1];
-      if (/^https?:\/\//.test(target)) {
-        if (/\b(10\.\d+\.\d+\.\d+|192\.168\.|localhost|\.internal\b|\.corp\b)\b/.test(target)) {
-          findings.push({ category: "internal-looking-external-link", severity: "medium", source_path: relPath, detail: "Link matches internal-hostname heuristic (value redacted).", redacted: true });
+  for (const rel of files) {
+    const text = fileTexts[rel];
+    const lines = text.split("\n");
+    let fence = false;
+    lines.forEach((line, idx) => {
+      if (/^\s*(```|~~~)/.test(line)) { fence = !fence; return; }
+      if (fence) return;
+      const ln = idx + 1;
+      // links
+      for (const m of line.matchAll(/\]\(([^)\s]+)\)/g)) {
+        const target = m[1];
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target)) {
+          if (INTERNAL_HOST_RE.test(target)) findings.push({ category: "internal-looking-external-link", severity: "medium", source_path: rel, line: ln, detail: "Link points to an internal-looking host (value redacted). Confirm it may appear in shared documentation." });
+          continue;
         }
-        continue;
+        const r = resolveTarget(rel, target);
+        if (!r.file) findings.push({ category: "broken-internal-reference", severity: "high", source_path: rel, line: ln, detail: `Linked file "${r.pathPart}" does not exist in the corpus.` });
+        else if (r.anchor && /\.(md|markdown|html?)$/i.test(r.file) && !headingSlugs(r.file).has(slugify(r.anchor))) findings.push({ category: "broken-internal-reference", severity: "medium", source_path: rel, line: ln, detail: `Anchor "#${r.anchor}" not found among headings of "${r.file}".` });
       }
-      const resolved = join(corpusPath, relPath, "..", target);
-      if (!existsSync(resolved) && !existsSync(join(corpusPath, target))) {
-        findings.push({ category: "broken-internal-reference", severity: "high", source_path: relPath, detail: `Reference "${target}" does not resolve within the corpus.` });
+      if (/^\s*#{1,6}\s/.test(line)) return; // headings are not claims
+      // citations
+      for (const m of line.matchAll(/\[(?:source|src)\s*:\s*([^\]]+)\]/gi)) {
+        for (const ref of m[1].split(/[;,]\s*/)) {
+          const target = ref.trim().split(/\s/)[0];
+          if (!target || !/[./#]/.test(target)) continue;
+          const r = resolveTarget(rel, target);
+          if (!r.file) findings.push({ category: "unresolvable-citation", severity: "high", source_path: rel, line: ln, detail: `Citation target "${r.pathPart}" does not exist.` });
+          else if (r.anchor && /\.(md|markdown|html?)$/i.test(r.file) && !/^L\d/.test(r.anchor) && !headingSlugs(r.file).has(slugify(r.anchor))) findings.push({ category: "unresolvable-citation", severity: "medium", source_path: rel, line: ln, detail: `Citation anchor "#${r.anchor}" not found in "${r.file}".` });
+          else findings.push({ category: "citation-needs-support-check", severity: "info", source_path: rel, line: ln, detail: `Citation to "${target}" resolves; whether it actually supports the claim needs review.` });
+        }
       }
-    }
+    });
+  }
 
-    for (const line of text.split("\n")) {
-      if (STRONG_CLAIM_RE.test(line) && !/\[source:/i.test(line) && !/#/.test(line)) {
-        findings.push({ category: "unsupported-claim", severity: "medium", source_path: relPath, detail: `Strong claim without citation: "${line.trim().slice(0, 120)}"` });
-      }
+  // unsupported strong claims (sentence level; table rows included)
+  for (const rel of files) for (const sn of sentencesWithLines(fileTexts[rel])) if (isUnsupportedStrongClaim(sn.text)) findings.push({ category: "unsupported-claim", severity: "medium", source_path: rel, line: sn.line, detail: `Strong claim without citation: "${sn.text.slice(0, 140)}"` });
+
+  // contradiction candidates: similar statements with different numeric values in the same unit.
+  // Series/enumeration lines (the same sentence skeleton repeated >=3x in a file, e.g. a timing
+  // script or a changelog table) are NOT contradictions — they list different items — so exclude them.
+  const skeleton = (t) => t.toLowerCase().replace(/\d+(?:[.,:]\d+)?/g, "#").replace(/\s+/g, " ").trim();
+  const skelCount = new Map();
+  const rawClaims = [];
+  for (const rel of files) for (const s of sentencesWithLines(fileTexts[rel])) for (const m of s.text.matchAll(UNIT_RE)) {
+    const sk = rel + "\u0000" + skeleton(s.text); skelCount.set(sk, (skelCount.get(sk) || 0) + 1);
+    rawClaims.push({ rel, line: s.line, text: s.text, value: Number(m[1]), unit: unitKey(m[2]), words: contentWords(s.text), sk });
+  }
+  const claims = rawClaims.filter((c) => skelCount.get(c.sk) < 3); // drop repeated-template series
+  const seen = new Set(); const perFile = new Map(); const CAP = 40;
+  for (let i = 0; i < claims.length; i++) for (let j = i + 1; j < claims.length; j++) {
+    const a = claims[i], b = claims[j];
+    if (a.unit !== b.unit || a.value === b.value || (a.rel === b.rel && a.line === b.line)) continue;
+    if (a.sk === b.sk) continue; // identical skeleton across lines = same template, not a conflict
+    const inter = [...a.words].filter((w) => b.words.has(w)).length; const union = new Set([...a.words, ...b.words]).size;
+    if (!union || inter / union < 0.5 || inter < 4) continue; // require a strong subject overlap
+    const key = [a.rel, a.line, b.rel, b.line].join("|"); if (seen.has(key)) continue; seen.add(key);
+    const fkey = a.rel + "|" + b.rel; const n = perFile.get(fkey) || 0; if (n >= CAP) continue; perFile.set(fkey, n + 1);
+    findings.push({ category: "contradiction-candidate", severity: "high", source_path: a.rel, line: a.line, other: { source_path: b.rel, line: b.line }, detail: `"${a.text.slice(0, 100)}" (${a.value} ${a.unit}) vs "${b.text.slice(0, 100)}" (${b.value} ${b.unit}) — report both sides; do not pick one.` });
+  }
+
+  // required sections
+  for (const [pattern, required] of Object.entries(requiredSections || {})) {
+    const re = globRe(pattern);
+    for (const rel of files.filter((f) => f === pattern || re.test(f))) {
+      const have = new Set(headingsOf(fileTexts[rel]).map(slugify));
+      for (const h of required) if (!have.has(slugify(h))) findings.push({ category: "missing-required-section", severity: "medium", source_path: rel, line: null, detail: `Expected section "${h}" not found.` });
     }
   }
 
-  return { findings, totalFiles: Object.keys(fileTexts || {}).length };
+  // staleness (opt-in; mtime-based)
+  if (staleAfterDays != null && corpusPath) for (const rel of files) {
+    const p = join(corpusPath, rel); if (!existsSync(p)) continue;
+    const ageDays = (now - statSync(p).mtimeMs) / 86400000;
+    if (ageDays > staleAfterDays && !/last[- ]reviewed\s*:/i.test(fileTexts[rel])) findings.push({ category: "possibly-stale", severity: "low", source_path: rel, line: null, detail: `Not modified for ${Math.floor(ageDays)} days (threshold ${staleAfterDays}) and no "Last reviewed:" marker.` });
+  }
+
+  const order = { high: 0, medium: 1, low: 2, info: 3 };
+  findings.sort((a, b) => order[a.severity] - order[b.severity] || a.source_path.localeCompare(b.source_path) || (a.line ?? 0) - (b.line ?? 0));
+  const counts = {}; for (const f of findings) counts[f.category] = (counts[f.category] || 0) + 1;
+  return { findings, counts, totalFiles: files.length, notChecked: ["whether a resolvable citation semantically supports its claim", "non-numeric contradictions", ...(staleAfterDays == null ? ["staleness (pass --stale-after-days)"] : []), ...(Object.keys(requiredSections || {}).length ? [] : ["required sections (pass --required)"])] };
 }
 
-async function main() {
-  console.error("This script is intended to be imported programmatically with pre-loaded file texts.");
-  console.error("See skills/documentation-quality-auditor/SKILL.md for the full procedure.");
-  process.exit(0);
+export function loadCorpusTexts(corpusPath) {
+  const out = {};
+  (function walk(d) {
+    for (const e of readdirSync(d)) {
+      if ([".git", "node_modules"].includes(e)) continue;
+      const p = join(d, e);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (/\.(md|markdown|html?|txt)$/i.test(e)) out[relative(corpusPath, p).split("\\").join("/")] = readFileSync(p, "utf8");
+    }
+  })(corpusPath);
+  return out;
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  main();
+function main() {
+  const args = process.argv.slice(2);
+  const corpusPath = args.find((a, i) => !a.startsWith("--") && !["--required", "--stale-after-days", "--out"].includes(args[i - 1]));
+  if (!corpusPath) { console.error("Usage: node audit-docs.mjs <corpusDir> [--required <file.json>] [--stale-after-days N] [--out report.json]"); process.exit(1); }
+  const opt = (k) => { const i = args.indexOf(k); return i >= 0 ? args[i + 1] : undefined; };
+  try {
+    if (!existsSync(corpusPath) || !statSync(corpusPath).isDirectory()) throw new Error(`Corpus directory not found: ${corpusPath}`);
+    const requiredSections = opt("--required") ? JSON.parse(readFileSync(opt("--required"), "utf8")) : {};
+    const stale = opt("--stale-after-days"); 
+    const report = auditDocs({ corpusPath, fileTexts: loadCorpusTexts(corpusPath), requiredSections, staleAfterDays: stale != null ? Number(stale) : null });
+    const json = JSON.stringify(report, null, 2);
+    if (opt("--out")) writeFileSync(opt("--out"), json + "\n");
+    console.log(json);
+  } catch (err) { console.error(`audit-docs: ${err.message}`); process.exit(1); }
 }
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/skills/engineering-knowledge-transfer/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: engineering-knowledge-transfer
-description: >-
-  Generate onboarding guides, operational runbooks, handover documents, troubleshooting guides, and
-  role-specific learning paths from project evidence. Use this skill when a user needs to bring a new
-  engineer, operator, or reviewer up to speed on a target project, or when preparing a handover
-  between teams.
+description: "Generate onboarding guides, operational runbooks, handover documents, troubleshooting guides, and role-specific learning paths from project evidence. Use this skill when a user needs to bring a new engineer, operator, or reviewer up to speed on a target project, or when preparing a handover between teams."
 metadata:
   version: 1.0.0
   partOf: enterprise-project-intelligence-agent

package/skills/enterprise-ai-integration-planner/SKILL.md

@@ -1,13 +1,6 @@
 ---
 name: enterprise-ai-integration-planner
-description: >-
-  Discover, evaluate, design, prioritize, and plan AI integration opportunities for any existing
-  software project, including projects with no current AI capabilities. Use this skill once project
-  evidence exists (via project-documentation-discovery and/or software-reverse-engineering) and the
-  user wants to know where AI could help, whether it should, and how to adopt it safely. It compares
-  every AI proposal against the simplest viable non-AI alternative, scores feasibility
-  transparently, treats security/privacy/legal blockers as non-overridable, and never invents ROI,
-  accuracy, latency, or cost numbers.
+description: "Discover, evaluate, design, prioritize, and plan AI integration opportunities for any existing software project, including projects with no current AI capabilities. Use this skill once project evidence exists (via project-documentation-discovery and/or software-reverse-engineering) and the user wants to know where AI could help, whether it should, and how to adopt it safely. It compares every AI proposal against the simplest viable non-AI alternative, scores feasibility transparently, treats security/privacy/legal blockers as non-overridable, and never invents ROI, accuracy, latency, or cost numbers."
 metadata:
   version: 1.0.0
   partOf: enterprise-project-intelligence-agent
@@ -83,13 +76,18 @@ project into this public repository; use the blank template plus the synthetic e
 
 ### 4. Score feasibility transparently (§7.4)
 
-Run `scripts/score-opportunity.mjs` (or apply `references/feasibility-scoring.md` by hand) against
-each candidate across: business value, data readiness, integration feasibility, technical maturity,
-security readiness, evaluation feasibility, maintainability, cost efficiency. The script enforces the
-rule in `references/feasibility-scoring.md` §"Non-overridable blockers": if any critical
-security/privacy/legal/authorization blocker is flagged, the opportunity's recommendation is forced
-to `blocked` or `rework-required` regardless of the weighted score. Never report a numeric score as
-if it alone determines the recommendation.
+**Run** `scripts/score-opportunity.mjs` for every candidate — pass a JSON array of opportunities
+(`[{"id":"O1","businessValue":4,...,"blockers":[...]}]`) or a path to a `.json` file — and paste its
+JSON output (score, band, recommendation, explanation) into the assessment. Never hand-calculate
+weighted scores. Scores use the eight dimensions in `references/feasibility-scoring.md`; score `0`
+only when a dimension could not be assessed (the script then returns `insufficient-evidence`).
+
+Blockers have a fixed class (table in `references/feasibility-scoring.md`): structural blockers
+(`no-authorization-path`, `regulatory-prohibition`) force `blocked`; mitigable ones force
+`rework-required`. If a different design would avoid a structural blocker (e.g., a locally hosted
+model instead of a third-party API), list it as a **separate opportunity variant** and score it
+without that blocker only when the evidence supports that the blocker no longer applies. Never
+report a numeric score as if it alone determines the recommendation.
 
 ### 5. Design architecture alternatives (§7.5)
 

package/skills/enterprise-ai-integration-planner/references/feasibility-scoring.md

@@ -38,11 +38,32 @@ Positive criteria must never cancel out a critical blocker. Define blockers sepa
   action without human approval.
 - `blocker:regulatory-prohibition` — a named law, regulation, or binding internal policy prohibits it.
 
-**Rule**: if one or more blockers are present, the recommendation is forced to `blocked` (if the
-blocker is structural and cannot be mitigated in this design) or `rework-required` (if a concrete
-mitigation would remove the blocker), regardless of the weighted score. `scripts/score-opportunity.mjs`
-implements this rule and is covered by an automated test; do not reimplement the rule in a way that
-lets a numeric score override it.
+**Rule**: if one or more blockers are present, the recommendation is forced regardless of the weighted
+score. Each blocker has a fixed class — do not reclassify a blocker case-by-case:
+
+| Blocker | Class | Forced recommendation | Why |
+|---|---|---|---|
+| `blocker:no-authorization-path` | **structural** | `blocked` | No approved basis for this data use exists *in this design*. Changing the design (e.g., a locally hosted model) is a **new opportunity variant** that must be scored separately — without this blocker, but only if the authorization question is actually resolved for it. |
+| `blocker:regulatory-prohibition` | **structural** | `blocked` | A law/regulation/binding policy forbids it. |
+| `blocker:unresolved-pii-exposure` | mitigable | `rework-required` | A concrete mitigation (minimization, redaction, access scoping) can remove it. |
+| `blocker:no-access-control-on-retrieval` | mitigable | `rework-required` | Retrieval can be made to inherit source permissions. |
+| `blocker:irreversible-autonomous-action` | mitigable | `rework-required` | Add a human approval gate. |
+
+This table mirrors `STRUCTURAL_BLOCKERS` / `MITIGABLE_BLOCKERS` in `scripts/score-opportunity.mjs`;
+an automated test fails if they diverge. Do not reimplement the rule in a way that lets a numeric
+score override it.
+
+## Not-assessed dimensions
+
+A dimension scored `0` means "not assessed / insufficient evidence", never "very bad". If any
+dimension is `0` (and no structural blocker applies), the script returns
+`recommendation: "insufficient-evidence"` plus the list of `notAssessed` dimensions. Report the
+weighted score only as provisional and list the evidence needed.
+
+## Always use the script
+
+Compute every score with `scripts/score-opportunity.mjs` (single JSON object, an array of objects,
+or a path to a `.json` file) and quote its JSON output. Do not hand-calculate weighted scores.
 
 ## Required accompanying documentation per proposal
 

package/skills/enterprise-ai-integration-planner/scripts/score-opportunity.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { pathToFileURL } from "node:url";
+import { readFileSync } from "node:fs";
 /**
  * Transparent, reproducible feasibility scoring for one AI opportunity.
  * Implements the weighting formula and non-overridable-blocker rule documented in
@@ -13,7 +14,7 @@ import { pathToFileURL } from "node:url";
  *   import { scoreOpportunity } from "./score-opportunity.mjs";
  */
 
-const WEIGHTS = {
+export const WEIGHTS = {
   businessValue: 0.20,
   dataReadiness: 0.15,
   integrationFeasibility: 0.15,
@@ -24,12 +25,13 @@ const WEIGHTS = {
   costEfficiency: 0.075,
 };
 
-const STRUCTURAL_BLOCKERS = new Set([
+/** Blocker taxonomy — documented in references/feasibility-scoring.md (keep in sync; enforced by tests). */
+export const STRUCTURAL_BLOCKERS = new Set([
   "blocker:no-authorization-path",
   "blocker:regulatory-prohibition",
 ]);
 
-const MITIGABLE_BLOCKERS = new Set([
+export const MITIGABLE_BLOCKERS = new Set([
   "blocker:unresolved-pii-exposure",
   "blocker:no-access-control-on-retrieval",
   "blocker:irreversible-autonomous-action",
@@ -59,7 +61,6 @@ export function scoreOpportunity(input) {
     }
   }
 
-  let recommendation;
   let band;
   if (weightedScore >= 3.75) band = "go";
   else if (weightedScore >= 2.5) band = "rework-required";
@@ -67,14 +68,14 @@ export function scoreOpportunity(input) {
 
   const hasStructuralBlocker = blockers.some((b) => STRUCTURAL_BLOCKERS.has(b));
   const hasMitigableBlocker = blockers.some((b) => MITIGABLE_BLOCKERS.has(b));
+  // 0 means "not assessed / insufficient evidence" (feasibility-scoring.md), never a real low score.
+  const notAssessed = Object.entries(scores).filter(([, v]) => v === 0).map(([k]) => k);
 
-  if (hasStructuralBlocker) {
-    recommendation = "blocked";
-  } else if (hasMitigableBlocker) {
-    recommendation = "rework-required";
-  } else {
-    recommendation = band;
-  }
+  let recommendation;
+  if (hasStructuralBlocker) recommendation = "blocked";
+  else if (notAssessed.length) recommendation = "insufficient-evidence";
+  else if (hasMitigableBlocker) recommendation = "rework-required";
+  else recommendation = band;
 
   return {
     scores,
@@ -82,18 +83,34 @@ export function scoreOpportunity(input) {
     band,
     blockers,
     recommendation,
-    blockerOverrodeScore: recommendation !== band,
+    notAssessed,
+    blockerOverrodeScore: hasStructuralBlocker || (hasMitigableBlocker && recommendation !== band),
+    explanation: hasStructuralBlocker
+      ? "Structural blocker present: recommendation forced to 'blocked' regardless of score."
+      : notAssessed.length
+        ? `Not assessed (score 0): ${notAssessed.join(", ")}. Gather evidence before deciding; the weighted score is provisional.`
+        : hasMitigableBlocker
+          ? "Mitigable blocker present: recommendation forced to 'rework-required' until the mitigation is in place."
+          : `Weighted score ${weightedScore} falls in band '${band}'.`,
   };
 }
 
 function main() {
   const arg = process.argv[2];
   if (!arg) {
-    console.error("Usage: node score-opportunity.mjs '<json-input>'");
+    console.error("Usage: node score-opportunity.mjs '<json-input>'  (or a path to a .json file)");
+    process.exit(1);
+  }
+  try {
+    const text = /^[\[{]/.test(arg.trim()) ? arg : readFileSync(arg, "utf8");
+    const input = JSON.parse(text);
+    const list = Array.isArray(input) ? input : [input];
+    const out = list.map((o) => ({ ...(o.id ? { id: o.id } : {}), ...scoreOpportunity(o) }));
+    console.log(JSON.stringify(Array.isArray(input) ? out : out[0], null, 2));
+  } catch (err) {
+    console.error(`score-opportunity: ${err.message}`);
     process.exit(1);
   }
-  const input = JSON.parse(arg);
-  console.log(JSON.stringify(scoreOpportunity(input), null, 2));
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/skills/presentation-compliance-validator/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: presentation-compliance-validator
-description: >-
-  Convert configurable, user-supplied presentation guidelines into structured rules and validate a
-  generated slide deck against them, reporting specific violations and corrective actions rather than
-  a vague score. Use this skill after corporate-presentation-generator produces a draft, or whenever
-  a user wants to check an existing deck against their own corporate guidelines. Never hardcodes a
-  specific organization's proprietary rules; always reads rules from a user-supplied or default
-  configuration.
+description: "Convert configurable, user-supplied presentation guidelines into structured rules and validate a generated slide deck against them, reporting specific violations and corrective actions rather than a vague score. Use this skill after corporate-presentation-generator produces a draft, or whenever a user wants to check an existing deck against their own corporate guidelines. Never hardcodes a specific organization's proprietary rules; always reads rules from a user-supplied or default configuration."
 metadata:
   version: 1.0.0
   partOf: enterprise-project-intelligence-agent
@@ -33,14 +27,18 @@ separating what was checked automatically from what needs human judgment.
 
 ## Execution procedure
 
-1. **Load the rule set.** Split rules into `explicit` (directly from the supplied config),
-   `derived` (a reasonable interpretation the tool computed, e.g., "max bullets" derived from a
-   stated "content density" guideline), `optional-recommendation`, and `human-review-required`
-   (anything semantic/visual that cannot be deterministically checked, e.g., "diagram looks
-   professional").
-2. **Run deterministic checks** with `scripts/validate-deck.mjs`: required sections present, bullet
-   count per slide, title presence, footer/page-number presence, citation markers present on slides
-   with numeric claims, font/color values matching the declared palette when the format exposes them.
+1. **Build or load the rule set.** If the user supplied prose guidelines (a brand guide, a style
+   PDF exported to text), convert them with the procedure in `references/rule-schema.md`
+   §"Converting a user's prose guideline into a rule set": every statement goes into exactly one
+   bucket — `explicit` (measurable, stated), `derived` (qualitative, interpreted; record it in
+   `derivedRules`), `optionalRecommendations`, or `humanReviewOnly` (semantic/visual). If a JSON
+   rule set was supplied, use it as-is.
+2. **Run deterministic checks** with
+   `node scripts/validate-deck.mjs <deck.json> <rules.json>`. The script first validates the rule
+   set; if it returns `schemaErrors`, report them and stop. Otherwise it checks required sections,
+   bullet count, titles, footer/page numbers, citations on numeric claims, and palette/typography
+   values when the deck exposes them. If you only have a Markdown outline, convert it first with
+   `skills/corporate-presentation-generator/scripts/outline-to-deck-json.mjs`.
 3. **Flag semantic/visual items** for human review rather than guessing a pass/fail (e.g., actual
    visual balance, logo placement in a rendered image, diagram aesthetic quality).
 4. **Report specific violations**: rule ID, slide number, what was found, what was expected, and a
@@ -51,6 +49,8 @@ separating what was checked automatically from what needs human judgment.
 ## Expected outputs
 
 - A compliance report listing: rule ID, severity, slide reference, finding, corrective action.
+- When guidelines were converted: the rule-set JSON plus a table showing each guideline statement →
+  bucket (explicit / derived / optional / human-review).
 - A human-review list for semantic/visual items.
 - An overall pass/fail only for rules marked `blocking` in the rule set; non-blocking rules are
   reported as recommendations.

package/skills/presentation-compliance-validator/references/rule-schema.md

@@ -3,22 +3,79 @@
 ```json
 {
   "name": "string - name of the guideline set (user-supplied)",
-  "requiredSections": ["string, e.g. Executive Summary", "Risks and Decisions"],
+  "source": "optional - where the rules came from, e.g. 'brand-guide.pdf §3' (no proprietary text)",
+  "requiredSections": ["Executive Summary", "Risks and Decisions"],
   "maxBulletsPerSlide": 6,
   "requireTitleOnEverySlide": true,
   "requireFooterOrPageNumber": true,
   "requireCitationOnNumericClaims": true,
   "palette": { "primary": "#RRGGBB", "text": "#RRGGBB", "background": "#RRGGBB", "risk": "#RRGGBB" },
   "typography": { "titleFont": "string", "bodyFont": "string" },
-  "blockingRuleIds": ["required-sections", "max-bullets"],
-  "humanReviewOnly": ["visual-balance", "diagram-aesthetics", "logo-placement"]
+  "blockingRuleIds": ["required-sections", "max-bullets", "require-title"],
+  "humanReviewOnly": ["visual-balance", "diagram-aesthetics", "logo-placement"],
+  "derivedRules": [{ "rule": "maxBulletsPerSlide", "from": "guideline text: 'keep slides sparse'", "interpretation": "6 bullets" }],
+  "optionalRecommendations": ["Prefer one key idea per slide"]
 }
 ```
 
-- `requiredSections`, `maxBulletsPerSlide`, `requireTitleOnEverySlide`, `requireFooterOrPageNumber`,
-  and `requireCitationOnNumericClaims` are deterministically checkable and should be in
-  `blockingRuleIds` if the organization wants them enforced as hard failures.
-- `palette`/`typography` are checkable only when the deck format exposes those properties; otherwise
-  the validator reports `not-checkable-from-this-format`.
-- `humanReviewOnly` entries are never auto-passed or auto-failed; they always appear in the
-  human-review list.
+## Field types (validated by `scripts/validate-deck.mjs` before any check runs)
+
+| Key | Type | Notes |
+|---|---|---|
+| `requiredSections` | array of non-empty strings | Matched case-insensitively against `deck.sections` **and** slide titles (a title may continue after `:`, `—`, or ` -`). |
+| `maxBulletsPerSlide` | positive integer | |
+| `requireTitleOnEverySlide`, `requireFooterOrPageNumber`, `requireCitationOnNumericClaims` | boolean | |
+| `palette`, `typography` | object of strings | Palette values must be `#RRGGBB`. |
+| `blockingRuleIds` | array of known rule ids (below) | Unknown ids are a schema error. |
+| `humanReviewOnly` | array of strings | Free-form; never auto-passed. |
+| `name`, `source`, `notes`, `derivedRules`, `optionalRecommendations` | informational | Not enforced. |
+
+Any other key, or a wrong type, makes the rule set **invalid**: the validator returns
+`{ "pass": false, "schemaErrors": [...], "stopped": "invalid rule set" }` and checks nothing.
+Fix the rule set rather than guessing intent.
+
+## Rule IDs emitted by the validator (use these in `blockingRuleIds`)
+
+| Rule id | Triggered by | Scope |
+|---|---|---|
+| `required-sections` | a `requiredSections` entry not found | deck |
+| `require-title` | `requireTitleOnEverySlide` and a slide without `title` | slide |
+| `max-bullets` | a slide with more than `maxBulletsPerSlide` bullets | slide |
+| `require-footer` | `requireFooterOrPageNumber` and `hasFooterOrPageNumber` false | slide |
+| `citation-on-numeric-claim` | `requireCitationOnNumericClaims` and `hasNumericClaim` without `citationsPresent` | slide |
+| `palette-<key>` / `typography-<key>` | deck exposes a different value than the rule | deck |
+| `palette-not-checkable` / `typography-not-checkable` | the deck format exposes no such metadata (severity `info`) | deck |
+
+Non-blocking findings are reported as `recommendation`; `pass` is false only when a blocking rule fails.
+
+## Deck JSON (validator input)
+
+```json
+{
+  "sections": ["Executive Summary", "Risks and Decisions"],
+  "palette": { "primary": "#2B6CB0" },
+  "slides": [
+    { "title": "Executive Summary", "bullets": ["..."], "notes": "...",
+      "hasFooterOrPageNumber": true, "hasNumericClaim": false, "citationsPresent": true }
+  ]
+}
+```
+
+`corporate-presentation-generator` produces this file from its Markdown outline with
+`skills/corporate-presentation-generator/scripts/outline-to-deck-json.mjs`.
+
+## Converting a user's prose guideline into a rule set
+
+1. Read the user-supplied guideline (never bundle it in this toolkit). For every statement decide
+   one bucket:
+   - **explicit** — measurable and stated (e.g. "no more than five bullets") → set the field directly;
+   - **derived** — stated qualitatively ("keep slides sparse") → set the field AND record the
+     interpretation in `derivedRules` so a human can confirm it;
+   - **optional recommendation** — stylistic advice → `optionalRecommendations`;
+   - **human review** — semantic or visual ("logo must breathe", "diagrams look premium") →
+     `humanReviewOnly`. Never convert these into automated pass/fail rules.
+2. Put a rule in `blockingRuleIds` only if the guideline makes it mandatory ("must", "required").
+3. Do not invent rules the guideline does not state; leave fields out instead.
+4. Record provenance in `source` (section numbers, not copied proprietary wording).
+5. Validate the result: `node scripts/validate-deck.mjs <deck.json> <rules.json>` reports schema errors
+   before anything else.