@ghostbyte/agent-docs-kit 0.0.0-stage → 4.0.2

package/skills/manage-project-quality/references/security-protocol.md

@@ -0,0 +1,22 @@
+# Security review protocol
+
+## Purpose
+
+Security assurance looks for exploitable weaknesses and missing controls that can affect confidentiality, integrity, availability, privacy, or release safety. Its output is evidence-based and can block release when a Critical or High control fails.
+
+## Safety boundary
+
+Repository inspection, dependency-manifest review, and static configuration review are passive. Dynamic scanning, fuzzing, credential use, exploit validation, cloud changes, load generation, and production access require explicit authorization for the named target. Stop when target ownership or permitted impact is unclear.
+
+## Statuses
+
+- `Pass`: sufficient evidence demonstrates the control.
+- `Fail`: evidence demonstrates the control is absent, ineffective, or bypassable.
+- `Unverified`: evidence is unavailable or cannot be safely collected.
+- `N/A`: the control does not apply; record why.
+
+Never infer `Pass` from absence of evidence. A tool reporting no finding is evidence only for the scope and limitations of that tool.
+
+## Severity and release effect
+
+Use Critical, High, Medium, Low, or Informational. Critical and High failures block release by default. An exception must name the risk owner, justification, compensating control, and expiry date.

package/skills/manage-project-quality/scripts/check-report.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+
+const file = process.argv[2];
+if (!file) throw new Error("Usage: node check-report.mjs <report.md>");
+const text = await readFile(file, "utf8");
+const allowed = new Set(["Pass", "Fail", "Unverified", "N/A", "Applied", "Partial", "Recommended"]);
+const errors = [];
+for (const [index, line] of text.split(/\r?\n/).entries()) {
+  if (!line.startsWith("|") || /^\|[-: |]+\|$/.test(line)) continue;
+  const cells = line.split("|").slice(1, -1).map((cell) => cell.trim());
+  const status = cells.find((cell) => allowed.has(cell));
+  if (status && status !== "Unverified" && !cells.some((cell, cellIndex) => cellIndex > 1 && cell.length > 3)) {
+    errors.push(`Line ${index + 1}: status '${status}' has no supporting detail.`);
+  }
+}
+if (errors.length) {
+  console.error(errors.join("\n"));
+  process.exitCode = 1;
+} else {
+  console.log("Report structure check passed.");
+}

package/src/api/index.mjs

@@ -0,0 +1,4 @@
+export { setupProject } from "../commands/setup.mjs";
+export { auditDocumentation, auditSecurity, reviewEngineering } from "../commands/audit.mjs";
+export { installSkill } from "../commands/skill.mjs";
+export { loadCatalog } from "../core/catalog.mjs";

package/src/cli/arguments.mjs

@@ -0,0 +1,30 @@
+export function parseArguments(argv) {
+  const positionals = [];
+  const flags = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+    const [rawKey, inline] = token.slice(2).split("=", 2);
+    if (inline !== undefined) {
+      flags[rawKey] = inline;
+    } else if (argv[index + 1] && !argv[index + 1].startsWith("--")) {
+      flags[rawKey] = argv[++index];
+    } else {
+      flags[rawKey] = true;
+    }
+  }
+  return { positionals, flags };
+}
+
+export function optionsFromFlags(flags) {
+  return {
+    cwd: flags.cwd,
+    dryRun: Boolean(flags["dry-run"]),
+    force: Boolean(flags.force),
+    style: flags.style ?? "standard",
+    report: Boolean(flags.report)
+  };
+}

package/src/cli/help.mjs

@@ -0,0 +1,24 @@
+export const helpText = `Agent Docs & Quality Kit
+
+Usage:
+  agent-docs                         Open the guided menu (TTY only)
+  agent-docs setup [--dry-run]       Install the documentation workspace
+  agent-docs audit documentation     Check documentation health
+  agent-docs audit security [phase]  Create an evidence-based security worksheet
+  agent-docs review engineering [topic]
+                                     Create an engineering review worksheet
+  agent-docs list [security|engineering]
+  agent-docs skill install [--target project|codex] [--dry-run]
+  agent-docs validate                Validate this package's catalog and skill
+  agent-docs doctor                  Check local prerequisites
+  agent-docs --version               Show the package version
+
+Options:
+  --cwd <path>             Target project (default: current directory)
+  --style standard|learning
+  --dry-run                Preview writes without changing files
+  --force                  Replace files that this command owns
+  --report                 Write documentation audit results
+  --help                   Show this help
+
+Installing the npm package performs no project setup. Run a command explicitly.`;

