azcodr 1.5.2 → 2.1.0

package/scripts/validate/io.js

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Reporter seam. Tests inject a collector so assertions can read the exact
+ * pass/warn/fail outcome instead of scraping stdout.
+ */
+export function createReporter(sink = console) {
+  return {
+    pass: (msg) => sink.log(`  ✅ ${msg}`),
+    warn: (msg) => sink.log(`  ⚠️  ${msg}`),
+    fail: (msg) => sink.log(`  ❌ ${msg}`),
+    log: (msg) => sink.log(msg),
+    heading: (msg) => sink.log(msg)
+  };
+}
+
+/**
+ * Reads a UTF-8 text file, reporting rather than throwing on failure.
+ *
+ * Unguarded readFileSync calls crashed the whole run on a directory named
+ * `*.md`, an unreadable file, or a broken symlink, aborting every later phase
+ * and emitting a stack trace instead of a verdict.
+ */
+export function readTextOrFail(filePath, label, fail) {
+  try {
+    const st = fs.statSync(filePath);
+    if (!st.isFile()) {
+      fail(`${label} is not a regular file (${st.isDirectory() ? 'it is a directory' : 'special file'}).`);
+      return null;
+    }
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    fail(`Could not read ${label}: ${err.code || err.message}`);
+    return null;
+  }
+}
+
+/** Recursively collects markdown files under `root`. */
+export function walkMarkdown(root, label, fail) {
+  const out = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (err) {
+      fail(`Could not list ${label} directory ${dir}: ${err.code || err.message}`);
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.name === '.git' || entry.name === 'node_modules') continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.name.toLowerCase().endsWith('.md')) {
+        out.push(full);
+      }
+    }
+  }
+  return out.sort();
+}
+
+/** Lists skill directories, skipping symlinks that cannot be resolved. */
+export function readSkillFolders(skillsDir, fail) {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  } catch (err) {
+    fail(`Could not list skills directory: ${err.code || err.message}`);
+    return [];
+  }
+  const folders = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    folders.push(entry.name);
+  }
+  return folders;
+}
+
+export default { createReporter, readTextOrFail, walkMarkdown, readSkillFolders };

package/scripts/validate/links.js

