@kaiohenricunha/harness 0.2.0

package/plugins/harness/src/validate-specs.mjs

@@ -0,0 +1,217 @@
+import path from "path";
+import {
+  anyPathMatches,
+  listRepoPaths,
+  listSpecDirs,
+  readJson,
+  pathExists,
+} from "./spec-harness-lib.mjs";
+import { ValidationError, ERROR_CODES } from "./lib/errors.mjs";
+
+const VALID_STATUSES = new Set([
+  "draft",
+  "approved",
+  "implementing",
+  "done",
+]);
+
+/**
+ * Validate every spec.json under docs/specs/.
+ *
+ * Checks performed per spec:
+ *  - spec.json exists
+ *  - required fields present and non-empty: id, title, status, owners, linked_paths, acceptance_commands, depends_on_specs, active_prs
+ *  - status is one of the allowed enum values
+ *  - id matches the directory name
+ *  - linked_paths entries are non-empty strings
+ *  - acceptance_commands entries are non-empty strings
+ *
+ * Cross-spec checks:
+ *  - depends_on_specs references resolve to known spec ids
+ *
+ * @param {object} ctx  Harness context from createHarnessContext().
+ * @returns {{ ok: boolean, errors: ValidationError[] }}
+ */
+export function validateSpecs(ctx) {
+  const errors = [];
+  const specDirs = listSpecDirs(ctx);
+  const repoPaths = listRepoPaths(ctx);
+
+  // Collect known spec IDs for cross-reference resolution.
+  const specIds = new Set(specDirs);
+
+  for (const specDir of specDirs) {
+    const specJsonRelative = `docs/specs/${specDir}/spec.json`;
+    const prefix = `docs/specs/${specDir}`;
+
+    if (!pathExists(ctx, specJsonRelative)) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.SPEC_JSON_INVALID,
+        category: "spec",
+        file: prefix,
+        message: "missing spec.json",
+        hint: "create spec.json with required fields (id, title, status, owners, linked_paths, acceptance_commands)",
+      }));
+      continue;
+    }
+
+    let metadata;
+    try {
+      metadata = readJson(ctx, specJsonRelative);
+    } catch (err) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.SPEC_JSON_INVALID,
+        category: "spec",
+        file: prefix,
+        message: `spec.json is not valid JSON — ${err.message}`,
+        hint: "run `node -e \"JSON.parse(require('fs').readFileSync('docs/specs/<id>/spec.json','utf8'))\"` to locate the parse error",
+      }));
+      continue;
+    }
+
+    // id must match directory name.
+    if (metadata.id !== specDir) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.SPEC_ID_MISMATCH,
+        category: "spec",
+        file: prefix,
+        pointer: "id",
+        expected: specDir,
+        got: String(metadata.id),
+        message: `spec.json id "${metadata.id}" must equal directory name "${specDir}"`,
+      }));
+    }
+
+    // title: required, non-empty string.
+    if (typeof metadata.title !== "string" || !metadata.title.trim()) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.SPEC_MISSING_REQUIRED_FIELD,
+        category: "spec",
+        file: prefix,
+        pointer: "title",
+        message: "spec.json title must be a non-empty string",
+      }));
+    }
+
+    // status: required, must be in enum.
+    if (!VALID_STATUSES.has(metadata.status)) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.SPEC_STATUS_INVALID,
+        category: "spec",
+        file: prefix,
+        pointer: "status",
+        expected: [...VALID_STATUSES].join(", "),
+        got: String(metadata.status),
+        message: `invalid status "${metadata.status}" (allowed: ${[...VALID_STATUSES].join(", ")})`,
+      }));
+    }
+
+    // owners: required, non-empty array.
+    if (!Array.isArray(metadata.owners) || metadata.owners.length === 0) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.SPEC_MISSING_REQUIRED_FIELD,
+        category: "spec",
+        file: prefix,
+        pointer: "owners",
+        message: "owners must be a non-empty array",
+      }));
+    }
+
+    // linked_paths: required, non-empty array of strings.
+    if (!Array.isArray(metadata.linked_paths) || metadata.linked_paths.length === 0) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.SPEC_LINKED_PATH_MISSING,
+        category: "spec",
+        file: prefix,
+        pointer: "linked_paths",
+        message: "linked_paths must be a non-empty array",
+      }));
+    } else {
+      for (const linkedPath of metadata.linked_paths) {
+        if (typeof linkedPath !== "string" || !linkedPath.trim()) {
+          errors.push(new ValidationError({
+            code: ERROR_CODES.SPEC_LINKED_PATH_MISSING,
+            category: "spec",
+            file: prefix,
+            pointer: "linked_paths[]",
+            got: JSON.stringify(linkedPath),
+            message: "linked_paths entries must be non-empty strings",
+          }));
+        }
+      }
+    }
+
+    // acceptance_commands: required, non-empty array of non-empty strings.
+    if (!Array.isArray(metadata.acceptance_commands) || metadata.acceptance_commands.length === 0) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.SPEC_ACCEPTANCE_EMPTY,
+        category: "spec",
+        file: prefix,
+        pointer: "acceptance_commands",
+        message: "acceptance_commands must be a non-empty array",
+      }));
+    } else {
+      for (const cmd of metadata.acceptance_commands) {
+        if (typeof cmd !== "string" || !cmd.trim()) {
+          errors.push(new ValidationError({
+            code: ERROR_CODES.SPEC_ACCEPTANCE_EMPTY,
+            category: "spec",
+            file: prefix,
+            pointer: "acceptance_commands[]",
+            got: JSON.stringify(cmd),
+            message: "acceptance_commands entries must be non-empty strings",
+          }));
+        }
+      }
+    }
+
+    // depends_on_specs: must be an array (can be empty).
+    if (!Array.isArray(metadata.depends_on_specs)) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.SPEC_MISSING_REQUIRED_FIELD,
+        category: "spec",
+        file: prefix,
+        pointer: "depends_on_specs",
+        message: "depends_on_specs must be an array",
+      }));
+    }
+
+    // active_prs: must be an array (can be empty).
+    if (!Array.isArray(metadata.active_prs)) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.SPEC_MISSING_REQUIRED_FIELD,
+        category: "spec",
+        file: prefix,
+        pointer: "active_prs",
+        message: "active_prs must be an array",
+      }));
+    }
+  }
+
+  // Cross-spec: depends_on_specs references must resolve.
+  for (const specDir of specDirs) {
+    const specJsonRelative = `docs/specs/${specDir}/spec.json`;
+    if (!pathExists(ctx, specJsonRelative)) continue;
+    let metadata;
+    try {
+      metadata = readJson(ctx, specJsonRelative);
+    } catch {
+      continue;
+    }
+    for (const dependency of metadata.depends_on_specs ?? []) {
+      if (typeof dependency !== "string" || !dependency.trim()) continue;
+      if (!specIds.has(dependency)) {
+        errors.push(new ValidationError({
+          code: ERROR_CODES.SPEC_DEPENDENCY_UNKNOWN,
+          category: "spec",
+          file: `docs/specs/${specDir}`,
+          pointer: "depends_on_specs",
+          got: dependency,
+          message: `depends_on_specs references unknown spec "${dependency}"`,
+        }));
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/plugins/harness/templates/claude/hooks/guard-destructive-git.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# PreToolUse hook: block destructive git operations.
+# Reads JSON from stdin (Claude Code hook protocol).
+# Exit 2 = block the tool call (Claude Code hook protocol — NOT the harness
+# validator exit convention). Exit 0 = allow.
+#
+# Bypass: set BYPASS_DESTRUCTIVE_GIT=1 in the command's environment when you
+# genuinely need to run a destructive git invocation. Use sparingly — the
+# block exists because these operations are silently destructive.
+
+# Fail open if jq is not installed (don't break all Bash tool calls).
+if ! command -v jq >/dev/null 2>&1; then
+  exit 0
+fi
+
+if [ "${BYPASS_DESTRUCTIVE_GIT:-0}" = "1" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty')
+[ "$TOOL" = "Bash" ] || exit 0
+
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')
+NORM=$(printf '%s' "$CMD" | tr '\t' ' ' | tr -s ' ')
+
+BOUNDARY='(^|[[:space:];&|])'
+G='git[[:space:]]+'
+
+PATTERNS=(
+  "${BOUNDARY}${G}reset[[:space:]]+--hard(\b|[[:space:]]|$)"
+  "${BOUNDARY}${G}push[[:space:]][^&;|]*(-f|--force|--force-with-lease)(\b|=|[[:space:]]|$)"
+  "${BOUNDARY}${G}clean[[:space:]][^&;|]*(-[a-zA-Z]*f[a-zA-Z]*|--force)(\b|=|[[:space:]]|$)"
+  "${BOUNDARY}${G}checkout[[:space:]]+\.(\b|$)"
+  "${BOUNDARY}${G}restore[[:space:]]+\.(\b|$)"
+  "${BOUNDARY}${G}branch[[:space:]]+-D\b"
+  "${BOUNDARY}${G}worktree[[:space:]]+remove[[:space:]]+--force\b"
+)
+
+for rx in "${PATTERNS[@]}"; do
+  if printf '%s' "$NORM" | grep -qE "$rx"; then
+    {
+      echo "BLOCKED: Destructive git operation detected. Get explicit user confirmation first."
+      echo "         Bypass (only with user confirmation): BYPASS_DESTRUCTIVE_GIT=1 <your command>"
+    } >&2
+    exit 2
+  fi
+done
+
+exit 0

package/plugins/harness/templates/claude/settings.headless.json

@@ -0,0 +1,24 @@
+{
+  "_note": "Conservative deny-list for unattended runs. Extend per-repo as needed.",
+  "permissions": {
+    "allow": [
+      "Read",
+      "Grep",
+      "Glob",
+      "Bash(git status)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)"
+    ],
+    "deny": [
+      "Bash(git push:*)",
+      "Bash(git push)",
+      "Bash(git reset --hard:*)",
+      "Bash(git reset --hard)",
+      "Bash(git clean -f:*)",
+      "Bash(git clean -fd:*)",
+      "Bash(npm publish:*)",
+      "Bash(npm publish)"
+    ]
+  }
+}

package/plugins/harness/templates/claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-destructive-git.sh\"",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/harness/templates/claude/skills-manifest.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "version": "1.0.0",
+  "generatedAt": "{{today}}",
+  "skills": []
+}

package/plugins/harness/templates/docs/repo-facts.json

@@ -0,0 +1,17 @@
+{
+  "project_name": "{{project_name}}",
+  "project_type": "{{project_type}}",
+  "protected_paths": [
+    "CLAUDE.md",
+    "README.md",
+    ".github/workflows/**",
+    ".claude/commands/**",
+    ".claude/hooks/**",
+    ".claude/settings.json",
+    ".claude/settings.headless.json",
+    ".claude/skills-manifest.json",
+    "docs/repo-facts.json",
+    "docs/specs/**/spec.json"
+  ],
+  "verification_commands": []
+}

package/plugins/harness/templates/docs/specs/README.md

@@ -0,0 +1,36 @@
+# Specs
+
+Each spec lives in its own directory with a `spec.json` metadata file and supporting markdown.
+
+## Layout
+
+```
+docs/specs/
+├─ <slug>/
+│  ├─ spec.json          Required metadata
+│  ├─ spec.md            Human-readable spec
+│  └─ (requirements.md, design.md, tasks.md — optional phase docs)
+└─ README.md             This file
+```
+
+## spec.json schema
+
+```json
+{
+  "id": "unique-slug-matching-dir-name",
+  "title": "Human title",
+  "status": "draft | approved | implementing | done",
+  "owners": ["Person Name"],
+  "linked_paths": ["glob", "patterns", "of/files/this/spec/covers/**"],
+  "acceptance_commands": ["npm test", "go test ./..."],
+  "depends_on_specs": [],
+  "active_prs": []
+}
+```
+
+## Workflow
+
+1. Draft → `status: draft`; no CI enforcement yet.
+2. Approve → `status: approved`; files in `linked_paths` now require this spec (or a `No-spec rationale`) in any PR that touches them.
+3. Implement → `status: implementing`; work in progress, same gating.
+4. Done → `status: done`; spec remains as governance over linked_paths (Böckeler's "spec-anchored" mode).

package/plugins/harness/templates/githooks/pre-commit

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+staged=$(git diff --cached --name-only --diff-filter=ACMR)
+if echo "$staged" | grep -qE '^\.claude/(commands|skills)/'; then
+  echo "harness: auto-updating skills-manifest.json"
+  npx harness-validate-skills --update
+  git add .claude/skills-manifest.json
+fi

package/plugins/harness/templates/workflows/ai-review.yml

@@ -0,0 +1,28 @@
+# Always-on AI PR review via Claude-headless.
+#
+# Phase 5 of the SDD & Harness Hardening plan chose this path over Vercel Agent
+# because it works in any repo with an ANTHROPIC_API_KEY secret — no per-repo
+# Vercel project linking required. Swap to vercel:vercel-agent per-project if
+# the host project is Vercel-deployed and prefers that integration.
+#
+# Requires: ANTHROPIC_API_KEY set as a GitHub Actions secret.
+# Scope: runs only on same-repo PRs (not forks) to prevent secret exfiltration
+# via malicious PR (SEC-6 in the spec).
+name: AI PR review
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false && github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with: { fetch-depth: 0 }
+      - name: Run /review-prs headless
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          npx @anthropic-ai/claude-code -p "Run /review-prs for PR #${{ github.event.pull_request.number }}" \
+            --settings .claude/settings.headless.json --max-turns 40

package/plugins/harness/templates/workflows/detect-drift.yml

@@ -0,0 +1,15 @@
+name: Detect harness drift
+on:
+  schedule:
+    - cron: "0 12 * * 1"
+  workflow_dispatch:
+
+jobs:
+  detect:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f
+        with: { node-version: "22" }
+      - run: npx --yes @kaiohenricunha/harness harness-detect-drift

package/plugins/harness/templates/workflows/validate-skills.yml

@@ -0,0 +1,36 @@
+name: Validate Skills Inventory
+
+on:
+  schedule:
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - ".claude/commands/**"
+      - ".claude/skills/**"
+      - ".claude/skills-manifest.json"
+      - "docs/specs/**/spec.json"
+      - "docs/repo-facts.json"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: "22"
+          cache: "npm"
+      - run: npm ci
+      - run: npx harness-validate-skills
+      - run: npx harness-validate-specs
+      - run: npx harness-check-instruction-drift
+      - name: Check for stale skills (30-day window)
+        run: |
+          node -e "
+            const m = require('./.claude/skills-manifest.json');
+            const cut = new Date(); cut.setDate(cut.getDate() - 30);
+            const stale = m.skills.filter(s => new Date(s.lastValidated) < cut);
+            if (stale.length) { console.log('Stale:'); stale.forEach(s => console.log(' -', s.name)); process.exit(1); }
+            console.log('✅ all skills within 30 days');
+          "