feat: add Hermes configuration audit skill

Amp-Thread-ID: https://ampcode.com/threads/T-019fd296-da7a-7667-9bcc-b3e704438f27
Co-authored-by: rekt <omaraziz.dev@gmail.com>

Author: ampagent

skills/auditing-hermes-config/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: auditing-hermes-config
+description: Audits revision-pinned Hermes runtime configuration, native NixOS module options, and host configuration. Use when reviewing Hermes defaults, migrations, validity, module wiring, or revision drift.
+compatibility: Requires Node.js 20+. Nix is optional; static fallback is explicitly limited.
+---
+
+# Auditing Hermes Config
+
+Keep three evidence surfaces separate: Hermes runtime configuration, the exact
+`hermes-agent` NixOS module pinned in `flake.lock`, and target host-effective
+configuration. Absence from defaults alone does not prove invalidity.
+
+## Run
+
+Set the installed skill directory and always identify the target explicitly:
+
+```sh
+SKILL_DIR=/absolute/path/to/skills/auditing-hermes-config
+node "$SKILL_DIR/scripts/hermes-config-audit.mjs" discover --target-repo /path/to/nixos-config --source /exact/worktree --cache /outside/cache
+node "$SKILL_DIR/scripts/hermes-config-audit.mjs" index --target-repo /path/to/nixos-config --source /exact/worktree --cache /outside/cache
+node "$SKILL_DIR/scripts/hermes-config-audit.mjs" audit --target-repo /path/to/nixos-config --host marley --source /exact/worktree --cache /outside/cache --json /outside/reports/audit.json --markdown /outside/reports/audit.md
+node "$SKILL_DIR/scripts/hermes-config-audit.mjs" compare --base /outside/base.json --target /outside/target.json
+```
+
+`--target-repo` is canonical. `HERMES_TARGET_REPO` and upward discovery are
+fallbacks; `--repo` is a compatibility alias. Outputs and cache must be outside
+the target, skills repository, and source worktree. Read
+[surfaces](reference/surfaces.md) before interpreting results and the
+[output schema](reference/output-schema.md) before consuming JSON.
+
+## Discipline
+
+Report **Proper**, **Repo today**, **Gap**, and **Path**. Treat unresolved values
+and incomplete dynamic schemas as uncertainty, never as proof of invalidity.
+`configFile` may bypass generated `settings`; do not realize derivations merely
+to inspect it.
+
+The tool is read-only. Never run Python, build, switch, deploy, rebuild, restart,
+or edit target configuration. Snapshot permits at most one read-only `nix eval`
+per host invocation, disables import-from-derivation, redacts scalar host values,
+and falls back honestly when evaluation fails. Add
+`--host-adapter hosts/marley/hermes/settings.nix` for tracked static local evidence;
+without it static host evidence remains unresolved.
+
+Static analysis is not effective configuration. Dynamic contracts and the
+structural Nix parser can be incomplete; `configFile` content stays unresolved
+without realization; offline Nix can fail. `--latest` is tested with a
+deterministic fake `gh`; live GitHub availability is not tested. Target dirty
+state is reported.

skills/auditing-hermes-config/reference/audit.schema.json