@@ -0,0 +1,166 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readTextOrFail } from './io.js';
+import { stripFencedCode } from './text.js';
+
+function normalizeLinkTarget(rawTarget) {
+  let target = rawTarget.trim();
+  if (!target) return null;
+  // Link titles: [x](./a.md "Title") and 'Title' / (Title).
+  target = target.replace(/\s+(?:"[^"]*"|'[^']*'|\([^)]*\))$/, '').trim();
+  // Angle-bracket destinations: [x](<./a.md>)
+  const angled = target.match(/^<([^>]*)>$/);
+  if (angled) target = angled[1].trim();
+  // Strip a query string; strip a fragment.
+  const display = target.split('#')[0].split('?')[0];
+  if (!display) return null;
+  // Schemes, case-insensitively. Protocol-relative and Windows absolute
+  // paths are external too.
+  if (/^[a-z][a-z0-9+.-]*:/i.test(display)) return null;
+  if (display.startsWith('//')) return null;
+  if (/^[a-z]:[\\/]/i.test(display)) return null;
+  // Percent-decode so ./exists%2emd resolves like a renderer would.
+  try {
+    return { target: decodeURIComponent(display), display };
+  } catch {
+    return { target: display, display };
+  }
+}
+
+function recordLinkTarget(link, ctx) {
+  const normalized = normalizeLinkTarget(link.rawTarget);
+  if (normalized === null) return;
+  ctx.linkCount += 1;
+  const resolved = path.normalize(path.join(link.dir, normalized.target));
+  if (!fs.existsSync(resolved)) {
+    ctx.broken.push(`${path.relative(ctx.workspaceRoot, link.filePath)} -> ${normalized.display}`);
+  }
+}
+
+function collectInlineLinks(job, ctx) {
+  // Inline links: [text](target). Tolerates nested brackets in the link text,
+  // which previously made `[click [here] now](./x)` unmatchable.
+  const inline = /\[((?:[^\][]|\[[^\][]*\])*)\]\(([^)]*)\)/g;
+  let m;
+  while ((m = inline.exec(job.live)) !== null) {
+    const display = m[2].trim() || '(empty target)';
+    recordLinkTarget({ rawTarget: m[2], display, dir: job.dir, filePath: job.filePath }, ctx);
+  }
+}
+
+function collectReferenceLinks(job, ctx) {
+  // Reference-style definitions: [ref]: ./target
+  const reference = /^\s{0,3}\[[^\]]+\]:\s*(\S+)/gm;
+  let m;
+  while ((m = reference.exec(job.live)) !== null) {
+    recordLinkTarget({ rawTarget: m[1], display: m[1], dir: job.dir, filePath: job.filePath }, ctx);
+  }
+}
+
+function collectHtmlAnchors(job, ctx) {
+  // HTML anchors: <a href="./target">
+  const html = /<a\s[^>]*href\s*=\s*["']([^"']+)["']/gi;
+  let m;
+  while ((m = html.exec(job.live)) !== null) {
+    recordLinkTarget({ rawTarget: m[1], display: m[1], dir: job.dir, filePath: job.filePath }, ctx);
+  }
+}
+
+function checkFile(filePath, ctx) {
+  // An unreadable markdown file must be reported, not allowed to abort the
+  // entire validation run: the remaining files still need checking.
+  const content = readTextOrFail(filePath, `markdown file ${path.relative(ctx.workspaceRoot, filePath)}`, ctx.fail);
+  if (content === null) return;
+  const job = {
+    live: stripFencedCode(content),
+    dir: path.dirname(filePath),
+    filePath
+  };
+  collectInlineLinks(job, ctx);
+  collectReferenceLinks(job, ctx);
+  collectHtmlAnchors(job, ctx);
+}
+
+function reportUnreadableDir(dir, err, ctx) {
+  // A silently-skipped subtree yields "0 broken links" derived from zero
+  // coverage, which is the worst outcome a checker can produce: a green
+  // result that proves nothing. Report what could not be read instead.
+  if (err instanceof RangeError) {
+    // Stack exhaustion (needs a tree thousands of levels deep -- not
+    // reproducible portably). Abort loudly rather than pretending clean.
+    ctx.fail(`Directory traversal exhausted the stack at ${path.relative(ctx.workspaceRoot, dir) || '.'}; link validation is incomplete.`);
+    return;
+  }
+  ctx.warn(`Skipped unreadable directory ${path.relative(ctx.workspaceRoot, dir) || '.'}: ${err.code || err.message}`);
+}
+
+function followSymlinkEntry(full, ctx) {
+  let real = null;
+  try {
+    real = fs.realpathSync(full);
+  } catch {
+    real = null;
+  }
+  if (real === null) {
+    ctx.warn(`Skipped dangling symlink ${path.relative(ctx.workspaceRoot, full)}`);
+    return;
+  }
+  if (ctx.visitedRealPaths.has(real)) return;
+  ctx.visitedRealPaths.add(real);
+  let st = null;
+  try {
+    st = fs.statSync(full);
+  } catch {
+    st = null;
+  }
+  if (st && st.isDirectory()) walk(full, ctx);
+  else if (full.endsWith('.md')) checkFile(full, ctx);
+}
+
+function visitEntry(entry, full, ctx) {
+  if (entry.isDirectory()) {
+    walk(full, ctx);
+    return;
+  }
+  // Symlink following is unreachable on Windows without Developer Mode, so the
+  // isSymbolicLink() arm is covered only on hosts that allow it.
+  if (entry.isSymbolicLink()) {
+    followSymlinkEntry(full, ctx);
+    return;
+  }
+  if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) checkFile(full, ctx);
+}
+
+function walk(dir, ctx) {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    reportUnreadableDir(dir, err, ctx);
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name === '.git' || entry.name === 'node_modules') continue;
+    visitEntry(entry, path.join(dir, entry.name), ctx);
+  }
+}
+
+function seedVisitedPaths(ctx) {
+  try {
+    ctx.visitedRealPaths.add(fs.realpathSync(ctx.workspaceRoot));
+  } catch {
+    // Unresolvable root: the walk reports each missing file individually.
+  }
+}
+
+function phaseLinks(ctx) {
+  ctx.log('');
+  ctx.heading('4. Checking Markdown Internal Links & Cross-References...');
+  seedVisitedPaths(ctx);
+  walk(ctx.workspaceRoot, ctx);
+  if (ctx.broken.length === 0) ctx.pass(`Validated ${ctx.linkCount} internal links across workspace (0 broken links).`);
+  else for (const b of ctx.broken) ctx.fail(`Broken markdown link: ${b}`);
+}
+
+export { phaseLinks, checkFile, normalizeLinkTarget };
+export default { phaseLinks, checkFile, normalizeLinkTarget };

