azcodr 1.5.1 → 2.0.0

package/scripts/validate/skills.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readTextOrFail, readSkillFolders } = require('./io.js');
+
+function frontMatterBlock(content, skill, fail) {
+  const lines = content.split('\n');
+  if (lines[0].trim() !== '---') {
+    fail(`Skill '${skill}' missing opening front matter delimiter (---)`);
+    return null;
+  }
+  const closingIdx = lines.slice(1).findIndex((l) => l.trim() === '---');
+  if (closingIdx === -1) {
+    fail(`Skill '${skill}' missing closing front matter delimiter (---)`);
+    return null;
+  }
+  // Scope metadata lookups to the front-matter block only. Searching the
+  // whole file let body prose or a fenced example satisfy the checks.
+  const frontMatter = lines.slice(1, closingIdx + 1).join('\n');
+  const nameMatch = frontMatter.match(/^name:\s*(.+)$/m);
+  if (!nameMatch || nameMatch[1].trim() !== skill) {
+    fail(`Skill '${skill}' front matter 'name:' does not match directory name`);
+    return null;
+  }
+  return frontMatter;
+}
+
+function extractSkillDescription(frontMatter) {
+  const descMatch = frontMatter.match(/^description:\s*(.+)$/m);
+  const desc = descMatch ? descMatch[1].trim() : '';
+  if (!/^[>|][-+]?$/.test(desc)) return desc;
+  // YAML block scalars (>- / |) put the real text on following indented
+  // lines. Reading only the `>-` marker measured a 2-char "description" and
+  // defeated the 1024-char context-budget cap, so fold them in.
+  const afterDesc = frontMatter.slice(frontMatter.indexOf(descMatch[0]) + descMatch[0].length);
+  const folded = afterDesc.split('\n')
+    .filter((l) => /^\s+\S/.test(l))
+    .map((l) => l.trim())
+    .join(' ');
+  return folded.trim();
+}
+
+function checkSkillDescription(desc, skill, ctx) {
+  if (!desc) {
+    ctx.fail(`Skill '${skill}' missing front matter 'description:'`);
+    return;
+  }
+  if (!/^Use when/i.test(desc)) ctx.warn(`Skill '${skill}' description should start with imperative 'Use when...'`);
+  if (!/do not use/i.test(desc)) ctx.warn(`Skill '${skill}' description should specify negative boundaries ('Do not use for...')`);
+  if (desc.length > 1024) ctx.fail(`Skill '${skill}' description exceeds 1024 chars (${desc.length} chars)`);
+}
+
+function checkSkillBody(checked, ctx) {
+  const lines = checked.content.split('\n');
+  if (lines.length > 500) ctx.warn(`Skill '${checked.skill}' exceeds 500 lines (${lines.length} lines). Offload details to references/.`);
+  else ctx.pass(`Skill '${checked.skill}': ${lines.length} lines, description valid (${checked.desc.length} chars).`);
+  if (!/What NOT to do/i.test(checked.content) && !/Gotchas/i.test(checked.content)) {
+    ctx.warn(`Skill '${checked.skill}' missing mandatory 'Gotchas & What NOT to Do' section`);
+  }
+}
+
+function checkOneSkill(skill, skillsDir, ctx) {
+  const skillFile = path.join(skillsDir, skill, 'SKILL.md');
+  if (!fs.existsSync(skillFile)) {
+    ctx.fail(`Skill '${skill}' missing SKILL.md`);
+    return;
+  }
+  const content = readTextOrFail(skillFile, `Skill '${skill}'`, ctx.fail);
+  if (content === null) return;
+  const frontMatter = frontMatterBlock(content, skill, ctx.fail);
+  if (frontMatter === null) return;
+  const desc = extractSkillDescription(frontMatter);
+  checkSkillDescription(desc, skill, ctx);
+  checkSkillBody({ content, desc, skill }, ctx);
+}
+
+function phaseSkills(ctx) {
+  ctx.log('');
+  ctx.heading('3. Checking Specialized Skills (.agents/skills)...');
+  const skillsDir = path.join(ctx.workspaceRoot, '.agents', 'skills');
+  if (!fs.existsSync(skillsDir)) {
+    ctx.fail(`Missing .agents/skills directory at ${skillsDir}`);
+    return 0;
+  }
+  const folders = readSkillFolders(skillsDir, ctx.fail);
+  let count = 0;
+  for (const skill of folders) {
+    count += 1;
+    checkOneSkill(skill, skillsDir, ctx);
+  }
+  ctx.pass(`Validated ${count} skills in .agents/skills/.`);
+  return count;
+}
+
+module.exports = { phaseSkills, checkOneSkill, extractSkillDescription, frontMatterBlock };