package/src/cli/main.mjs

@@ -0,0 +1,65 @@
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { parseArguments, optionsFromFlags } from "./arguments.mjs";
+import { helpText } from "./help.mjs";
+import { setupProject } from "../commands/setup.mjs";
+import { auditDocumentation, auditSecurity, reviewEngineering } from "../commands/audit.mjs";
+import { listCatalog } from "../commands/list.mjs";
+import { installSkill } from "../commands/skill.mjs";
+import { doctor } from "../commands/doctor.mjs";
+import { validatePackage } from "../commands/validate.mjs";
+import { readFile } from "node:fs/promises";
+import { resolveFromPackage } from "../core/paths.mjs";
+
+async function menu() {
+  const ui = createInterface({ input: stdin, output: stdout });
+  try {
+    console.log(`\nAgent Docs & Quality Kit\n\n1. Set up documentation\n2. Audit documentation\n3. Start security audit\n4. Start engineering review\n5. Install project skill\n6. Validate package\n0. Exit`);
+    const choice = await ui.question("\nChoose an action: ");
+    if (choice === "1") return setupProject();
+    if (choice === "2") return auditDocumentation();
+    if (choice === "3") {
+      await listCatalog("security");
+      return auditSecurity(await ui.question("Phase id or slug: "));
+    }
+    if (choice === "4") {
+      await listCatalog("engineering");
+      return reviewEngineering(await ui.question("Topic id or slug: "));
+    }
+    if (choice === "5") return installSkill("project");
+    if (choice === "6") return validatePackage();
+    if (choice !== "0") throw new Error("Unknown menu choice.");
+  } finally {
+    ui.close();
+  }
+}
+
+export async function main(argv) {
+  const { positionals, flags } = parseArguments(argv);
+  const [command, subject, selector] = positionals;
+  const options = optionsFromFlags(flags);
+  if (flags.version || command === "version") {
+    const metadata = JSON.parse(await readFile(resolveFromPackage("package.json"), "utf8"));
+    return console.log(metadata.version);
+  }
+  if (flags.help || command === "help") return console.log(helpText);
+  if (!command) {
+    if (!stdin.isTTY) {
+      console.log(helpText);
+      return;
+    }
+    return menu();
+  }
+  if (command === "setup") return setupProject(options);
+  if (command === "audit" && subject === "documentation") return auditDocumentation(options);
+  if (command === "audit" && subject === "security") return auditSecurity(selector ?? flags.phase, options);
+  if (command === "review" && subject === "engineering") return reviewEngineering(selector ?? flags.topic, options);
+  if (command === "list") return listCatalog(subject);
+  if (command === "skill" && subject === "install") return installSkill(flags.target ?? "project", options);
+  if (command === "validate") return validatePackage();
+  if (command === "doctor") {
+    if (!doctor()) process.exitCode = 1;
+    return;
+  }
+  throw new Error(`Unknown command.\n\n${helpText}`);
+}

package/src/commands/audit.mjs