package/scripts/validate/parity.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+
+/**
+ * Harness-parity verdicts, kept free of filesystem I/O.
+ *
+ * Callers pass in what lstat/readlink/readFile observed, because symlink
+ * creation is unavailable on some hosts -- Windows without Developer Mode
+ * returns EPERM -- so the symlink verdicts would otherwise be unreachable in
+ * CI on the platform matrix that matters most.
+ */
+
+/**
+ * The three target spellings a harness-parity file may legitimately use.
+ * Pure so it can be unit-tested without touching the filesystem.
+ */
+export function isValidAgentsTarget(target, agentsFile) {
+  const normalized = target.replace(/\\/g, '/');
+  const rootNormalized = agentsFile.replace(/\\/g, '/');
+  return normalized === 'AGENTS.md' || normalized === './AGENTS.md' || normalized === rootNormalized;
+}
+
+function symlinkVerdict(ctx) {
+  const { label, linkTarget, agentsFile } = ctx;
+  const normalized = linkTarget.replace(/\\/g, '/');
+  const isCopilot = label.endsWith('copilot-instructions.md');
+  const ok = isCopilot
+    ? (normalized === '../AGENTS.md'
+      || normalized === agentsFile.replace(/\\/g, '/')
+      || normalized === 'AGENTS.md')
+    : isValidAgentsTarget(linkTarget, agentsFile);
+  if (ok) return { kind: 'pass', message: `${label} is a valid symlink to AGENTS.md.` };
+  return { kind: 'fail', message: `${label} points to '${linkTarget}' instead of 'AGENTS.md'.` };
+}
+
+function textPointerVerdict(ctx) {
+  const { label, agentsFile, content } = ctx;
+  const trimmed = content.trim();
+  if (trimmed === 'AGENTS.md' || trimmed === './AGENTS.md' || trimmed === agentsFile) {
+    return { kind: 'pass', message: `${label} is a text pointer to AGENTS.md (symlink fallback).` };
+  }
+  const isCopilot = label.endsWith('copilot-instructions.md');
+  if (isCopilot && content.includes('AGENTS.md')) {
+    return { kind: 'pass', message: `${label} references AGENTS.md (symlink fallback).` };
+  }
+  return null;
+}
+
+function copyFallbackVerdict(ctx) {
+  const { label, allowCopyFallback, agentsContent, agentsContentMissing, content } = ctx;
+  if (allowCopyFallback && !agentsContentMissing && agentsContent && content === agentsContent) {
+    return {
+      kind: 'warn',
+      message: `${label} is a byte-identical copy of AGENTS.md (Windows symlink fallback; drift risk).`
+    };
+  }
+  return null;
+}
+
+function caseInsensitiveVerdict(ctx) {
+  const { label, entries } = ctx;
+  if (label === 'agents.md' && !entries.includes('agents.md') && entries.includes('AGENTS.md')) {
+    return {
+      kind: 'pass',
+      message: 'agents.md is satisfied natively by AGENTS.md (case-insensitive filesystem).'
+    };
+  }
+  return null;
+}
+
+function fileVerdict(ctx) {
+  const pointer = textPointerVerdict(ctx);
+  if (pointer !== null) return pointer;
+  const copy = copyFallbackVerdict(ctx);
+  if (copy !== null) return copy;
+  const native = caseInsensitiveVerdict(ctx);
+  if (native !== null) return native;
+  return { kind: 'fail', message: `${ctx.label} is not a symbolic link.` };
+}
+
+/**
+ * Decides whether a harness-parity entry is healthy, drifted, or outright wrong.
+ */
+export function evaluateParityTarget(ctx) {
+  if (ctx.isSymlink) return symlinkVerdict(ctx);
+  if (ctx.isFile) return fileVerdict(ctx);
+  // Anything lstat saw that is neither a symlink nor a regular file (a
+  // directory sitting in a parity slot, a socket, a device node).
+  return { kind: 'fail', message: `${ctx.label} is neither a symlink nor a regular file.` };
+}
+
+/**
+ * Creates the lowercase parity link, preferring a real symlink and falling back
+ * to a text pointer. Never throws: an unrecoverable workspace is reported so
+ * the caller can surface it.
+ *
+ * @returns {{created: boolean, strategy: 'symlink'|'pointer'|null, reason: string|null}}
+ */
+export function createLowercaseParityLink(lowerPath, fsImpl = fs) {
+  try {
+    fsImpl.symlinkSync('AGENTS.md', lowerPath);
+    return { created: true, strategy: 'symlink', reason: null };
+  } catch (symlinkErr) {
+    // Symlinks unavailable (Windows without Developer Mode): a text pointer
+    // preserves the invariant without duplicating content.
+    try {
+      fsImpl.writeFileSync(lowerPath, 'AGENTS.md\n', 'utf-8');
+      return { created: true, strategy: 'pointer', reason: null };
+    } catch (writeErr) {
+      return {
+        created: false,
+        strategy: null,
+        reason: `symlink failed (${symlinkErr.code || symlinkErr.message}); pointer write failed (${writeErr.code || writeErr.message})`
+      };
+    }
+  }
+}
+
+export default {
+  isValidAgentsTarget,
+  evaluateParityTarget,
+  createLowercaseParityLink
+};