package/scripts/validate/text.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * Text helpers shared by the validator phases.
+ *
+ * Both exist because generated documentation routinely contains ADR headings,
+ * rule headers, and Core Mandate lines inside examples. Matching the raw file
+ * would mistake documentation ABOUT the contract for the contract itself.
+ */
+
+function stripHtmlComments(text) {
+  // Remove HTML comments, tolerating unclosed ones. A stray `<!--` from an
+  // editor's "comment selection" must not silently hide every ADR after it.
+  return text
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<!--[\s\S]*$/, '');
+}
+
+/**
+ * Removes fenced code blocks so that examples inside documentation are not
+ * mistaken for real content. Without this, a rule file whose only H1 and
+ * "Core Mandate" lines sit inside a ```md fence satisfies both checks, and a
+ * `#### ADR-001` shown as an example is counted as a real decision.
+ */
+function stripFencedCode(text) {
+  return text.replace(/^([ \t]*)(```|~~~)[\s\S]*?^\1\2[ \t]*$/gm, '');
+}
+
+module.exports = { stripHtmlComments, stripFencedCode };

package/scripts/validate-cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * CLI entry for the agentic-architecture validator.
+ *
+ * Deliberately separate from scripts/validate.js: keeping the library free of a
+ * `require.main` guard means requiring it never validates or exits, and it
+ * avoids a permanently-unreachable branch that blocks the 100% coverage gate.
+ */
+const { main } = require('./validate.js');
+
+main();

package/scripts/validate.js

@@ -3,6 +3,21 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { createReporter, readTextOrFail } = require('./validate/io.js');
+const textHelpers = require('./validate/text.js');
+const parityHelpers = require('./validate/parity.js');
+const ioHelpers = require('./validate/io.js');
+const { parseAdrLedger, checkAdrIndexConsistency, checkGlossaryPopulated } = require('./validate/adr.js');
+const { phaseRootConfig } = require('./validate/root.js');
+const { phaseRules } = require('./validate/rules.js');
+const { phaseSkills } = require('./validate/skills.js');
+const { phaseLinks } = require('./validate/links.js');
+
+/**
+ * NOTE: this module is a library. It never self-executes, so importing it from
+ * a test or another tool cannot trigger validation or call process.exit().
+ * The CLI entry point lives in `scripts/validate-cli.js`.
+ */
 
 function parseArgs(argv) {
   let root = '';
@@ -13,234 +28,113 @@ function parseArgs(argv) {
   return root || process.cwd();
 }
 
-function main() {
-  const workspaceRoot = path.resolve(parseArgs(process.argv.slice(2)));
-  let errors = 0;
-  let warnings = 0;
-
-  const pass = (msg) => console.log(`  ✅ ${msg}`);
-  const warn = (msg) => { warnings += 1; console.log(`  ⚠️  ${msg}`); };
-  const fail = (msg) => { errors += 1; console.log(`  ❌ ${msg}`); };
-
-  console.log(`🔍 Validating Agentic Architecture in: ${workspaceRoot}`);
-  console.log('--------------------------------------------------------------');
-
-  console.log('1. Checking Root Configuration & Symlinks...');
-  const agentsFile = path.join(workspaceRoot, 'AGENTS.md');
-  if (!fs.existsSync(agentsFile)) {
-    fail(`Missing root AGENTS.md at ${agentsFile}`);
-  } else {
-    pass('AGENTS.md exists.');
-    const lines = fs.readFileSync(agentsFile, 'utf-8').split('\n').length;
-    if (lines <= 120) pass(`AGENTS.md line count is lean: ${lines} lines (<= 120).`);
-    else if (lines <= 150) warn(`AGENTS.md line count is getting large: ${lines} lines (warn > 120).`);
-    else fail(`AGENTS.md exceeds maximum line limit: ${lines} lines (max 150).`);
-  }
-
-  const agentsContent = fs.existsSync(agentsFile) ? fs.readFileSync(agentsFile, 'utf-8') : '';
-
-  function isValidAgentsTarget(target) {
-    return target === 'AGENTS.md' || target === './AGENTS.md' || target === agentsFile;
+function reportMemoryLedger(mem, ctx) {
+  const { entryIds } = parseAdrLedger(mem);
+  if (!/^# /m.test(mem)) ctx.fail('memory.md missing H1 header');
+  // Uses the same parser as phase 6. The previous unanchored
+  // `/#### ADR-/` disagreed with phase 6's anchored form, so the validator
+  // contradicted itself within a single run.
+  else if (entryIds.length > 0) ctx.pass('memory.md contains ADR entries with valid envelope.');
+  else ctx.pass('memory.md is a clean slate (no ADRs yet; record ADR-001 during /lets-build).');
+  // Template ADRs start well past ADR-024. Match any ID >= 25 regardless of
+  // zero padding.
+  const highestAdr = Math.max(0, ...entryIds);
+  if (highestAdr >= 25 && /azcodr/i.test(mem)) {
+    ctx.warn('memory.md may contain template-internal ADRs; fresh projects must start at ADR-001.');
   }
+}
 
-  function checkParity(filePath, label, allowCopyFallback) {
-    let stat = null;
-    try { stat = fs.lstatSync(filePath); } catch { fail(`${label} is missing.`); return; }
-    if (stat.isSymbolicLink()) {
-      let target = '';
-      try { target = fs.readlinkSync(filePath); } catch { fail(`${label} readlink failed.`); return; }
-      const ok = label.endsWith('copilot-instructions.md')
-        ? (target === '../AGENTS.md' || target === agentsFile || target === 'AGENTS.md')
-        : isValidAgentsTarget(target);
-      if (ok) pass(`${label} is a valid symlink to AGENTS.md.`);
-      else fail(`${label} points to '${target}' instead of 'AGENTS.md'.`);
-      return;
-    }
-    if (stat.isFile()) {
-      const content = fs.readFileSync(filePath, 'utf-8');
-      const trimmed = content.trim();
-      if (trimmed === 'AGENTS.md' || trimmed === './AGENTS.md' || trimmed === agentsFile) {
-        pass(`${label} is a text pointer to AGENTS.md (symlink fallback).`);
-        return;
-      }
-      if (label.endsWith('copilot-instructions.md') && content.includes('AGENTS.md')) {
-        pass(`${label} references AGENTS.md (symlink fallback).`);
-        return;
-      }
-      if (allowCopyFallback && agentsContent && content === agentsContent) {
-        warn(`${label} is a byte-identical copy of AGENTS.md (Windows symlink fallback; drift risk).`);
-        return;
-      }
-      if (label === 'agents.md') {
-        try {
-          const entries = fs.readdirSync(workspaceRoot);
-          if (!entries.includes('agents.md') && entries.includes('AGENTS.md')) {
-            pass('agents.md is satisfied natively by AGENTS.md (case-insensitive filesystem).');
-            return;
-          }
-        } catch { /* fall through */ }
-      }
-      fail(`${label} is not a symbolic link.`);
-      return;
-    }
-    fail(`${label} is neither a symlink nor a regular file.`);
+function phaseMemory(ctx) {
+  ctx.log('');
+  ctx.heading('5. Checking Memory & ADR Ledger...');
+  const memoryFile = path.join(ctx.workspaceRoot, 'memory.md');
+  if (!fs.existsSync(memoryFile)) {
+    ctx.fail('Missing memory.md ADR ledger.');
+    return;
   }
+  // readTextOrFail already reported any read failure; skip the analysis.
+  const mem = readTextOrFail(memoryFile, 'memory.md', ctx.fail);
+  if (mem !== null) reportMemoryLedger(mem, ctx);
+}
 
-  checkParity(path.join(workspaceRoot, 'CLAUDE.md'), 'CLAUDE.md', true);
-  const lowerPath = path.join(workspaceRoot, 'agents.md');
-  try {
-    const entries = fs.readdirSync(workspaceRoot);
-    const hasUpper = entries.includes('AGENTS.md');
-    const hasLowerExact = entries.includes('agents.md');
-    if (hasUpper && !hasLowerExact) {
-      let appearsSame = false;
-      try { appearsSame = fs.existsSync(lowerPath); } catch { appearsSame = false; }
-      if (appearsSame) {
-        pass('agents.md is satisfied natively by AGENTS.md (case-insensitive filesystem).');
-      } else {
-        checkParity(lowerPath, 'agents.md', true);
-      }
-    } else {
-      checkParity(lowerPath, 'agents.md', true);
-    }
-  } catch {
-    checkParity(lowerPath, 'agents.md', true);
+function phaseLedger(ctx) {
+  ctx.log('');
+  ctx.heading('6. Checking ADR Index Consistency...');
+  const consistency = checkAdrIndexConsistency(ctx.workspaceRoot, ctx.fail, ctx.pass);
+  if (consistency === 'indexed' || consistency === 'inconsistent') {
+    checkGlossaryPopulated(ctx.workspaceRoot, { fail: ctx.fail, pass: ctx.pass, warn: ctx.warn });
   }
-  checkParity(path.join(workspaceRoot, 'GEMINI.md'), 'GEMINI.md', true);
-  checkParity(path.join(workspaceRoot, '.cursorrules'), '.cursorrules', true);
-  checkParity(path.join(workspaceRoot, '.windsurfrules'), '.windsurfrules', true);
-  const githubDir = path.join(workspaceRoot, '.github');
-  if (fs.existsSync(githubDir) && fs.statSync(githubDir).isDirectory()) {
-    const copilot = path.join(githubDir, 'copilot-instructions.md');
-    if (fs.existsSync(copilot)) {
-      checkParity(copilot, '.github/copilot-instructions.md', true);
-    } else {
-      warn('.github/copilot-instructions.md is missing (run scaffold to restore harness parity).');
-    }
-    if (!fs.existsSync(path.join(githubDir, 'workflows'))) {
-      warn('.github/workflows is missing (CI will not run in scaffolded projects).');
-    }
-  }
-
-  if (fs.existsSync(path.join(workspaceRoot, '.gitignore'))) pass('.gitignore exists.');
-  else fail('Missing .gitignore');
+}
 
-  console.log('');
-  console.log('2. Checking Progressive Disclosure Rules...');
-  const rulesDir = path.join(workspaceRoot, 'docs', 'rules');
-  if (!fs.existsSync(rulesDir)) {
-    fail(`Missing docs/rules directory at ${rulesDir}`);
-  } else {
-    const files = fs.readdirSync(rulesDir).filter((f) => f.endsWith('.md'));
-    let count = 0;
-    for (const name of files) {
-      count += 1;
-      const fp = path.join(rulesDir, name);
-      const content = fs.readFileSync(fp, 'utf-8');
-      const stat = fs.statSync(fp);
-      if (!/^# /m.test(content)) fail(`Rule ${name} missing H1 header (# Title)`);
-      if (!/^> \*\*Core Mandate:\*\*/m.test(content)) warn(`Rule ${name} missing standardized '> **Core Mandate:**' summary`);
-      if (stat.size > 24000) warn(`Rule ${name} exceeds 24KB token-economy cap (${stat.size} bytes)`);
-    }
-    pass(`Validated ${count} modular rule files in docs/rules/.`);
-  }
+function buildValidationContext(workspaceRoot, reporter, counts) {
+  return {
+    workspaceRoot,
+    agentsFile: '',
+    agentsContent: '',
+    pass: reporter.pass,
+    warn: (msg) => { counts.warnings += 1; reporter.warn(msg); },
+    fail: (msg) => { counts.errors += 1; reporter.fail(msg); },
+    log: reporter.log,
+    heading: reporter.heading,
+    broken: [],
+    linkCount: 0,
+    visitedRealPaths: new Set()
+  };
+}
 
-  console.log('');
-  console.log('3. Checking Specialized Skills (.agents/skills)...');
-  const skillsDir = path.join(workspaceRoot, '.agents', 'skills');
-  if (!fs.existsSync(skillsDir)) {
-    fail(`Missing .agents/skills directory at ${skillsDir}`);
+function reportSummary(counts, reporter) {
+  reporter.log('');
+  reporter.log('--------------------------------------------------------------');
+  if (counts.errors === 0) {
+    reporter.log(`🎉 SUCCESS: All agentic configurations are valid and healthy! (${counts.warnings} warnings)`);
   } else {
-    const folders = fs.readdirSync(skillsDir).filter((f) => fs.statSync(path.join(skillsDir, f)).isDirectory());
-    let count = 0;
-    for (const skill of folders) {
-      count += 1;
-      const skillFile = path.join(skillsDir, skill, 'SKILL.md');
-      if (!fs.existsSync(skillFile)) { fail(`Skill '${skill}' missing SKILL.md`); continue; }
-      const content = fs.readFileSync(skillFile, 'utf-8');
-      const lines = content.split('\n');
-      if (lines[0].trim() !== '---') { fail(`Skill '${skill}' missing opening front matter delimiter (---)`); continue; }
-      const closing = lines.slice(1).findIndex((l) => l.trim() === '---');
-      if (closing === -1) fail(`Skill '${skill}' missing closing front matter delimiter (---)`);
-      const nameMatch = content.match(/^name:\s*(.+)$/m);
-      if (!nameMatch || nameMatch[1].trim() !== skill) fail(`Skill '${skill}' front matter 'name:' does not match directory name`);
-      const descMatch = content.match(/^description:\s*(.+)$/m);
-      const desc = descMatch ? descMatch[1].trim() : '';
-      if (!desc) {
-        fail(`Skill '${skill}' missing front matter 'description:'`);
-      } else {
-        if (!/^Use when/.test(desc)) warn(`Skill '${skill}' description should start with imperative 'Use when...'`);
-        if (!/do not use/i.test(desc)) warn(`Skill '${skill}' description should specify negative boundaries ('Do not use for...')`);
-        if (desc.length > 1024) fail(`Skill '${skill}' description exceeds 1024 chars (${desc.length} chars)`);
-      }
-      if (lines.length > 500) warn(`Skill '${skill}' exceeds 500 lines (${lines.length} lines). Offload details to references/.`);
-      else pass(`Skill '${skill}': ${lines.length} lines, description valid (${desc.length} chars).`);
-      if (!/What NOT to do/i.test(content) && !/Gotchas/i.test(content)) {
-        warn(`Skill '${skill}' missing mandatory 'Gotchas & What NOT to Do' section`);
-      }
-    }
-    pass(`Validated ${count} skills in .agents/skills/.`);
+    reporter.log(`🚨 FAILURE: Found ${counts.errors} error(s) and ${counts.warnings} warning(s) in agentic configurations.`);
   }
+}
 
-  console.log('');
-  console.log('4. Checking Markdown Internal Links & Cross-References...');
-  const broken = [];
-  let totalLinks = 0;
-  function walk(dir) {
-    let entries = [];
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
-    for (const entry of entries) {
-      if (entry.name === '.git' || entry.name === 'node_modules') continue;
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) walk(full);
-      else if (entry.isFile() && entry.name.endsWith('.md')) checkFile(full);
-    }
-  }
-  function checkFile(filePath) {
-    const content = fs.readFileSync(filePath, 'utf-8');
-    const dir = path.dirname(filePath);
-    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
-    let m;
-    while ((m = regex.exec(content)) !== null) {
-      const target = m[2].trim();
-      if (/^(https?:|mailto:|#|conversation:\/\/|file:\/\/)/.test(target)) continue;
-      const clean = target.split('#')[0];
-      if (!clean) continue;
-      totalLinks += 1;
-      if (!fs.existsSync(path.normalize(path.join(dir, clean)))) {
-        broken.push(`${path.relative(workspaceRoot, filePath)} -> ${target}`);
-      }
-    }
-  }
-  walk(workspaceRoot);
-  if (broken.length === 0) pass(`Validated ${totalLinks} internal links across workspace (0 broken links).`);
-  else for (const b of broken) fail(`Broken markdown link: ${b}`);
-
-  console.log('');
-  console.log('5. Checking Memory & ADR Ledger...');
-  const memoryFile = path.join(workspaceRoot, 'memory.md');
-  if (!fs.existsSync(memoryFile)) {
-    fail('Missing memory.md ADR ledger.');
-  } else {
-    const mem = fs.readFileSync(memoryFile, 'utf-8');
-    const withoutComments = mem.replace(/<!--[\s\S]*?-->/g, '');
-    if (!/^# /m.test(mem)) fail('memory.md missing H1 header');
-    else if (/#### ADR-/.test(withoutComments)) pass('memory.md contains ADR entries with valid envelope.');
-    else pass('memory.md is a clean slate (no ADRs yet; record ADR-001 during /lets-build).');
-    if (/ADR-025|ADR-028/.test(withoutComments) && /azcodr/i.test(mem)) {
-      warn('memory.md may contain template-internal ADRs; fresh projects must start at ADR-001.');
-    }
-  }
+function runValidation(workspaceRoot, reporter = createReporter()) {
+  // Counters live here, not on the reporter: an injected reporter only needs
+  // pass/warn/fail to observe outcomes, and the tally must not depend on the
+  // reporter's shape.
+  const counts = { errors: 0, warnings: 0 };
+  const ctx = buildValidationContext(workspaceRoot, reporter, counts);
+  reporter.heading(`🔍 Validating Agentic Architecture in: ${workspaceRoot}`);
+  reporter.log('--------------------------------------------------------------');
+  phaseRootConfig(ctx);
+  const validatedRules = phaseRules(ctx);
+  const validatedSkills = phaseSkills(ctx);
+  phaseLinks(ctx);
+  phaseMemory(ctx);
+  phaseLedger(ctx);
+  reportSummary(counts, reporter);
+  return {
+    errors: counts.errors,
+    warnings: counts.warnings,
+    validatedRules,
+    validatedSkills,
+    totalLinks: ctx.linkCount,
+    brokenLinks: ctx.broken
+  };
+}
 
-  console.log('');
-  console.log('--------------------------------------------------------------');
-  if (errors === 0) {
-    console.log(`🎉 SUCCESS: All agentic configurations are valid and healthy! (${warnings} warnings)`);
-    process.exit(0);
-  } else {
-    console.log(`🚨 FAILURE: Found ${errors} error(s) and ${warnings} warning(s) in agentic configurations.`);
-    process.exit(1);
-  }
+function main(argv = process.argv.slice(2), exit = process.exit) {
+  const workspaceRoot = path.resolve(parseArgs(argv));
+  const result = runValidation(workspaceRoot);
+  return exit(result.errors === 0 ? 0 : 1);
 }
 
-main();
+module.exports = {
+  runValidation,
+  parseArgs,
+  createReporter,
+  main,
+  parseAdrLedger,
+  checkAdrIndexConsistency,
+  checkGlossaryPopulated,
+  evaluateParityTarget: parityHelpers.evaluateParityTarget,
+  isValidAgentsTarget: parityHelpers.isValidAgentsTarget,
+  createLowercaseParityLink: parityHelpers.createLowercaseParityLink,
+  stripHtmlComments: textHelpers.stripHtmlComments,
+  stripFencedCode: textHelpers.stripFencedCode,
+  walkMarkdown: ioHelpers.walkMarkdown
+};

package/.github/copilot-instructions.md

@@ -1 +0,0 @@
-../AGENTS.md