@kaiohenricunha/harness 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaio Henrique Cunha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# `@kaiohenricunha/harness`
+
+[![npm](https://img.shields.io/npm/v/@kaiohenricunha/harness.svg)](https://www.npmjs.com/package/@kaiohenricunha/harness)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![changelog](https://img.shields.io/badge/changelog-keep--a--changelog-orange.svg)](./CHANGELOG.md)
+
+Portable Claude Code plugin + zero-dependency npm package that bootstraps
+spec-driven-development governance into consumer repos. Ships a structured-error
+CLI, an umbrella `harness` dispatcher, seven standalone bins, a destructive-git
+PreToolUse hook, and a gold-standard shell settings validator.
+
+**Two personas live in this repo** (by design — see [docs/personas.md](./docs/personas.md)):
+
+- The **npm package** under `plugins/harness/` (what consumers install).
+- Kaio's **personal dotfiles** at the top level (symlinked into `~/.claude/` via `bootstrap.sh`).
+
+If you're installing the package, ignore the top-level scripts —
+`package.json.files` excludes them from the tarball.
+
+---
+
+## Consumer quickstart
+
+```bash
+npm i -D @kaiohenricunha/harness
+npx harness-init --project-name my-project --project-type node
+npx harness-doctor          # self-diagnostic
+npx harness-validate-specs  # every bin works standalone or via `npx harness <sub>`
+```
+
+Five minutes end-to-end: [docs/quickstart.md](./docs/quickstart.md).
+
+### Node API
+
+```js
+import {
+  createHarnessContext,
+  validateSpecs,
+  validateManifest,
+  checkSpecCoverage,
+  checkInstructionDrift,
+  scaffoldHarness,
+  ValidationError,
+  ERROR_CODES,
+  EXIT_CODES,
+} from "@kaiohenricunha/harness";
+
+const ctx = createHarnessContext(); // resolves repo root via git
+const { ok, errors } = validateSpecs(ctx); // errors are ValidationError instances
+if (!ok) {
+  for (const err of errors) {
+    if (err.code === ERROR_CODES.SPEC_STATUS_INVALID) {
+      // programmatic reaction to a specific failure class
+    }
+  }
+  process.exit(EXIT_CODES.VALIDATION);
+}
+```
+
+Full contract: [docs/api-reference.md](./docs/api-reference.md).
+
+### CLI contract
+
+Every bin honors `--help`, `--version`, `--json`, `--verbose`, `--no-color` and exits with the named enum:
+
+| Code | Name       | Meaning                                                |
+| ---- | ---------- | ------------------------------------------------------ |
+| 0    | OK         | Success                                                |
+| 1    | VALIDATION | Rule failure (expected failure mode)                   |
+| 2    | ENV        | Misconfigured environment                              |
+| 64   | USAGE      | Bad CLI invocation (matches BSD `sysexits.h EX_USAGE`) |
+
+Per-bin details: [docs/cli-reference.md](./docs/cli-reference.md).
+
+---
+
+## Hardening decisions
+
+Each row links to its ADR (see [docs/adr/](./docs/adr/)):
+
+| Decision                                 | ADR                                                     |
+| ---------------------------------------- | ------------------------------------------------------- |
+| Monorepo dual-persona layout             | [0001](./docs/adr/0001-monorepo-dual-persona-layout.md) |
+| No TypeScript; JSDoc + zero runtime deps | [0002](./docs/adr/0002-no-typescript.md)                |
+| Structured `ValidationError` contract    | [0012](./docs/adr/0012-structured-error-contract.md)    |
+| Exit-code convention `{0,1,2,64}`        | [0013](./docs/adr/0013-exit-code-convention.md)         |
+| CLI ✓/✗/⚠ output format                  | [0014](./docs/adr/0014-cli-tick-cross-warn-format.md)   |
+
+Shell-level hardening (SEC-1..4, OPS-1..2) is enforced today at
+`plugins/harness/scripts/validate-settings.sh`; its 12-case behavioral
+suite at `plugins/harness/tests/test_validate_settings.sh` pins every
+contract.
+
+---
+
+## Personal dotfiles persona
+
+If you're Kaio (or forking for your own dotfiles), the entry-point is:
+
+```bash
+git clone https://github.com/kaiohenricunha/dotclaude.git ~/projects/kaiohenricunha/dotclaude
+cd ~/projects/kaiohenricunha/dotclaude
+./bootstrap.sh                  # symlinks commands/ + skills/ + CLAUDE.md into ~/.claude/
+./sync.sh pull                  # pull + re-bootstrap
+./sync.sh push                  # secret-scan + commit + push
+```
+
+See [CLAUDE.md](./CLAUDE.md) for the global rules this installs.
+
+---
+
+## Further reading
+
+|                                                      |                                             |
+| ---------------------------------------------------- | ------------------------------------------- |
+| [docs/index.md](./docs/index.md)                     | Nav map with persona-tailored entry points  |
+| [docs/quickstart.md](./docs/quickstart.md)           | Install → scaffold → first green validator  |
+| [docs/cli-reference.md](./docs/cli-reference.md)     | Every bin, flag, exit code, `--json` schema |
+| [docs/api-reference.md](./docs/api-reference.md)     | Node API surface                            |
+| [docs/architecture.md](./docs/architecture.md)       | Layer diagram + PR-time sequence            |
+| [docs/troubleshooting.md](./docs/troubleshooting.md) | Error-code → remediation index              |
+| [docs/upgrade-guide.md](./docs/upgrade-guide.md)     | 0.1 → 0.2 migration, forking                |
+| [docs/personas.md](./docs/personas.md)               | Who reads which file                        |
+| [CONTRIBUTING.md](./CONTRIBUTING.md)                 | Dev workflow + local gates                  |
+| [SECURITY.md](./SECURITY.md)                         | Private vulnerability disclosure            |
+| [CHANGELOG.md](./CHANGELOG.md)                       | Keep-a-Changelog history                    |
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@kaiohenricunha/harness",
+  "version": "0.2.0",
+  "description": "Portable harness + SDD validators for Claude Code projects.",
+  "type": "module",
+  "main": "plugins/harness/src/index.mjs",
+  "exports": {
+    ".": "./plugins/harness/src/index.mjs",
+    "./errors": "./plugins/harness/src/lib/errors.mjs",
+    "./exit-codes": "./plugins/harness/src/lib/exit-codes.mjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "harness": "./plugins/harness/bin/harness.mjs",
+    "harness-doctor": "./plugins/harness/bin/harness-doctor.mjs",
+    "harness-detect-drift": "./plugins/harness/bin/harness-detect-drift.mjs",
+    "harness-validate-skills": "./plugins/harness/bin/harness-validate-skills.mjs",
+    "harness-check-spec-coverage": "./plugins/harness/bin/harness-check-spec-coverage.mjs",
+    "harness-validate-specs": "./plugins/harness/bin/harness-validate-specs.mjs",
+    "harness-check-instruction-drift": "./plugins/harness/bin/harness-check-instruction-drift.mjs",
+    "harness-init": "./plugins/harness/bin/harness-init.mjs"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "lint": "echo 'lint target stubs — prettier + markdownlint wiring lands in PR 4/6' && exit 0",
+    "shellcheck": "shellcheck -x bootstrap.sh sync.sh plugins/harness/scripts/*.sh plugins/harness/hooks/*.sh plugins/harness/tests/*.sh plugins/harness/templates/claude/hooks/*.sh plugins/harness/templates/githooks/pre-commit",
+    "dogfood": "npx harness-validate-skills && npx harness-validate-specs && npx harness-check-instruction-drift && npx harness-check-spec-coverage"
+  },
+  "files": [
+    "plugins/harness/src/",
+    "plugins/harness/bin/",
+    "plugins/harness/scripts/",
+    "plugins/harness/templates/",
+    "plugins/harness/hooks/",
+    "plugins/harness/README.md",
+    "plugins/harness/.claude-plugin/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.4",
+    "bats": "^1.11.1",
+    "vitest": "^4.1.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kaiohenricunha/dotclaude.git"
+  },
+  "homepage": "https://github.com/kaiohenricunha/dotclaude#readme",
+  "bugs": {
+    "url": "https://github.com/kaiohenricunha/dotclaude/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "harness",
+    "sdd",
+    "spec-driven",
+    "validator",
+    "linter",
+    "governance",
+    "cli"
+  ],
+  "license": "MIT"
+}

package/plugins/harness/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "harness",
+  "description": "Portable SDD + harness engineering kit: skills-manifest validator, spec-coverage gate, spec-kit validators, instruction-drift detector, destructive-git hook, and `/init-harness` scaffolder. Works in any repo that follows the repo-facts.json + docs/specs/ conventions.",
+  "author": {
+    "name": "Kaio Cunha",
+    "email": "kaiohenricunha@example.com"
+  }
+}