package/scripts/validate/root.js

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readTextOrFail } from './io.js';
+import { evaluateParityTarget, createLowercaseParityLink } from './parity.js';
+
+function reportAgentsLineBudget(agentsText, ctx) {
+  const lines = agentsText.split('\n').length;
+  if (lines <= 120) ctx.pass(`AGENTS.md line count is lean: ${lines} lines (<= 120).`);
+  else if (lines <= 150) ctx.warn(`AGENTS.md line count is getting large: ${lines} lines (warn > 120).`);
+  else ctx.fail(`AGENTS.md exceeds maximum line limit: ${lines} lines (max 150).`);
+}
+
+function checkAgentsFile(ctx, agentsFile) {
+  if (!fs.existsSync(agentsFile)) {
+    ctx.fail(`Missing root AGENTS.md at ${agentsFile}`);
+    return null;
+  }
+  ctx.pass('AGENTS.md exists.');
+  const agentsText = readTextOrFail(agentsFile, 'AGENTS.md', ctx.fail);
+  if (agentsText === null) return null;
+  // A 0-byte root contract passed the line budget (''.split('\n').length
+  // is 1). Progressive disclosure with an empty root file discloses nothing.
+  if (agentsText.trim().length === 0) {
+    ctx.fail('AGENTS.md is empty; the root agent contract must define its operating rules.');
+    return agentsText;
+  }
+  reportAgentsLineBudget(agentsText, ctx);
+  return agentsText;
+}
+
+function readParityLink(filePath, stat) {
+  if (stat.isSymbolicLink()) {
+    try {
+      return { isSymlink: true, linkTarget: fs.readlinkSync(filePath) };
+    } catch (err) {
+      // A symlink that lstat sees but readlink cannot resolve (dangling on
+      // Windows, or a race) must be reported, never silently downgraded to a
+      // regular file that might then "pass" as a valid pointer.
+      return { readlinkError: err.message };
+    }
+  }
+  if (stat.isFile()) {
+    try {
+      return { isFile: true, content: fs.readFileSync(filePath, 'utf-8') };
+    } catch (err) {
+      return { readError: err.message };
+    }
+  }
+  return { neither: true };
+}
+
+function observeParityEntry(filePath, workspaceRoot) {
+  let stat = null;
+  try {
+    stat = fs.lstatSync(filePath);
+  } catch {
+    return { missing: true };
+  }
+  let entries = [];
+  try {
+    entries = fs.readdirSync(workspaceRoot);
+  } catch {
+    // Verdict degrades to a plain fail.
+  }
+  return { ...readParityLink(filePath, stat), entries };
+}
+
+function applyParityVerdict(label, verdict, ctx) {
+  if (verdict.kind === 'pass') ctx.pass(verdict.message);
+  else if (verdict.kind === 'warn') ctx.warn(verdict.message);
+  else ctx.fail(verdict.message);
+}
+
+function checkParity(filePath, target, ctx) {
+  const observed = observeParityEntry(filePath, ctx.workspaceRoot);
+  if (observed.missing) {
+    ctx.fail(`${target.label} is missing.`);
+    return;
+  }
+  if (observed.readlinkError) {
+    ctx.fail(`${target.label} readlink failed: ${observed.readlinkError}`);
+    return;
+  }
+  if (observed.readError) {
+    ctx.fail(`${target.label} could not be read: ${observed.readError}`);
+    return;
+  }
+  const verdict = evaluateParityTarget({
+    label: target.label,
+    allowCopyFallback: target.allowCopyFallback,
+    agentsContent: ctx.agentsContent,
+    agentsContentMissing: !ctx.agentsContent,
+    agentsFile: ctx.agentsFile,
+    entries: observed.entries || [],
+    isSymlink: Boolean(observed.isSymlink),
+    linkTarget: observed.linkTarget || null,
+    isFile: Boolean(observed.isFile),
+    content: observed.content || ''
+  });
+  applyParityVerdict(target.label, verdict, ctx);
+}
+
+function parityTarget(label) {
+  return { label, allowCopyFallback: true };
+}
+
+function restoreLowercaseParity(lowerPath, ctx) {
+  const outcome = createLowercaseParityLink(lowerPath, fs);
+  if (outcome.created) {
+    ctx.pass('Created agents.md parity link to AGENTS.md (case-sensitive filesystem).');
+  } else {
+    ctx.warn(`Could not restore agents.md parity: ${outcome.reason}`);
+  }
+  checkParity(lowerPath, parityTarget('agents.md'), ctx);
+}
+
+function checkLowercaseParity(ctx) {
+  const lowerPath = path.join(ctx.workspaceRoot, 'agents.md');
+  // An unreadable root degrades to an empty listing, which routes every file
+  // through checkParity and reports each one individually.
+  let rootEntries = [];
+  try {
+    rootEntries = fs.readdirSync(ctx.workspaceRoot);
+  } catch {
+    rootEntries = [];
+  }
+  if (rootEntries.includes('AGENTS.md') && !rootEntries.includes('agents.md')) {
+    // No exact 'agents.md' in the listing. On a case-insensitive filesystem the
+    // lower-cased path resolves to AGENTS.md itself, so the invariant already
+    // holds and MUST NOT be "restored": writing here would overwrite the very
+    // file it is trying to point at. Only repair on a genuinely
+    // case-sensitive filesystem, where the two paths are distinct entries.
+    if (fs.existsSync(lowerPath)) {
+      ctx.pass('agents.md is satisfied natively by AGENTS.md (case-insensitive filesystem).');
+    } else {
+      restoreLowercaseParity(lowerPath, ctx);
+    }
+    return;
+  }
+  checkParity(lowerPath, parityTarget('agents.md'), ctx);
+}
+
+function checkHarnessParity(ctx) {
+  const { workspaceRoot } = ctx;
+  checkParity(path.join(workspaceRoot, 'CLAUDE.md'), parityTarget('CLAUDE.md'), ctx);
+  checkLowercaseParity(ctx);
+  checkParity(path.join(workspaceRoot, 'GEMINI.md'), parityTarget('GEMINI.md'), ctx);
+  checkParity(path.join(workspaceRoot, '.cursorrules'), parityTarget('.cursorrules'), ctx);
+  checkParity(path.join(workspaceRoot, '.windsurfrules'), parityTarget('.windsurfrules'), ctx);
+}
+
+function checkGithubParity(ctx) {
+  const githubDir = path.join(ctx.workspaceRoot, '.github');
+  if (!fs.existsSync(githubDir) || !fs.statSync(githubDir).isDirectory()) return;
+  const copilot = path.join(githubDir, 'copilot-instructions.md');
+  if (fs.existsSync(copilot)) {
+    checkParity(copilot, parityTarget('.github/copilot-instructions.md'), ctx);
+  } else {
+    ctx.warn('.github/copilot-instructions.md is missing (run scaffold to restore harness parity).');
+  }
+  if (!fs.existsSync(path.join(githubDir, 'workflows'))) {
+    ctx.warn('.github/workflows is missing (CI will not run in scaffolded projects).');
+  }
+}
+
+function checkGitignore(ctx) {
+  if (fs.existsSync(path.join(ctx.workspaceRoot, '.gitignore'))) ctx.pass('.gitignore exists.');
+  else ctx.fail('Missing .gitignore');
+}
+
+function phaseRootConfig(ctx) {
+  ctx.heading('1. Checking Root Configuration & Symlinks...');
+  const agentsFile = path.join(ctx.workspaceRoot, 'AGENTS.md');
+  const agentsText = checkAgentsFile(ctx, agentsFile);
+  ctx.agentsFile = agentsFile;
+  ctx.agentsContent = agentsText === null ? '' : agentsText;
+  checkHarnessParity(ctx);
+  checkGithubParity(ctx);
+  checkGitignore(ctx);
+}
+
+export { phaseRootConfig, checkParity, checkAgentsFile };
+export default { phaseRootConfig, checkParity, checkAgentsFile };