@@ -0,0 +1,49 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { loadCatalog, selectEntry } from "../core/catalog.mjs";
+import { exists, writeSafe } from "../core/files.mjs";
+import { resolveFromPackage } from "../core/paths.mjs";
+
+const date = () => new Date().toISOString().slice(0, 10);
+
+async function reportFor(kind, selector, options = {}) {
+  const catalog = await loadCatalog();
+  const entries = catalog[kind];
+  const entry = selectEntry(entries, selector);
+  if (!entry) throw new Error(`Unknown ${kind} selection '${selector ?? ""}'. Run 'agent-docs list ${kind}'.`);
+  const source = await readFile(resolveFromPackage(entry.source), "utf8");
+  const status = kind === "security" ? "Unverified" : "Unverified";
+  const heading = kind === "security" ? "Security audit" : "Engineering review";
+  const destinationRoot = kind === "security"
+    ? "docs/04-testing/security-audits"
+    : "docs/03-development/engineering-reviews";
+  const output = resolve(options.cwd ?? process.cwd(), destinationRoot, `${date()}-${entry.slug}.md`);
+  const body = `# ${heading}: ${entry.title}\n\n- Date: ${date()}\n- Style: ${options.style ?? "standard"}\n- Overall status: ${status}\n- Reviewer: _Unassigned_\n\n## Scope and authorization\n\n- Target: _Describe the code, configuration, or authorized environment_\n- Authorization: _Required before active security testing_\n- Exclusions: _List exclusions_\n\n## Findings\n\n| Check | Status | Evidence | Action |\n|---|---|---|---|\n| Add each applicable check | ${status} | File/line, command output, or external evidence | Required follow-up |\n\n## Reference checklist\n\n${source}\n`;
+  const result = await writeSafe(output, body, options);
+  console.log(`${result.status} ${output}`);
+  return result;
+}
+
+export const auditSecurity = (selector, options) => reportFor("security", selector, options);
+export const reviewEngineering = (selector, options) => reportFor("engineering", selector, options);
+
+export async function auditDocumentation(options = {}) {
+  const root = resolve(options.cwd ?? process.cwd());
+  const required = [
+    ".agent-docs/config.json",
+    "docs/README.md",
+    "docs/01-system/overview.md",
+    "docs/02-project/README.md",
+    "docs/05-operations/README.md"
+  ];
+  const rows = await Promise.all(required.map(async (path) => ({ path, present: await exists(resolve(root, path)) })));
+  for (const row of rows) console.log(`${row.present ? "PASS" : "FAIL"} ${row.path}`);
+  const result = { checkedAt: new Date().toISOString(), pass: rows.every((row) => row.present), files: rows };
+  if (options.report && !options.dryRun) {
+    const output = resolve(root, "docs/03-development/audits", `${date()}-documentation.json`);
+    await mkdir(resolve(output, ".."), { recursive: true });
+    await writeFile(output, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+    console.log(`created ${output}`);
+  }
+  return result;
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,12 @@
+import { execFileSync } from "node:child_process";
+
+export function doctor() {
+  const checks = [{ name: "Node.js >=20", pass: Number(process.versions.node.split(".")[0]) >= 20, value: process.version }];
+  try {
+    checks.push({ name: "Git", pass: true, value: execFileSync("git", ["--version"], { encoding: "utf8" }).trim() });
+  } catch {
+    checks.push({ name: "Git", pass: false, value: "not found" });
+  }
+  for (const check of checks) console.log(`${check.pass ? "PASS" : "FAIL"} ${check.name}: ${check.value}`);
+  return checks.every((check) => check.pass);
+}

package/src/commands/list.mjs

@@ -0,0 +1,11 @@
+import { loadCatalog } from "../core/catalog.mjs";
+
+export async function listCatalog(kind) {
+  const catalog = await loadCatalog();
+  const groups = kind ? [kind] : ["security", "engineering"];
+  for (const group of groups) {
+    if (!catalog[group]) throw new Error(`Unknown catalog '${group}'.`);
+    console.log(`\n${group.toUpperCase()}`);
+    for (const entry of catalog[group]) console.log(`  ${entry.id.padEnd(3)} ${entry.slug.padEnd(34)} ${entry.title}`);
+  }
+}

package/src/commands/setup.mjs

@@ -0,0 +1,42 @@
+import { resolve } from "node:path";
+import { displayResults, writeSafe } from "../core/files.mjs";
+
+const files = {
+  ".agent-docs/config.json": `{
+  "schemaVersion": 1,
+  "documentationRoot": "docs",
+  "securityReports": "docs/04-testing/security-audits",
+  "engineeringReports": "docs/03-development/engineering-reviews",
+  "interactionStyle": "standard"
+}\n`,
+  "docs/README.md": `# Project documentation
+
+This directory is the maintained project record. Keep decisions and system facts separate from generated audit evidence.
+
+- \`01-system/\`: system scope, architecture, data, and security design
+- \`02-project/\`: requirements, roadmap, decisions, and status
+- \`03-development/\`: implementation notes and engineering reviews
+- \`04-testing/\`: test plans, security audits, and evidence
+- \`05-operations/\`: setup, deployment, runbooks, and agent operations
+- \`06-future-enhancements/\`: proposals that are not current commitments
+- \`archive/\`: superseded material retained for traceability
+`,
+  "docs/01-system/overview.md": "# System overview\n\nStatus: Needs update\n\nDescribe the system boundary, users, dependencies, and authoritative sources.\n",
+  "docs/02-project/README.md": "# Project\n\nTrack requirements, decisions, milestones, and current delivery status here.\n",
+  "docs/03-development/engineering-reviews/.gitkeep": "",
+  "docs/04-testing/security-audits/.gitkeep": "",
+  "docs/04-testing/evidence/.gitkeep": "",
+  "docs/05-operations/README.md": "# Operations\n\nDocument setup, deployment, observability, incident response, and recovery procedures.\n",
+  "docs/06-future-enhancements/README.md": "# Future enhancements\n\nIdeas here are proposals, not part of the current scope until accepted.\n",
+  "docs/archive/README.md": "# Archive\n\nKeep superseded documents here with replacement links and archive dates.\n"
+};
+
+export async function setupProject(options = {}) {
+  const root = resolve(options.cwd ?? process.cwd());
+  const results = [];
+  for (const [path, contents] of Object.entries(files)) {
+    results.push(await writeSafe(resolve(root, path), contents, options));
+  }
+  displayResults(root, results);
+  return results;
+}

package/src/commands/skill.mjs

@@ -0,0 +1,14 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { copySafe } from "../core/files.mjs";
+import { resolveFromPackage } from "../core/paths.mjs";
+
+export async function installSkill(target = "project", options = {}) {
+  const root = resolve(options.cwd ?? process.cwd());
+  const destination = target === "codex"
+    ? resolve(homedir(), ".codex", "skills", "manage-project-quality")
+    : resolve(root, ".agents", "skills", "manage-project-quality");
+  const result = await copySafe(resolveFromPackage("skills", "manage-project-quality"), destination, options);
+  console.log(`${result.status} ${destination}`);
+  return result;
+}

package/src/commands/validate.mjs

@@ -0,0 +1,20 @@
+import { access, readFile } from "node:fs/promises";
+import { loadCatalog } from "../core/catalog.mjs";
+import { resolveFromPackage } from "../core/paths.mjs";
+
+export async function validatePackage() {
+  const catalog = await loadCatalog();
+  const errors = [];
+  for (const group of ["security", "engineering"]) {
+    for (const entry of catalog[group]) {
+      try { await access(resolveFromPackage(entry.source)); }
+      catch { errors.push(`Missing catalog source: ${entry.source}`); }
+    }
+  }
+  const skill = await readFile(resolveFromPackage("skills/manage-project-quality/SKILL.md"), "utf8");
+  if (!skill.includes("name: manage-project-quality")) errors.push("Skill name is invalid.");
+  if (errors.length) throw new Error(errors.join("\n"));
+  console.log(`PASS catalog (${catalog.security.length} security phases, ${catalog.engineering.length} engineering topics)`);
+  console.log("PASS unified skill");
+  return true;
+}

package/src/core/catalog.mjs

@@ -0,0 +1,19 @@
+import { readFile } from "node:fs/promises";
+import { resolveFromPackage } from "./paths.mjs";
+
+let cached;
+
+export async function loadCatalog() {
+  if (!cached) {
+    cached = JSON.parse(await readFile(resolveFromPackage("content", "catalog.json"), "utf8"));
+  }
+  return cached;
+}
+
+export function selectEntry(entries, selector) {
+  if (!selector) return undefined;
+  const normalized = selector.toLowerCase();
+  return entries.find((entry) =>
+    entry.id === normalized || entry.slug === normalized || entry.aliases?.includes(normalized)
+  );
+}

package/src/core/files.mjs

@@ -0,0 +1,42 @@
+import { access, cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+import { resolveFromPackage } from "./paths.mjs";
+
+export async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function writeSafe(path, contents, { force = false, dryRun = false } = {}) {
+  if (!force && await exists(path)) return { path, status: "skipped" };
+  if (!dryRun) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, contents, "utf8");
+  }
+  return { path, status: dryRun ? "planned" : "created" };
+}
+
+export async function copySafe(source, destination, options = {}) {
+  if (!options.force && await exists(destination)) return { path: destination, status: "skipped" };
+  if (!options.dryRun) {
+    await mkdir(dirname(destination), { recursive: true });
+    await cp(source, destination, { recursive: true, force: Boolean(options.force) });
+  }
+  return { path: destination, status: options.dryRun ? "planned" : "created" };
+}
+
+export async function readTemplate(name, replacements = {}) {
+  let value = await readFile(resolveFromPackage("templates", name), "utf8");
+  for (const [key, replacement] of Object.entries(replacements)) {
+    value = value.replaceAll(`{{${key}}}`, replacement);
+  }
+  return value;
+}
+
+export function displayResults(root, results) {
+  for (const result of results) console.log(`${result.status.padEnd(8)} ${relative(root, result.path)}`);
+}

package/src/core/paths.mjs

@@ -0,0 +1,5 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+export const resolveFromPackage = (...parts) => resolve(packageRoot, ...parts);