package/plugins/harness/README.md

@@ -0,0 +1,74 @@
+# `@kaiohenricunha/harness`
+
+Portable Claude Code plugin + zero-dependency npm package for
+spec-driven-development governance. Installs seven CLI bins, a Node API
+barrel, a destructive-git PreToolUse hook, and a gold-standard shell
+settings validator.
+
+This README is the npm tarball's entry point. **The full docs set lives at
+<https://github.com/kaiohenricunha/dotclaude/tree/main/docs>.**
+
+## Install
+
+```bash
+npm i -D @kaiohenricunha/harness
+```
+
+Zero runtime dependencies. Engines: Node `>=20`.
+
+## Scaffold + validate
+
+```bash
+npx harness-init --project-name my-project --project-type node
+npx harness-doctor           # self-diagnostic
+npx harness-validate-specs   # or: npx harness validate-specs
+```
+
+## Node API
+
+```js
+import {
+  createHarnessContext,
+  validateSpecs,
+  validateManifest,
+  checkSpecCoverage,
+  checkInstructionDrift,
+  scaffoldHarness,
+  ValidationError,
+  ERROR_CODES,
+  EXIT_CODES,
+} from "@kaiohenricunha/harness";
+
+const ctx = createHarnessContext();
+const { ok, errors } = validateSpecs(ctx); // errors are ValidationError instances
+```
+
+See [api-reference](https://github.com/kaiohenricunha/dotclaude/blob/main/docs/api-reference.md)
+for the full surface.
+
+## Bins
+
+- `harness` — umbrella dispatcher (`harness validate-specs`, `harness doctor`, …)
+- `harness-doctor` — self-diagnostic
+- `harness-init` — scaffold governance tree
+- `harness-validate-specs`, `harness-validate-skills`
+- `harness-check-spec-coverage`, `harness-check-instruction-drift`
+- `harness-detect-drift`
+
+Every bin supports `--help`, `--version`, `--json`, `--verbose`, `--no-color`.
+
+## Exit codes
+
+`{OK:0, VALIDATION:1, ENV:2, USAGE:64}` — `64` mirrors BSD `sysexits.h EX_USAGE`.
+
+## License
+
+MIT. See <https://github.com/kaiohenricunha/dotclaude/blob/main/LICENSE>.
+
+## Links
+
+- [Changelog](https://github.com/kaiohenricunha/dotclaude/blob/main/CHANGELOG.md)
+- [Contributing](https://github.com/kaiohenricunha/dotclaude/blob/main/CONTRIBUTING.md)
+- [Security](https://github.com/kaiohenricunha/dotclaude/blob/main/SECURITY.md)
+- [Quickstart](https://github.com/kaiohenricunha/dotclaude/blob/main/docs/quickstart.md)
+- [Troubleshooting](https://github.com/kaiohenricunha/dotclaude/blob/main/docs/troubleshooting.md)

package/plugins/harness/bin/harness-check-instruction-drift.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * harness-check-instruction-drift — cross-references `docs/repo-facts.json`
+ * against instruction files (CLAUDE.md, README.md, …) to catch stale
+ * team_count claims, missing protected-path documentation, and broken
+ * instruction-file references.
+ *
+ * Exits: 0 no drift, 1 drift detected, 2 env error, 64 usage error.
+ */
+
+import { parse, helpText } from "../src/lib/argv.mjs";
+import { createOutput } from "../src/lib/output.mjs";
+import { EXIT_CODES } from "../src/lib/exit-codes.mjs";
+import { formatError } from "../src/lib/errors.mjs";
+import { version } from "../src/index.mjs";
+import {
+  createHarnessContext,
+  checkInstructionDrift,
+} from "../src/index.mjs";
+
+const META = {
+  name: "harness-check-instruction-drift",
+  synopsis: "harness-check-instruction-drift [OPTIONS]",
+  description: "Detect drift between docs/repo-facts.json and instruction files (team_count, protected_paths, instruction_files).",
+  flags: {
+    "repo-root": { type: "string" },
+  },
+};
+
+let argv;
+try {
+  argv = parse(process.argv.slice(2), META.flags);
+} catch (err) {
+  process.stderr.write(`${err.message}\n`);
+  process.exit(EXIT_CODES.USAGE);
+}
+
+if (argv.help) {
+  process.stdout.write(`${helpText(META)}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+if (argv.version) {
+  process.stdout.write(`${version}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+
+const out = createOutput({ json: argv.json, noColor: argv.noColor });
+
+let ctx;
+try {
+  ctx = createHarnessContext({ repoRoot: argv.flags["repo-root"] });
+} catch (err) {
+  out.fail(`could not resolve repo root: ${err.message}`);
+  out.flush();
+  process.exit(EXIT_CODES.ENV);
+}
+
+let result;
+try {
+  result = checkInstructionDrift(ctx);
+} catch (err) {
+  out.fail(`drift check failed: ${err.message}`);
+  out.flush();
+  process.exit(EXIT_CODES.ENV);
+}
+
+if (result.ok) {
+  out.pass("instruction files match repo facts");
+  out.flush();
+  process.exit(EXIT_CODES.OK);
+}
+
+for (const err of result.errors) {
+  out.fail(formatError(err, { verbose: argv.verbose }), err.toJSON ? err.toJSON() : undefined);
+}
+out.flush();
+process.exit(EXIT_CODES.VALIDATION);

package/plugins/harness/bin/harness-check-spec-coverage.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * harness-check-spec-coverage — verifies that every change to a protected
+ * path is covered by an approved/implementing/done spec, or the PR body
+ * carries a `## No-spec rationale` section.
+ *
+ * Exits: 0 covered, 1 violation, 2 env error, 64 usage error.
+ */
+
+import { parse, helpText } from "../src/lib/argv.mjs";
+import { createOutput } from "../src/lib/output.mjs";
+import { EXIT_CODES } from "../src/lib/exit-codes.mjs";
+import { formatError } from "../src/lib/errors.mjs";
+import { version } from "../src/index.mjs";
+import {
+  createHarnessContext,
+  checkSpecCoverage,
+  getChangedFiles,
+  getPullRequestContext,
+} from "../src/index.mjs";
+
+const META = {
+  name: "harness-check-spec-coverage",
+  synopsis: "harness-check-spec-coverage [OPTIONS]",
+  description: "Check that protected-path changes are covered by a spec (or a No-spec rationale) in the current PR.",
+  flags: {
+    "repo-root": { type: "string" },
+  },
+};
+
+let argv;
+try {
+  argv = parse(process.argv.slice(2), META.flags);
+} catch (err) {
+  process.stderr.write(`${err.message}\n`);
+  process.exit(EXIT_CODES.USAGE);
+}
+
+if (argv.help) {
+  process.stdout.write(`${helpText(META)}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+if (argv.version) {
+  process.stdout.write(`${version}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+
+const out = createOutput({ json: argv.json, noColor: argv.noColor });
+
+let ctx;
+try {
+  ctx = createHarnessContext({ repoRoot: argv.flags["repo-root"] });
+} catch (err) {
+  out.fail(`could not resolve repo root: ${err.message}`);
+  out.flush();
+  process.exit(EXIT_CODES.ENV);
+}
+
+const { isPullRequest, body, actor } = getPullRequestContext();
+const changedFiles = getChangedFiles();
+
+let result;
+try {
+  result = checkSpecCoverage(ctx, { changedFiles, isPullRequest, body, actor });
+} catch (err) {
+  out.fail(`coverage check failed: ${err.message}`);
+  out.flush();
+  process.exit(EXIT_CODES.ENV);
+}
+
+if (result.ok) {
+  out.pass(`spec coverage ok (${result.protectedFiles.length} protected file(s) changed)`);
+  out.flush();
+  process.exit(EXIT_CODES.OK);
+}
+
+for (const err of result.errors) {
+  out.fail(formatError(err, { verbose: argv.verbose }), err.toJSON ? err.toJSON() : undefined);
+}
+out.flush();
+process.exit(EXIT_CODES.VALIDATION);

package/plugins/harness/bin/harness-detect-drift.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * harness-detect-drift — thin bin wrapping `plugins/harness/scripts/detect-branch-drift.mjs`
+ * so `npx harness-detect-drift` works (fixes the broken invocation at
+ * `plugins/harness/templates/workflows/detect-drift.yml:15`).
+ *
+ * Forwards every flag through. Owns --help / --version only.
+ *
+ * Exit codes: whatever detect-branch-drift.mjs returns.
+ */
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { EXIT_CODES } from "../src/lib/exit-codes.mjs";
+import { version } from "../src/index.mjs";
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(
+    [
+      "harness-detect-drift [OPTIONS]",
+      "",
+      "Flag .claude/commands/*.md and skills/**/SKILL.md that diverge from origin/main",
+      "for longer than the drift threshold. Wraps plugins/harness/scripts/detect-branch-drift.mjs.",
+      "",
+      "Options:",
+      "  --help, -h           show this help",
+      "  --version, -V        print harness version",
+      "  (all other flags are forwarded to the underlying script)",
+      "",
+      "Exit codes: 0 ok, 1 drift detected, 2 env error.",
+      "",
+    ].join("\n")
+  );
+  process.exit(EXIT_CODES.OK);
+}
+if (args.includes("--version") || args.includes("-V")) {
+  process.stdout.write(`${version}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const scriptPath = resolve(__dirname, "..", "scripts", "detect-branch-drift.mjs");
+
+const child = spawn(process.execPath, [scriptPath, ...args], { stdio: "inherit" });
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? EXIT_CODES.ENV);
+});

package/plugins/harness/bin/harness-doctor.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * harness-doctor — diagnostic self-check.
+ *
+ * Walks through every invariant a consumer repo (or the harness repo itself,
+ * when dogfooding) must satisfy for validators to run:
+ *
+ *   env          Node >= 20, git on PATH
+ *   repo         git rev-parse --show-toplevel resolves; repoRoot usable
+ *   facts        docs/repo-facts.json exists and parses
+ *   manifest     .claude/skills-manifest.json checksums match (via validateManifest)
+ *   specs        docs/specs/ scanned; validateSpecs clean
+ *   drift        checkInstructionDrift clean
+ *   hook         plugins/harness/hooks/guard-destructive-git.sh present + exec bit
+ *
+ * Exit codes: 0 all green, 1 one or more checks failed (validation), 2 env error.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { parse, helpText } from "../src/lib/argv.mjs";
+import { createOutput } from "../src/lib/output.mjs";
+import { EXIT_CODES } from "../src/lib/exit-codes.mjs";
+import { version } from "../src/index.mjs";
+import {
+  createHarnessContext,
+  validateManifest,
+  validateSpecs,
+  checkInstructionDrift,
+  pathExists,
+} from "../src/index.mjs";
+
+const META = {
+  name: "harness-doctor",
+  synopsis: "harness-doctor [OPTIONS]",
+  description: "Run the harness self-diagnostic across env, repo, facts, manifest, specs, drift, and hooks.",
+  flags: {
+    "repo-root": { type: "string" },
+  },
+};
+
+let argv;
+try {
+  argv = parse(process.argv.slice(2), META.flags);
+} catch (err) {
+  process.stderr.write(`${err.message}\n`);
+  process.exit(EXIT_CODES.USAGE);
+}
+
+if (argv.help) {
+  process.stdout.write(`${helpText(META)}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+if (argv.version) {
+  process.stdout.write(`${version}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+
+const out = createOutput({
+  json: argv.json,
+  noColor: argv.noColor,
+});
+
+let envError = false;
+
+// env: Node + git
+const nodeMajor = Number(process.versions.node.split(".")[0]);
+if (nodeMajor >= 20) {
+  out.pass(`Node ${process.versions.node} (>=20 required)`);
+} else {
+  out.fail(`Node ${process.versions.node} is below the >=20 requirement`);
+  envError = true;
+}
+try {
+  const gitVersion = execFileSync("git", ["--version"], { encoding: "utf8" }).trim();
+  out.pass(`git available — ${gitVersion}`);
+} catch {
+  out.fail("git is not on PATH");
+  envError = true;
+}
+
+// repo: resolve context
+const repoRoot = /** @type {string | undefined} */ (argv.flags["repo-root"]);
+let ctx;
+try {
+  ctx = createHarnessContext({ repoRoot });
+  out.pass(`repo root resolved to ${ctx.repoRoot}`);
+} catch (err) {
+  out.fail(`could not resolve repo root: ${err.message}`);
+  envError = true;
+}
+
+if (envError) {
+  out.flush();
+  process.exit(EXIT_CODES.ENV);
+}
+
+// facts
+if (pathExists(ctx, "docs/repo-facts.json")) {
+  out.pass("docs/repo-facts.json present");
+} else {
+  out.warn("docs/repo-facts.json missing — coverage/drift checks will be no-ops");
+}
+
+// manifest
+if (pathExists(ctx, ".claude/skills-manifest.json")) {
+  const r = validateManifest(ctx);
+  if (r.ok) out.pass(`manifest valid (${r.manifest.skills.length} skills)`);
+  else out.fail(`manifest has ${r.errors.length} error(s)`, { errors: r.errors });
+} else {
+  out.warn(".claude/skills-manifest.json missing — skill inventory not indexed");
+}
+
+// specs
+if (pathExists(ctx, "docs/specs")) {
+  const r = validateSpecs(ctx);
+  if (r.ok) out.pass("specs valid");
+  else out.fail(`specs have ${r.errors.length} error(s)`, { errors: r.errors });
+} else {
+  out.warn("docs/specs/ missing — no specs to validate");
+}
+
+// drift
+try {
+  const r = checkInstructionDrift(ctx);
+  if (r.ok) out.pass("instruction drift clean");
+  else out.fail(`instruction drift: ${r.errors.length} issue(s)`, { errors: r.errors });
+} catch (err) {
+  out.warn(`drift check skipped: ${err.message}`);
+}
+
+// hook
+const hookPath = resolve(ctx.repoRoot, "plugins/harness/hooks/guard-destructive-git.sh");
+if (existsSync(hookPath)) {
+  const mode = statSync(hookPath).mode & 0o111;
+  if (mode) out.pass("guard-destructive-git.sh present + executable");
+  else out.fail("guard-destructive-git.sh present but NOT executable (chmod +x)");
+} else {
+  out.warn("guard-destructive-git.sh missing — destructive git commands are unguarded");
+}
+
+out.flush();
+const { fail } = out.counts();
+process.exit(fail > 0 ? EXIT_CODES.VALIDATION : EXIT_CODES.OK);