@ghostbyte/agent-docs-kit 4.0.2 → 5.0.0

package/docs/ARCHITECTURE.md

@@ -1,107 +1,46 @@
 # Architecture and file structure
 
-The repository separates executable behavior, canonical reference content, the installable skill, project templates, maintainer automation, tests, and the static website.
+The package has four layers: CLI/API behavior in `src/`, canonical review content in `content/`, the generated progressive skill in `skills/`, and the static documentation site in `site/`.
 
 ```text
 Agent_Docs_Kit/
+├─ .agent-docs/config.json         # this repository's audit policy
 ├─ .github/
+│  ├─ dependabot.yml               # monthly npm/action update proposals
 │  └─ workflows/
-│     ├─ ci.yml                    # tests, validation, package smoke check
-│     ├─ pages.yml                 # GitHub Pages build and deployment
-│     └─ publish-npm.yml           # npm trusted-publishing release
-├─ bin/
-│  └─ agent-docs.mjs               # npm executable entry point
+│     ├─ ci.yml                    # Node 22/24/26 cross-platform release gate
+│     ├─ monthly-health.yml        # scheduled health and review-date check
+│     ├─ pages.yml                 # GitHub Pages deployment
+│     └─ publish-npm.yml           # npm trusted publishing
+├─ bin/agent-docs.mjs              # executable entry point
 ├─ src/
-│  ├─ api/
-│  │  └─ index.mjs                 # programmatic public exports
-│  ├─ cli/
-│  │  ├─ arguments.mjs             # option and positional parsing
-│  │  ├─ help.mjs                  # command reference
-│  │  └─ main.mjs                  # direct-command and menu router
-│  ├─ commands/
-│  │  ├─ audit.mjs                 # docs/security report creation
-│  │  ├─ doctor.mjs                # prerequisite checks
-│  │  ├─ list.mjs                  # phase/topic discovery
-│  │  ├─ setup.mjs                 # project docs scaffold
-│  │  ├─ skill.mjs                 # explicit skill installation
-│  │  └─ validate.mjs              # package integrity checks
-│  └─ core/
-│     ├─ catalog.mjs               # canonical catalog loader
-│     ├─ files.mjs                 # safe write/copy primitives
-│     └─ paths.mjs                 # package-relative resolution
+│  ├─ api/index.mjs                # programmatic exports
+│  ├─ cli/                         # parsing, help, and routing
+│  ├─ commands/                    # setup, audit, worksheet, template, skill, validation
+│  └─ core/                        # catalog, config, filesystem, and package paths
 ├─ content/
-│  ├─ catalog.json                 # phase/topic IDs, slugs, sources
-│  ├─ security/
-│  │  ├─ 01-design-architecture.md
-│  │  ├─ ...                       # phases 02–11
-│  │  ├─ 12-ongoing-operations.md
-│  │  └─ full-reference.md         # deep lookup; not loaded by default
-│  └─ engineering/
-│     ├─ 01-query-performance.md
-│     ├─ ...                       # topics 02–08
-│     ├─ 09-message-queues.md
-│     └─ full-reference.md
-├─ skills/
-│  └─ manage-project-quality/
-│     ├─ agents/
-│     │  └─ openai.yaml            # skill UI metadata
-│     ├─ assets/
-│     │  ├─ documentation-report.md
-│     │  ├─ engineering-report.md
-│     │  └─ security-report.md
-│     ├─ references/
-│     │  ├─ documentation-governance.md
-│     │  ├─ engineering-protocol.md
-│     │  ├─ evidence-and-reporting.md
-│     │  ├─ security-protocol.md
-│     │  ├─ security-01-....md      # 12 progressive phase files
-│     │  └─ engineering-01-....md   # 9 progressive topic files
-│     ├─ scripts/
-│     │  └─ check-report.mjs
-│     └─ SKILL.md                   # concise routing instructions
-├─ scripts/
-│  ├─ build-site.mjs
-│  ├─ build-skill.mjs
-│  └─ validate-content.mjs
-├─ site/
-│  ├─ index.html
-│  └─ styles.css
-├─ tests/
-│  ├─ cli.test.mjs
-│  └─ content.test.mjs
-├─ build/                           # generated, ignored
-│  └─ site/
-├─ docs/
-│  ├─ ARCHITECTURE.md
-│  ├─ GITHUB_AND_NPM_SETUP.md
-│  ├─ PURPOSE.md
-│  ├─ RELEASE_PROCESS.md
-│  └─ SECURITY_MODEL.md
-├─ docs/archive/
-│  └─ AGENT_DOCS_KIT_v3.2.md        # retained legacy compiled edition
+│  ├─ catalog.json                 # versioned selectors and review dates
+│  ├─ documentation/               # 7 focused areas plus an index
+│  ├─ security/                    # 12 focused phases plus an index
+│  └─ engineering/                 # 14 focused topics plus an index
+├─ templates/                      # ADR, runbook, change, incident, and evidence records
+├─ skills/manage-project-quality/
+│  ├─ SKILL.md                     # progressive workflow router
+│  ├─ agents/openai.yaml           # skill UI metadata
+│  ├─ assets/                      # report templates
+│  ├─ references/                  # generated focused reference library
+│  └─ scripts/check-report.mjs     # report status/evidence validation
+├─ scripts/                        # build, validation, preview, and package smoke tests
+├─ site/                           # accessible static source
+├─ tests/                          # CLI, content, and safety regressions
+├─ docs/                           # maintainer and product documentation
+├─ CHANGELOG.md
+├─ SECURITY.md
 ├─ LICENSE
 ├─ README.md
 └─ package.json
 ```
 