package/scripts/validate/rules.js

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readTextOrFail, walkMarkdown } from './io.js';
+import { stripFencedCode } from './text.js';
+
+export function checkOneRule(fp, name, ctx) {
+  const content = readTextOrFail(fp, `Rule ${name}`, ctx.fail);
+  if (content === null) return;
+  const stat = fs.statSync(fp);
+  // Strip fenced code so a documentation example cannot satisfy either
+  // structural check.
+  const structural = stripFencedCode(content);
+  if (!/^# /m.test(structural)) ctx.fail(`Rule ${name} missing H1 header (# Title)`);
+  if (!/^> \*\*Core Mandate:\*\*/m.test(structural)) ctx.warn(`Rule ${name} missing standardized '> **Core Mandate:**' summary`);
+  if (stat.size > 24000) ctx.warn(`Rule ${name} exceeds 24KB token-economy cap (${stat.size} bytes)`);
+}
+
+export function phaseRules(ctx) {
+  ctx.log('');
+  ctx.heading('2. Checking Progressive Disclosure Rules...');
+  const rulesDir = path.join(ctx.workspaceRoot, 'docs', 'rules');
+  if (!fs.existsSync(rulesDir) || !fs.statSync(rulesDir).isDirectory()) {
+    ctx.fail(`Missing docs/rules directory at ${rulesDir}`);
+    return 0;
+  }
+  // Recurse, and match the extension case-insensitively. The previous flat
+  // readdir missed docs/rules/sub/*.md and *.MD entirely, so the reported
+  // count could be a lie and a 200KB rule could go unvalidated.
+  const files = walkMarkdown(rulesDir, 'rule', ctx.fail);
+  let count = 0;
+  for (const fp of files) {
+    count += 1;
+    checkOneRule(fp, path.relative(rulesDir, fp), ctx);
+  }
+  // Progressive disclosure with zero rules defeats the purpose of the
+  // directory, so an empty one is a failure, not a pass.
+  if (count === 0) ctx.fail('docs/rules contains no .md rule files; progressive disclosure has nothing to disclose.');
+  ctx.pass(`Validated ${count} modular rule files in docs/rules/.`);
+  return count;
+}
+
+export default { phaseRules, checkOneRule };

package/scripts/validate/skills.js

@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readTextOrFail, readSkillFolders } from './io.js';
+
+export 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;
+}
+
+export 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`);
+  }
+}
+
+export 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);
+}
+
+export 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;
+}
+
+export default { phaseSkills, checkOneSkill, extractSkillDescription, frontMatterBlock };