@@ -0,0 +1,165 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.invalid/hermes-config-audit.schema.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "command",
+    "generatedAt",
+    "readOnly",
+    "provenance",
+    "surfaces",
+    "findings",
+    "moduleSummary",
+    "limits",
+    "safety"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 4 },
+    "command": { "const": "audit" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "readOnly": { "const": true },
+    "provenance": {
+      "type": "object",
+      "required": [
+        "selection",
+        "lockedSha",
+        "resolvedSha",
+        "owner",
+        "repo",
+        "targetRepo",
+        "targetDirty",
+        "host"
+      ],
+      "properties": {
+        "selection": { "enum": ["locked", "latest"] },
+        "lockedSha": { "$ref": "#/$defs/sha" },
+        "resolvedSha": { "$ref": "#/$defs/sha" },
+        "owner": { "type": "string", "minLength": 1 },
+        "repo": { "type": "string", "minLength": 1 },
+        "targetRepo": { "type": "string", "minLength": 1 },
+        "targetDirty": { "type": "boolean" },
+        "host": { "type": "string", "minLength": 1 },
+        "resolvedAt": { "type": "string", "format": "date-time" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "selection": { "const": "latest" } } },
+          "then": { "required": ["resolvedAt"] }
+        }
+      ]
+    },
+    "surfaces": {
+      "type": "object",
+      "required": ["runtime", "module", "host"],
+      "properties": {
+        "runtime": {
+          "type": "object",
+          "required": ["contracts", "defaultCount"],
+          "properties": {
+            "contracts": { "type": "object" },
+            "defaultCount": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "module": {
+          "type": "object",
+          "required": [
+            "source",
+            "optionCount",
+            "options",
+            "completeness",
+            "diagnostics",
+            "generation"
+          ],
+          "properties": {
+            "source": { "type": "string" },
+            "optionCount": { "type": "integer" },
+            "options": { "type": "array", "items": { "$ref": "#/$defs/option" } },
+            "completeness": { "type": "string" },
+            "diagnostics": { "type": "array", "items": { "type": "string" } },
+            "generation": { "type": "object" }
+          }
+        },
+        "host": {
+          "type": "object",
+          "required": [
+            "host",
+            "provenance",
+            "evaluated",
+            "runtimeDocument",
+            "moduleValues",
+            "localAssignments",
+            "mode",
+            "settingsEmpty",
+            "configFileBypassesSettings",
+            "limits"
+          ]
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "moduleSummary": {
+      "type": "object",
+      "required": ["effectiveTopLevelValues", "optionCoverage"],
+      "properties": {
+        "effectiveTopLevelValues": { "type": "array" },
+        "optionCoverage": { "const": "unavailable" }
+      }
+    },
+    "limits": { "type": "array", "items": { "type": "string" } },
+    "safety": { "type": "object", "required": ["performed", "forbidden"] }
+  },
+  "$defs": {
+    "sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "evidence": {
+      "type": "object",
+      "required": ["source", "line", "url", "excerpt"],
+      "properties": {
+        "source": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "url": { "type": "string" },
+        "excerpt": { "type": "string" }
+      }
+    },
+    "option": {
+      "type": "object",
+      "required": [
+        "path",
+        "typeExpression",
+        "default",
+        "example",
+        "description",
+        "declaration",
+        "mappingEvidence"
+      ],
+      "properties": {
+        "path": { "type": "string" },
+        "typeExpression": { "type": ["string", "null"] },
+        "declaration": { "$ref": "#/$defs/evidence" },
+        "mappingEvidence": { "type": "array" }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "required": ["path", "classification", "reason"],
+      "properties": {
+        "path": { "type": "string" },
+        "classification": {
+          "enum": [
+            "current",
+            "valid-dynamic-extension",
+            "obsolete-or-wrong-shape",
+            "ignored-or-nonexistent",
+            "intentional-semantic-exception",
+            "uncertain-needs-targeted-review"
+          ]
+        },
+        "reason": { "type": "string" },
+        "evidence": { "$ref": "#/$defs/evidence" }
+      }
+    }
+  }
+}

skills/auditing-hermes-config/reference/output-schema.md

@@ -0,0 +1,29 @@
+# Output schema (schemaVersion 4)
+
+Every document has `schemaVersion`, `command`, and command-specific data. Audit
+documents exactly contain:
+
+- `schemaVersion`, `command`, `generatedAt`, `readOnly`
+- `provenance`: `{ selection, lockedSha, resolvedSha, owner, repo, targetRepo,
+targetDirty, host }`, plus `resolvedAt` for `latest`
+- `surfaces`: `{ runtime: { contracts, defaultCount }, module, host }`
+- `findings[]`: `path`, `classification`, `reason`, plus optional `type`,
+  `unresolved`, and `evidence`; scalar setting values are never emitted
+- `moduleSummary`: `{ effectiveTopLevelValues, optionCoverage: "unavailable" }`
+- `limits[]`
+- `safety`: `{ performed, forbidden }`
+
+Evidence is `{ source, line, url, excerpt }`; upstream URLs include the exact SHA.
+Static or unresolved Markdown explicitly says it is not a complete audit.
+Host documents preserve key/type/unresolved shape but redact scalar values. Report
+files are mode `0600`.
+The machine-readable schema is [audit.schema.json](audit.schema.json).
+
+Useful `jq` queries:
+
+```sh
+jq -r '.provenance.resolvedSha' audit.json
+jq -r '.findings[] | select(.classification == "uncertain-needs-targeted-review") | .path' audit.json
+jq -r '.surfaces.module.options[] | [.path, .typeExpression] | @tsv' audit.json
+jq -r '.limits[]' audit.json
+```

skills/auditing-hermes-config/reference/surfaces.md

@@ -0,0 +1,46 @@
+# Evidence surfaces and limits
+
+## Boundaries
+
+The target is selected by `--target-repo`, then `HERMES_TARGET_REPO`, then upward
+discovery of a `flake.lock` with `nodes.hermes-agent.locked.rev`. `flake.lock`
+and host adapters must be Git-tracked. Every upstream source read is from a
+required path present in the selected commit's `git ls-tree`; paths containing a
+component exactly `_` are refused.
+The exact source worktree's `HEAD` must equal the requested SHA. Paths are
+enumerated from that object with `git ls-tree` and read with `git show`; dirty
+source worktree files therefore cannot affect evidence.
+
+Cache, indexes, temporary outputs, snapshots, and reports stay outside target,
+skills repository, and source worktree. Indexes are recomputed from immutable Git
+objects rather than trusted from mutable cache files. Python is parsed, never
+executed.
+
+## Runtime and platform contracts
+
+The JavaScript literal lexer ignores comments and understands quoted literals,
+collections, booleans, null, and simple numeric arithmetic. It extracts defaults,
+root sets, provider fields/aliases, platform container keys and concrete schemas
+where present. Provider unknown fields are called ignored only when the pinned
+normalizer proves rejection. Platform extraction records completeness; unknown
+fields remain uncertain if rejection cannot be proven.
+
+MCP shapes fail closed: known top-level server fields and explicitly supported
+nested leaves can be valid; unsupported ancestors or nested leaves are uncertain.
+Collision-safe `toolUnresolved: true` tool records remain atomic uncertainty
+records. A genuine `$unresolved` key is ordinary user data.
+
+## Native module and host
+
+Structural Nix extraction recognizes `mkOption`, `mkEnableOption`, nested attrsets,
+and wildcard `mcpServers.<name>` options without assuming a fixed option count.
+Metadata and exact-SHA citations retain line, URL, and excerpt.
+
+Snapshot makes at most one `nix eval` call. It asks the target flake for one host,
+uses JSON-safe values, disables import-from-derivation, is offline/read-only, and
+never deliberately realizes a build. Reports retain key/type shape but redact
+all scalar host values. Static evidence
+requires an explicit tracked `--host-adapter` and never guesses target layout.
+Derivation-backed
+`configFile` contents remain unresolved. Failed/disabled evaluation uses tracked
+static host evidence and explicitly limits every host-effective conclusion.