-## Installed project structure
+`content/` is the single canonical library for all three workflows. `agent-docs setup` creates `.agent-docs/config.json` and a project documentation tree. Reports are written beneath configured directories; the reference library stays in the npm package and installed skill rather than being duplicated into each project.
 
-`agent-docs setup` creates only the starting documents needed to establish ownership and navigation:
-
-```text
-.agent-docs/config.json
-docs/
-├─ README.md
-├─ 01-system/overview.md
-├─ 02-project/README.md
-├─ 03-development/
-│  └─ engineering-reviews/
-├─ 04-testing/
-│  ├─ security-audits/
-│  └─ evidence/
-├─ 05-operations/README.md
-├─ 06-future-enhancements/README.md
-└─ archive/README.md
-```
-
-The CLI creates audit reports beneath this tree. It does not copy the entire reference library into each consumer project.
+Generated outputs under `build/`, package archives, dependencies, and the maintainer’s local monthly AI prompt are ignored by Git.

package/docs/CONTENT_MAINTENANCE.md

@@ -6,4 +6,8 @@ Review security guidance at least quarterly and after material changes to major
 
 Review engineering topics when supported runtimes, architectural assumptions, or operational scale change. Keep recommendations contextual and avoid presenting preferences as universal rules.
 
-Before release, run the content validator. It checks catalog/source consistency and common encoding corruption. A human review is still required for technical accuracy and link freshness.
+The catalog records `lastReviewed` and `reviewDue`. The scheduled health workflow fails after the due date; extending the date requires an actual content review.
+
+Before release, run `npm run release:check`. Validation checks selectors, source files, duplicate headings, legacy references, encoding, package paths, templates, and website anchors. The smoke test installs the actual tarball into a clean temporary consumer. Human review is still required for technical accuracy and external-link freshness.
+
+The ignored `MONTHLY_MAINTENANCE_AI.md` file is the maintainer's reusable AI runbook. It checks runtime support, dependencies, actions, dates, links, registry/tag/release alignment, and rotates one security phase plus one engineering topic each month.

package/docs/GITHUB_AND_NPM_SETUP.md

@@ -102,7 +102,7 @@ In npm package settings, add a trusted publisher for GitHub Actions with these v
 
 No npm token or GitHub environment is required. The workflow is restricted to this GitHub repository and workflow through OIDC.
 
-After that, commit your changes, increment the npm version, and push to `main`. The push automatically validates and publishes the new version. No long-lived `NPM_TOKEN` is required.
+After that, commit your changes, increment the npm version, and push the matching version tag. The tag workflow verifies that the tag and `package.json` agree, runs the full release gate, publishes through npm trusted publishing, and creates the matching GitHub Release. A normal push to `main` updates source and Pages but does not publish npm. No long-lived `NPM_TOKEN` is required.
 
 ```powershell
 npm.cmd version patch

package/docs/RELEASE_PROCESS.md

@@ -1,14 +1,14 @@
 # Release process
 
-Published npm versions are immutable. A push can publish a new version, but it cannot replace the contents of an existing version.
+Published npm versions are immutable. A matching version-tag push can publish a new version, but it cannot replace the contents of an existing version.
 
 1. Update canonical content and run `npm run build` to refresh progressive skill references and the site.
-2. Run `npm test`, `npm run validate`, and `npm pack --dry-run`.
+2. Run `npm run release:check`. This includes tests, validation, builds, a clean tarball installation, and `npm audit`.
 3. Confirm the package archive contains no credentials, local reports, nested repositories, or generated consumer data.
 4. Commit the package changes locally.
 5. Update the version with `npm version patch`, `minor`, or `major` according to compatibility.
-6. Push the commit and tag. A push to `main` runs `.github/workflows/publish-npm.yml` and publishes the new version through npm trusted publishing.
-7. Verify `npx --yes @ghostbyte/agent-docs-kit@<version> --help` from a clean directory.
+6. Push the commit and tag. A matching `v*` tag on `main` runs `.github/workflows/publish-npm.yml`, verifies the version and ancestry, and publishes through npm trusted publishing.
+7. Let the workflow create the matching GitHub Release, then verify `npx --yes @ghostbyte/agent-docs-kit@<version> --help` from a clean directory.
 
 ```powershell
 git add -A
@@ -17,6 +17,6 @@ npm.cmd version patch
 git push --follow-tags
 ```
 
-Use `minor` for a backward-compatible feature and `major` for a breaking change. A GitHub Release is optional and does not control npm publication.
+Use `minor` for a backward-compatible feature and `major` for a breaking change. The workflow enforces agreement between `package.json` and the pushed tag, then creates the corresponding GitHub Release after publication.
 
 The first release was published manually because the package had to exist before its trusted publisher could be configured. If a pushed version already exists, the workflow validates the project and safely skips publication; increment the version before pushing package changes that should reach npm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostbyte/agent-docs-kit",
-  "version": "4.0.2",
+  "version": "5.0.0",
   "description": "Documentation governance, evidence-based security audits, and engineering-quality reviews for software projects.",
   "type": "module",
   "bin": {
@@ -16,7 +16,12 @@
     "templates/",
     "skills/",
     "docs/",
+    "scripts/",
+    "site/",
+    "tests/",
     "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {
@@ -24,11 +29,14 @@
     "site:preview": "node scripts/preview-site.mjs",
     "doctor": "node bin/agent-docs.mjs doctor",
     "test": "node --test",
-    "validate": "node scripts/validate-content.mjs && node bin/agent-docs.mjs validate",
-    "prepublishOnly": "npm run build && npm test && npm run validate"
+    "validate": "node scripts/validate-content.mjs && node scripts/check-links.mjs && node bin/agent-docs.mjs validate",
+    "smoke:package": "node scripts/smoke-package.mjs",
+    "review:dates": "node scripts/check-review-dates.mjs",
+    "release:check": "npm test && npm run validate && npm run review:dates && npm run build && npm run smoke:package && npm audit --cache .npm-cache",
+    "prepublishOnly": "npm run release:check"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "keywords": [
     "ai-agent",
@@ -51,7 +59,6 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "main": "serve.js",
   "directories": {
     "doc": "docs",
     "test": "tests"

package/scripts/build-site.mjs

@@ -0,0 +1,13 @@
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const root = resolve(import.meta.dirname, "..");
+const output = resolve(root, "build/site");
+await rm(output, { recursive: true, force: true });
+await mkdir(output, { recursive: true });
+await cp(resolve(root, "site"), output, { recursive: true });
+await cp(resolve(root, "docs"), resolve(output, "docs"), { recursive: true });
+await cp(resolve(root, "README.md"), resolve(output, "README.md"));
+await cp(resolve(root, "LICENSE"), resolve(output, "LICENSE"));
+await writeFile(resolve(output, ".nojekyll"), "", "utf8");
+console.log(`Built site at ${output}`);

package/scripts/build-skill.mjs

@@ -0,0 +1,24 @@
+import { copyFile, mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+
+const root = resolve(import.meta.dirname, "..");
+const references = resolve(root, "skills/manage-project-quality/references");
+await mkdir(references, { recursive: true });
+const catalog = JSON.parse(await readFile(resolve(root, "content/catalog.json"), "utf8"));
+const expected = new Set();
+for (const kind of ["documentation", "security", "engineering"]) {
+  for (const entry of catalog[kind]) {
+    const name = `${kind}-${basename(entry.source)}`;
+    expected.add(name);
+    await copyFile(resolve(root, entry.source), resolve(references, name));
+  }
+  const fullName = `${kind}-full-reference.md`;
+  expected.add(fullName);
+  await copyFile(resolve(root, `content/${kind}/full-reference.md`), resolve(references, fullName));
+}
+for (const name of await readdir(references)) {
+  if (/^(?:documentation|security|engineering)-(?:\d{2}-.+|full-reference)\.md$/.test(name) && !expected.has(name)) {
+    await rm(resolve(references, name));
+  }
+}
+console.log("Built progressive skill references.");

package/scripts/check-links.mjs

@@ -0,0 +1,56 @@
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, extname, relative, resolve } from "node:path";
+
+const root = resolve(import.meta.dirname, "..");
+const excluded = new Set([".agents", ".codex", ".git", ".npm-cache", "build", "node_modules"]);
+const cache = new Map();
+
+async function files(directory) {
+  const found = [];
+  for (const item of await readdir(directory, { withFileTypes: true })) {
+    if (item.isDirectory() && excluded.has(item.name)) continue;
+    const path = resolve(directory, item.name);
+    if (item.isDirectory()) found.push(...await files(path));
+    else if (item.isFile() && extname(path).toLowerCase() === ".md") found.push(path);
+  }
+  return found;
+}
+
+function slug(value) {
+  return value.toLowerCase().trim().replace(/[^\p{L}\p{N}\s-]/gu, "").replace(/\s+/g, "-");
+}
+
+const errors = [];
+for (const file of await files(root)) {
+  const value = await readFile(file, "utf8");
+  cache.set(file, value);
+  const inspectable = value.replace(/^(```|~~~)[\s\S]*?^\1\s*$/gm, "");
+  for (const match of inspectable.matchAll(/\[[^\]]+\]\((<[^>]+>|[^\s)]+)(?:\s+["'][^"']*["'])?\)/g)) {
+    const raw = match[1].trim().replace(/^<|>$/g, "");
+    if (!raw || /^(?:https?:|mailto:)/i.test(raw)) continue;
+    const [pathPart, fragment] = raw.split("#", 2);
+    let decodedPath;
+    let decodedFragment;
+    try {
+      decodedPath = pathPart ? decodeURIComponent(pathPart) : "";
+      decodedFragment = fragment ? decodeURIComponent(fragment).toLowerCase() : "";
+    } catch {
+      errors.push(`${relative(root, file)} -> invalid URL encoding ${raw}`);
+      continue;
+    }
+    const target = decodedPath ? resolve(dirname(file), decodedPath) : file;
+    let targetValue;
+    try {
+      if (!cache.has(target)) cache.set(target, await readFile(target, "utf8"));
+      targetValue = cache.get(target);
+    }
+    catch { errors.push(`${relative(root, file)} -> missing ${raw}`); continue; }
+    if (fragment && extname(target).toLowerCase() === ".md") {
+      const anchors = new Set([...targetValue.matchAll(/^#{1,6}\s+(.+)$/gm)].map(([, heading]) => slug(heading)));
+      if (!anchors.has(decodedFragment)) errors.push(`${relative(root, file)} -> missing anchor ${raw}`);
+    }
+  }
+}
+
+if (errors.length) { console.error(errors.join("\n")); process.exitCode = 1; }
+else console.log("PASS internal Markdown links and anchors");

package/scripts/check-review-dates.mjs

@@ -0,0 +1,21 @@
+import { readFile } from "node:fs/promises";
+
+const catalog = JSON.parse(await readFile(new URL("../content/catalog.json", import.meta.url), "utf8"));
+const asOfFlag = process.argv.indexOf("--as-of");
+const now = new Date();
+const localToday = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+const today = asOfFlag >= 0 ? process.argv[asOfFlag + 1] : localToday;
+const parsedToday = new Date(`${today}T00:00:00Z`);
+if (!/^\d{4}-\d{2}-\d{2}$/.test(today) || Number.isNaN(parsedToday.getTime()) || parsedToday.toISOString().slice(0, 10) !== today) throw new Error("Use a valid --as-of YYYY-MM-DD date.");
+const overdue = [];
+for (const kind of ["documentation", "security", "engineering"]) {
+  for (const entry of catalog[kind]) {
+    if (entry.reviewDue < today) overdue.push(`${kind}:${entry.id} ${entry.slug} (due ${entry.reviewDue})`);
+  }
+}
+if (overdue.length) {
+  console.error(`Review controls overdue as of ${today}:\n${overdue.join("\n")}`);
+  process.exitCode = 1;
+} else {
+  console.log(`PASS review dates (${catalog.documentation.length + catalog.security.length + catalog.engineering.length} areas checked as of ${today})`);
+}

package/scripts/preview-site.mjs

@@ -0,0 +1,43 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { extname, resolve, sep } from "node:path";
+
+const root = resolve(import.meta.dirname, "../build/site");
+const portIndex = process.argv.indexOf("--port");
+const port = Number(portIndex >= 0 ? process.argv[portIndex + 1] : 4173);
+const host = "127.0.0.1";
+const types = {
+  ".css": "text/css; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".svg": "image/svg+xml"
+};
+
+const server = createServer(async (request, response) => {
+  try {
+    const url = new URL(request.url ?? "/", `http://${request.headers.host ?? host}`);
+    const requested = decodeURIComponent(url.pathname === "/" ? "/index.html" : url.pathname);
+    const file = resolve(root, `.${requested}`);
+    if (file !== root && !file.startsWith(`${root}${sep}`)) {
+      response.writeHead(403).end("Forbidden");
+      return;
+    }
+    const info = await stat(file);
+    if (!info.isFile()) throw new Error("Not a file");
+    response.writeHead(200, {
+      "Content-Type": types[extname(file)] ?? "application/octet-stream",
+      "Cache-Control": "no-store",
+      "X-Content-Type-Options": "nosniff"
+    });
+    createReadStream(file).pipe(response);
+  } catch {
+    response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" }).end("Not found");
+  }
+});
+
+server.listen(port, host, () => {
+  console.log(`Agent Docs & Quality Kit preview: http://${host}:${port}`);
+});

package/scripts/smoke-package.mjs

@@ -0,0 +1,58 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { access, mkdtemp, mkdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+
+const root = resolve(import.meta.dirname, "..");
+const scratch = await mkdtemp(resolve(tmpdir(), "agent-docs-kit-smoke-"));
+const npmCli = process.env.npm_execpath;
+const runNpm = (arguments_, options = {}) => npmCli
+  ? execFileSync(process.execPath, [npmCli, ...arguments_], options)
+  : execFileSync("npm", arguments_, options);
+try {
+  const cache = resolve(scratch, "npm-cache");
+  const packed = JSON.parse(runNpm(["pack", "--json", "--cache", cache, "--pack-destination", scratch], { cwd: root, encoding: "utf8" }));
+  const archivePaths = new Set(packed[0].files.map((entry) => entry.path.replaceAll("\\", "/")));
+  for (const required of ["scripts/validate-content.mjs", "site/index.html", "tests/cli.test.mjs", "skills/manage-project-quality/references/security-protocol.md", "skills/manage-project-quality/references/engineering-protocol.md", "skills/manage-project-quality/references/documentation-governance.md"]) {
+    if (!archivePaths.has(required)) throw new Error(`Packed archive is missing ${required}.`);
+  }
+  for (const path of archivePaths) {
+    if (/^(?:\.git|\.agent-docs|\.npm-cache|build|node_modules)(?:\/|$)|MONTHLY_MAINTENANCE_AI\.md$|\.tgz$/i.test(path)) throw new Error(`Private or generated path leaked into package: ${path}`);
+  }
+  const tarball = resolve(scratch, packed[0].filename);
+  const consumer = resolve(scratch, "consumer");
+  await mkdir(consumer);
+  runNpm(["init", "--yes", "--cache", cache], { cwd: consumer, stdio: "ignore" });
+  runNpm(["install", "--ignore-scripts", "--cache", cache, tarball], { cwd: consumer, stdio: "ignore" });
+  const packageRoot = resolve(consumer, "node_modules", "@ghostbyte", "agent-docs-kit");
+  const cli = resolve(packageRoot, "bin", "agent-docs.mjs");
+  const runCli = (...arguments_) => execFileSync(process.execPath, [cli, ...arguments_], { cwd: consumer, encoding: "utf8" });
+  const help = execFileSync(process.execPath, [cli, "--help"], { cwd: consumer, encoding: "utf8" });
+  if (!help.includes("documentation guide") || !help.includes("security worksheet") || !help.includes("template create")) throw new Error("Packed CLI help is incomplete.");
+  runCli("setup", "--dry-run");
+  runCli("setup");
+  runCli("audit", "documentation", "--strict", "--report", "--format", "json");
+  const securityOutput = runCli("security", "worksheet", "api-layer");
+  const engineeringOutput = runCli("engineering", "worksheet", "testing-types");
+  for (const output of [securityOutput, engineeringOutput]) {
+    const report = output.match(/created\s+(.+\.md)\s*$/m)?.[1];
+    if (!report) throw new Error(`Unable to locate generated report in output: ${output}`);
+    execFileSync(process.execPath, [resolve(packageRoot, "skills/manage-project-quality/scripts/check-report.mjs"), report], { cwd: consumer, stdio: "ignore" });
+  }
+  for (const type of ["adr", "runbook", "change", "incident", "evidence"]) runCli("template", "create", type, "--name", `smoke-${type}`);
+  runCli("documentation", "guide", "system-documentation");
+  runCli("skill", "install", "--target", "project");
+  runCli("validate");
+  await access(resolve(consumer, ".agents/skills/manage-project-quality/SKILL.md"));
+  execFileSync(process.execPath, ["--input-type=module", "--eval", "const api = await import('@ghostbyte/agent-docs-kit'); if (typeof api.auditDocumentation !== 'function' || typeof api.createTemplate !== 'function') process.exit(1);"], { cwd: consumer });
+  const invalid = spawnSync(process.execPath, [cli, "doctor", "unexpected"], { cwd: consumer, encoding: "utf8" });
+  if (invalid.status === 0 || !invalid.stderr.includes("Invalid arguments")) throw new Error("CLI accepted an unexpected positional argument.");
+  runNpm(["run", "validate"], { cwd: packageRoot, stdio: "ignore" });
+  const today = new Date();
+  const date = `${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, "0")}-${String(today.getDate()).padStart(2, "0")}`;
+  const reportBody = await readFile(resolve(consumer, "docs/03-development/audits", `${date}-documentation.json`), "utf8");
+  JSON.parse(reportBody);
+  console.log(`PASS packed installation (${packed[0].size} bytes, ${packed[0].entryCount} files)`);
+} finally {
+  await rm(scratch, { recursive: true, force: true });
+}

package/scripts/validate-content.mjs

@@ -0,0 +1,85 @@
+import { access, readFile, readdir } from "node:fs/promises";
+import { basename, relative, resolve } from "node:path";
+
+const root = resolve(import.meta.dirname, "..");
+const catalog = JSON.parse(await readFile(resolve(root, "content/catalog.json"), "utf8"));
+const metadata = JSON.parse(await readFile(resolve(root, "package.json"), "utf8"));
+const errors = [];
+const identities = new Set();
+const expectedGenerated = new Set();
+const aliases = { documentation: new Map(), security: new Map(), engineering: new Map() };
+const controlIds = new Set();
+
+function validDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value ?? "")) return false;
+  const parsed = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+
+if (catalog.schemaVersion !== 2) errors.push("content/catalog.json must use schemaVersion 2.");
+if (!validDate(catalog.lastReviewed)) errors.push("Catalog lastReviewed is missing or invalid.");
+if (!validDate(catalog.reviewDue)) errors.push("Catalog reviewDue is missing or invalid.");
+if (catalog.reviewDue < catalog.lastReviewed) errors.push("Catalog reviewDue precedes lastReviewed.");
+
+for (const kind of ["documentation", "security", "engineering"]) {
+  for (const entry of catalog[kind]) {
+    const identity = `${kind}:${entry.id}:${entry.slug}`;
+    if (identities.has(identity)) errors.push(`Duplicate catalog entry: ${identity}`);
+    identities.add(identity);
+    if (!validDate(entry.lastReviewed)) errors.push(`${identity} has an invalid lastReviewed date.`);
+    if (!validDate(entry.reviewDue)) errors.push(`${identity} has an invalid reviewDue date.`);
+    if (entry.reviewDue < entry.lastReviewed) errors.push(`${identity} reviewDue precedes lastReviewed.`);
+    for (const selector of new Set([entry.id, entry.slug, ...(entry.aliases ?? [])])) {
+      if (aliases[kind].has(selector) && aliases[kind].get(selector) !== identity) errors.push(`Duplicate ${kind} selector: ${selector}`);
+      aliases[kind].set(selector, identity);
+    }
+    try {
+      const value = await readFile(resolve(root, entry.source), "utf8");
+      const h1s = value.match(/^#\s+/gm) ?? [];
+      if (h1s.length !== 1) errors.push(`${entry.source} must contain exactly one H1; found ${h1s.length}.`);
+      if (/\uFFFD|Ã|â(?:€|†)/.test(value)) errors.push(`${entry.source} contains encoding artifacts.`);
+      if (/CHECKLIST\.md|RESULTS_TEMPLATE\.md|SECURITY_CHECKLIST\.md|ENGINEERING_REFERENCE\.md|security-gate/.test(value)) errors.push(`${entry.source} contains a legacy path reference.`);
+      if (/Files in this folder|this same folder|RESULTS_\d{4}-\d{2}-\d{2}|Reference (?:checklist|list) only/.test(value)) errors.push(`${entry.source} contains legacy folder-oriented instructions.`);
+      const prefix = kind === "documentation" ? "DOC" : kind === "security" ? "SEC" : "ENG";
+      const ids = value.match(new RegExp(`\\b${prefix}-${entry.id}-\\d{2}\\b`, "g")) ?? [];
+      if (!ids.length) errors.push(`${entry.source} has no stable ${prefix}-${entry.id}-NN identifiers.`);
+      for (const id of ids) {
+        if (controlIds.has(id)) errors.push(`Duplicate control identifier: ${id}`);
+        controlIds.add(id);
+      }
+      const generated = resolve(root, "skills/manage-project-quality/references", `${kind}-${basename(entry.source)}`);
+      expectedGenerated.add(basename(generated));
+      try {
+        if (await readFile(generated, "utf8") !== value) errors.push(`Generated skill reference is stale: ${relative(root, generated)}`);
+      } catch { errors.push(`Missing generated skill reference: ${relative(root, generated)}`); }
+    } catch { errors.push(`Missing source: ${entry.source}`); }
+  }
+  const fullSource = resolve(root, `content/${kind}/full-reference.md`);
+  const fullGenerated = resolve(root, `skills/manage-project-quality/references/${kind}-full-reference.md`);
+  expectedGenerated.add(basename(fullGenerated));
+  try {
+    if (await readFile(fullSource, "utf8") !== await readFile(fullGenerated, "utf8")) errors.push(`Generated ${kind} full reference is stale.`);
+  } catch { errors.push(`Missing ${kind} full reference or generated copy.`); }
+}
+
+for (const name of await readdir(resolve(root, "skills/manage-project-quality/references"))) {
+  if (/^(?:documentation|security|engineering)-(?:\d{2}-.+|full-reference)\.md$/.test(name) && !expectedGenerated.has(name)) errors.push(`Unexpected generated skill reference: ${name}`);
+}
+
+if (catalog.documentation.length !== 7) errors.push(`Expected 7 documentation areas; found ${catalog.documentation.length}.`);
+if (catalog.security.length !== 12) errors.push(`Expected 12 security phases; found ${catalog.security.length}.`);
+if (catalog.engineering.length !== 14) errors.push(`Expected 14 engineering topics; found ${catalog.engineering.length}.`);
+if (!Number(metadata.engines?.node?.match(/\d+/)?.[0]) || Number(metadata.engines.node.match(/\d+/)[0]) < 22) errors.push("Node.js engine must require 22 or newer.");
+for (const directory of metadata.files ?? []) {
+  try { await access(resolve(root, directory)); }
+  catch { errors.push(`package.json files entry does not exist: ${directory}`); }
+}
+
+const site = await readFile(resolve(root, "site/index.html"), "utf8");
+const ids = [...site.matchAll(/\sid="([^"]+)"/g)].map((match) => match[1]);
+const duplicateIds = ids.filter((id, index) => ids.indexOf(id) !== index);
+for (const id of new Set(duplicateIds)) errors.push(`Duplicate website id: ${id}`);
+for (const [, anchor] of site.matchAll(/href="#([^"]+)"/g)) if (!ids.includes(anchor)) errors.push(`Broken website anchor: #${anchor}`);
+
+if (errors.length) { console.error(errors.join("\n")); process.exitCode = 1; }
+else console.log(`Validated ${identities.size} catalog entries, package paths, and website anchors.`);