novahiz 0.2.2 → 0.2.5

package/skills/novahiz-planner/SKILL.md

@@ -80,8 +80,7 @@ The full pipeline applies to `code`, `debug`, `browser`, `design-ui`, `database-
 ## Cross-cutting rules
 
 - **Choices through the interface**: every user-facing decision runs through the `question` tool. Interactive table, options described by consequence, recommended option first. No prose questions or confirmation requests in chat. Chat carries context and content; the interface carries choices.
-- **humanizer** on all prose: text, documentation, interface messages, comments.
-- **anti-AI-design** / catalog design skills on everything that touches visual style.
+- **novahiz-humanizer, ui-slop-remover, ui-craft-rules** only on frontend design tasks (R13).
 - **Supabase skills** (`supabase`, `supabase-postgres-best-practices`) on the `database-supabase` category.
 - **Honesty**: no claimed execution without real output. Uncertainty gets stated.
 - **Critique**: an inconsistent, ambiguous, risky, or weak request gets challenged, with an alternative on the table.

package/skills/openapi-mcp-server/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: "openapi-mcp-server"
+description: "Ship an MCP server from an OpenAPI contract: tool granularity, JSON Schema 2020-12, streamable HTTP, OAuth, annotations, search/fetch read pair, MCP Inspector. Use when exposing a REST API to agents, generating tools from openapi.yaml, or reviewing an MCP server before production."
+license: "Apache-2.0"
+metadata:
+  author: Novahiz
+  organization: Novahiz
+  version: "1.0.0"
+  date: September 2026
+---
+
+# openapi-mcp-server
+
+Turn a documented REST API into an MCP server agents can call safely. Spec first: MCP JSON Schema is the source of truth for messages (TypeScript schema + generated JSON Schema).
+
+## Contract prep
+
+1. OpenAPI 2.0 or 3.x, absolute base URL in `servers`, security schemes declared.
+2. Fix common defects before codegen: duplicate `operationId`, missing path params, wrong types, dangling `$ref`.
+3. Pick a dialect: JSON Schema 2020-12 is the MCP default when `$schema` is absent.
+4. Auth stays in the host (bearer, OAuth 2.1, mTLS). Tokens never enter tool results or `_meta`.
+
+A clean contract usually yields working tools on the first pass; residual failures are often small schema bugs, not framework issues.
+
+## Tool shape (do not mirror 1:1)
+
+Map **user goals**, not every endpoint:
+
+| Bad | Good |
+|---|---|
+| 80 REST verbs as tools | `search`, `get_project`, `update_project` |
+| One mega-tool with mode enum | One action per tool |
+
+Each tool needs:
+
+- Action-oriented `name` (prefer `camelCase` for tokenization).
+- `description` that says **when** to use it and one short example.
+- Explicit `inputSchema`; `outputSchema` when structured.
+- Accurate annotations: `readOnlyHint`, `destructiveHint`, `openWorldHint`.
+- Handler that authorizes, validates, and rate-limits.
+
+Annotations are hints. They never replace server-side authz.
+
+For research-style hosts, implement the standard read pair:
+
+- `search(query)` → `id`, `title`, `text`, `url` (canonical, citable).
+- `fetch(id)` → full document + same `url` shape.
+
+Return `structuredContent` plus a JSON string in `content` for older clients. Stable ids let later tool calls join records.
+
+## Server surface
+
+- `instructions` on initialize: workflows, required tool order, rate limits. Keep the first characters dense; do not rewrite every tool description.
+- Prefer a handful of high-level tools over dozens of micro-tools (token cost and multi-hop thrash).
+- Avoid framing empty search results as hard “not found”; return closest matches so the model can reason.
+
+## Transport and deploy
+
+- Dev: stdio. Prod remote: streamable HTTP at a stable URL (often `.../mcp`).
+- HTTPS, auth on every request, timeouts, limits on expensive tools.
+- Secrets from the host secret manager only; no secrets in the OpenAPI file or tool results.
+- Post-deploy: MCP Inspector against initialize, tools list, schemas, auth, and error paths.
+
+## Security checklist
+
+- [ ] Every tool input treated as untrusted; validated server-side.
+- [ ] Authz in the handler for every call (model never decides access).
+- [ ] Confirmation path for write/destructive tools.
+- [ ] No tokens, PII, or internal ids that grant access in results.
+- [ ] Rate limits + logs that omit credentials.
+- [ ] Schema dialect documented; output schemas validate.
+- [ ] Names and schemas stay backward compatible once published.
+
+## Sources
+
+MCP specification (modelcontextprotocol.io, 2025 revisions): tools, JSON Schema dialect, authorization. OpenAI developer guidance on building MCP servers and plugin tools. Cloudflare openApiMcpServer pattern. AutoMCP paper on OpenAPI-to-MCP failure modes. Original Novahiz synthesis; no upstream skill text.

package/skills/openapi-mcp-server/references/mcp-ship-checklist.md

@@ -0,0 +1,30 @@
+# MCP checklist (ship gate)
+
+Service / server: __________________  Date: __________________
+
+## Contract
+
+- [ ] OpenAPI validated (full validator + `openapi_mcp_lint.mjs` HIGH = 0)
+- [ ] Absolute https base URL
+- [ ] operationIds unique; path params declared
+
+## Tools
+
+- [ ] Goal-oriented names (not verb dump)
+- [ ] description: when + example
+- [ ] inputSchema / outputSchema complete
+- [ ] annotations match read vs write behavior
+- [ ] search/fetch pair if retrieval surface
+
+## Runtime
+
+- [ ] MCP Inspector: initialize, tools/list, sample calls
+- [ ] Auth 401/403 path tested
+- [ ] Rate limits and timeouts on expensive tools
+- [ ] Logs contain no tokens
+- [ ] instructions block at initialize is short and dense
+
+## Ship
+
+- [ ] Names/schema backward-compatible with previous publish
+- [ ] Owner and rollback contact recorded

package/skills/openapi-mcp-server/references/tool-worksheet.md

@@ -0,0 +1,30 @@
+# MCP tool worksheet
+
+API / service: __________________  Owner: __________________  Date: __________________
+
+## Goal mapping
+
+| User goal | Proposed tool name | Read/write | Source operations |
+|---|---|---|---|
+| | | | |
+
+Rules: one tool per goal; no 1:1 verb dump; `search`/`fetch` pair for retrieval.
+
+## Per-tool fields
+
+For each name above:
+
+- [ ] camelCase name, stable once published
+- [ ] description: when + one example
+- [ ] inputSchema required fields only
+- [ ] outputSchema if structured
+- [ ] annotations (readOnly / destructive / openWorld) match real behavior
+- [ ] server-side authz + validation + rate limit
+- [ ] no secrets in results
+
+## Ship gate
+
+- [ ] openapi_mcp_lint HIGH = 0 (plus full OpenAPI validator)
+- [ ] MCP Inspector: initialize, tools/list, sample calls
+- [ ] Auth path tested (401/403)
+- [ ] Logs free of tokens

package/skills/openapi-mcp-server/scripts/openapi_mcp_lint.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * openapi-mcp-server: lint an OpenAPI document for MCP conversion readiness.
+ * Offline structural checks. Not a full OpenAPI validator.
+ *
+ * Usage: node scripts/openapi_mcp_lint.mjs <openapi.yaml|json> [...]
+ * Exit 1 if any HIGH finding.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { extname } from "node:path";
+
+function loadDoc(path) {
+  const text = readFileSync(path, "utf8");
+  const ext = extname(path).toLowerCase();
+  if (ext === ".json") return JSON.parse(text);
+  // Minimal YAML: try JSON first (some exports are JSON with .yaml name is wrong);
+  // for real YAML without a parser dependency, only handle JSON-compatible subset.
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { __yaml: true, __raw: text };
+  }
+}
+
+function walkOps(doc) {
+  const out = [];
+  const paths = doc.paths || {};
+  const methods = new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
+  for (const [p, item] of Object.entries(paths)) {
+    if (!item || typeof item !== "object") continue;
+    for (const [m, op] of Object.entries(item)) {
+      if (!methods.has(m)) continue;
+      if (!op || typeof op !== "object") continue;
+      out.push({ path: p, method: m, op });
+    }
+  }
+  return out;
+}
+
+function lint(path) {
+  const findings = [];
+  const push = (level, id, msg) => findings.push({ level, id, file: path, msg });
+
+  if (!existsSync(path)) {
+    push("HIGH", "missing-file", "File not found");
+    return findings;
+  }
+
+  let doc;
+  try {
+    doc = loadDoc(path);
+  } catch (e) {
+    push("HIGH", "parse-error", `Cannot parse: ${e.message}`);
+    return findings;
+  }
+
+  if (doc.__yaml) {
+    push("MED", "yaml-needs-external-validator", "YAML detected; run a full OpenAPI validator (swagger-cli / redocly) as well");
+    return findings;
+  }
+
+  if (!doc.openapi && !doc.swagger) {
+    push("HIGH", "not-openapi", "Missing openapi/swagger version field");
+  }
+
+  const servers = doc.servers || (doc.host ? [{ url: `https://${doc.host}${doc.basePath || ""}` }] : []);
+  if (!servers.length) {
+    push("HIGH", "no-servers", "No servers/base URL; absolute base required for MCP handlers");
+  } else if (servers.some((s) => !s.url || s.url.startsWith("/"))) {
+    push("MED", "relative-server", "Server URL is relative; prefer absolute https URL");
+  }
+
+  const ops = walkOps(doc);
+  if (ops.length === 0) {
+    push("HIGH", "no-operations", "No path operations found");
+  }
+
+  const ids = new Map();
+  for (const { path: p, method, op } of ops) {
+    const loc = `${method.toUpperCase()} ${p}`;
+    if (!op.operationId) {
+      push("MED", "missing-operationId", `${loc}: missing operationId`);
+    } else {
+      if (ids.has(op.operationId)) {
+        push("HIGH", "duplicate-operationId", `${loc}: duplicate operationId ${op.operationId}`);
+      } else {
+        ids.set(op.operationId, loc);
+      }
+    }
+    if (!op.summary && !op.description) {
+      push("MED", "missing-description", `${loc}: no summary/description for tool text`);
+    }
+    // path params declared?
+    const pathParams = (p.match(/\{[^}]+\}/g) || []).map((s) => s.slice(1, -1));
+    const opParams = (op.parameters || []).filter((x) => x && x.in === "path");
+    for (const pp of pathParams) {
+      if (!opParams.some((x) => x.name === pp)) {
+        push("HIGH", "undefined-path-param", `${loc}: path {${pp}} not in parameters`);
+      }
+    }
+  }
+
+  const hasSecurity =
+    Object.keys(doc.components?.securitySchemes || {}).length > 0 ||
+    Array.isArray(doc.security) ||
+    ops.some((o) => o.op.security);
+  if (!hasSecurity) {
+    push("LOW", "no-security-schemes", "No security schemes declared; document how host auth works");
+  }
+
+  return findings;
+}
+
+const files = process.argv.slice(2);
+if (files.length === 0) {
+  console.error("usage: node scripts/openapi_mcp_lint.mjs <openapi.yaml|json> [...]");
+  process.exit(2);
+}
+
+const all = files.flatMap(lint);
+const byLevel = { HIGH: [], MED: [], LOW: [] };
+for (const f of all) byLevel[f.level].push(f);
+
+for (const level of ["HIGH", "MED", "LOW"]) {
+  for (const f of byLevel[level]) {
+    console.log(`${level}\t${f.id}\t${f.file}\t${f.msg}`);
+  }
+}
+
+const high = byLevel.HIGH.length;
+console.error(`openapi_mcp_lint: ${files.length} files, ${all.length} findings (${high} HIGH)`);
+process.exit(high > 0 ? 1 : 0);

package/skills/package-risk-audit/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: "package-risk-audit"
+description: "Dependency and supply-chain risk audit: lockfiles, typosquat and dependency confusion checks, OSV/CVE triage, license exposure, SBOM generation, update policy. Use when adding a package, reviewing package.json/pnpm-lock/Cargo.lock/go.mod, investigating a CVE, or preparing a release BOM."
+license: "Apache-2.0"
+metadata:
+  author: Novahiz
+  organization: Novahiz
+  version: "1.0.0"
+  date: September 2026
+---
+
+# package-risk-audit
+
+Decide whether a dependency is safe to take, keep, or drop. Aligns with OWASP Top 10 2025 A03 (software supply chain failures) and OSSF package-manager practice.
+
+## Intake (new package)
+
+1. Exact name and registry; prefer official source over mirrors.
+2. Why this package beats a small in-repo implementation (cost of ownership).
+3. Repo health: maintainers, release cadence, open critical issues, OpenSSF Scorecard if available.
+4. Transitive size: what it pulls in; `deps.dev` or lockfile graph.
+5. License compatible with the product license.
+6. Pin strategy: exact version or lockfile hash; no floating `latest`.
+
+Reject or quarantine when: brand-new account, name within Levenshtein distance of a popular package with no clear link, install scripts that fetch remote binaries, or maintainers you cannot map to a known org.
+
+## Typosquat and confusion
+
+- Compare the name to the intended package (edit distance, homoglyphs, extra suffixes like `-utils`, `-pro`).
+- Scope private packages (`@yorg/...`) so npm cannot silently resolve them from the public registry.
+- Disable “merge with upstream” on internal proxies; fail the build on 404 instead of falling back to public.
+- Claim the org name on public registries even if you only publish privately.
+
+Confusion attacks are mostly semantic; typos are only one mechanism. A rename that swaps one word (`discord.js` vs `discord.dll`) is a real flag.
+
+## Vulnerability triage
+
+| Source | Use |
+|---|---|
+| OSV / GitHub Advisory | Primary advisory query per ecosystem |
+| NVD CVE | When OSV is thin for a stack |
+| OSSF malicious-packages | Known malicious publishes |
+
+For each hit:
+
+1. Is the package actually reachable in your build (not dev-only, not optional unused)?
+2. Fixed version available? Semver-compatible?
+3. Exploitability in your call path (not only CVSS).
+4. Action: upgrade, patch pin, replace, or document accepted risk with an owner and review date.
+
+Do not mass-upgrade majors in the same PR as product changes.
+
+## Lockfile and reproducibility
+
+- Commit the lockfile; CI installs frozen/`--frozen-lockfile`/`cargo build --locked` style.
+- Prefer hash pinning the manager already stores; treat lockfile diffs as security-relevant.
+- Remove unused deps on a schedule (`npm prune`, `cargo machete` equivalent, `go mod tidy`).
+- Build images and artifacts from the lockfile, not from a developer’s global cache.
+
+## SBOM and inventory
+
+Generate a CycloneDX or SPDX SBOM on release (and on demand for customers). Contents: direct and transitive components, versions, licenses, purls. Store next to the artifact. Diff SBOMs between releases to spot unexpected new packages.
+
+## Update policy
+
+- Critical/high with fix: same week (or documented exception).
+- Dependabot/Renovate (or equivalent) with security alerts on.
+- Staged rollout when the vendor is new to you; canary before fleet-wide.
+- Unmaintained dependency with no fix: plan a replacement; virtual patch only buys time.
+
+## Checklist
+
+- [ ] Name and registry verified; scope confusion impossible.
+- [ ] Lockfile present, committed, enforced in CI.
+- [ ] OSV/advisory scan clean or triaged with owners.
+- [ ] License recorded in SBOM; copyleft OK for ship context.
+- [ ] Install scripts reviewed or disabled.
+- [ ] Transitive graph understood for the new package.
+- [ ] Update bot and alert channel configured.
+
+## Sources
+
+OWASP Top 10 2025 A03; OSSF package-manager best practices (npm and peers); OSV schema and OSSF malicious-packages; ConfuGuard / Neupane package-confusion research. Original Novahiz synthesis.

package/skills/package-risk-audit/references/intake-worksheet.md

@@ -0,0 +1,19 @@
+# New dependency worksheet
+
+Package: __________________  Registry: __________________  Date: __________________
+
+| Question | Answer |
+|---|---|
+| Exact name and intended package | |
+| Why not in-repo or stdlib | |
+| Repo / maintainers verified | |
+| Scorecard or equivalent | |
+| Transitive count | |
+| License | |
+| Install scripts? | |
+| Pin / lockfile entry | |
+| OSV hits triaged | |
+
+Decision: accept | reject | conditional (conditions: ______________)
+
+Owner: ______________  Review date: ______________

package/skills/package-risk-audit/scripts/dep_risk_lint.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * package-risk-audit: lightweight dependency risk hints from manifests.
+ * Offline heuristics. Pair with `npm audit` / OSV queries for CVEs.
+ *
+ * Usage: node scripts/dep_risk_lint.mjs <project-dir> [...]
+ * Exit 1 if any HIGH finding.
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+
+const LOCKFILES = [
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lockb",
+  "bun.lock",
+  "Cargo.lock",
+  "poetry.lock",
+  "Pipfile.lock",
+  "composer.lock",
+];
+
+const SUSPICIOUS_NAME = /(?:^|[-_.@])(util|utils|helper|helpers|core|base|common|lib)(?:$|[-_.@])/i;
+
+function walkProjects(root, out = []) {
+  const st = statSync(root);
+  if (!st.isDirectory()) return out;
+  const hasManifest =
+    existsSync(join(root, "package.json")) ||
+    existsSync(join(root, "Cargo.toml")) ||
+    existsSync(join(root, "pyproject.toml")) ||
+    existsSync(join(root, "go.mod"));
+  if (hasManifest) out.push(root);
+  if (basename(root) === "node_modules" || basename(root) === "target" || basename(root) === ".git") return out;
+  for (const name of readdirSync(root)) {
+    const p = join(root, name);
+    try {
+      if (statSync(p).isDirectory()) walkProjects(p, out);
+    } catch {
+      /* ignore */
+    }
+  }
+  return out;
+}
+
+function checkProject(dir) {
+  const findings = [];
+  const push = (level, id, file, msg) => findings.push({ level, id, file, msg });
+
+  const lock = LOCKFILES.find((l) => existsSync(join(dir, l)));
+  const pkgPath = join(dir, "package.json");
+
+  if (existsSync(pkgPath) && !lock) {
+    push("HIGH", "missing-lockfile", pkgPath, "package.json without committed lockfile");
+  }
+
+  if (existsSync(pkgPath)) {
+    let pkg;
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    } catch {
+      push("HIGH", "manifest-parse", pkgPath, "package.json is not valid JSON");
+      pkg = null;
+    }
+    if (pkg) {
+      const deps = {
+        ...(pkg.dependencies || {}),
+        ...(pkg.devDependencies || {}),
+      };
+      for (const [name, range] of Object.entries(deps)) {
+        if (range === "*" || range === "latest" || range === "next") {
+          push("HIGH", "floating-range", `${pkgPath}#${name}`, `Unpinned range: ${range}`);
+        }
+        if (/@[^/]+\/[^/]+$/.test(name) === false && name.includes("/") && !name.startsWith("@")) {
+          // git or path deps often used for attacks when unexpected
+          if (String(range).startsWith("git") || String(range).includes("github:")) {
+            push("MED", "git-dependency", `${pkgPath}#${name}`, `Git dependency: ${range}`);
+          }
+        }
+        if (SUSPICIOUS_NAME.test(name) && !name.startsWith("@types/") && !name.startsWith("@babel/")) {
+          push("LOW", "generic-name", `${pkgPath}#${name}`, "Generic suffix name; confirm identity");
+        }
+      }
+      if (pkg.scripts && (pkg.scripts.preinstall || pkg.scripts.install || pkg.scripts.postinstall)) {
+        push("MED", "install-script", pkgPath, "Install lifecycle scripts present; review what they run");
+      }
+    }
+  }
+
+  if (lock) {
+    try {
+      const text = readFileSync(join(dir, lock), "utf8");
+      if (lock.endsWith(".json")) {
+        const data = JSON.parse(text);
+        const packages = data.packages || data.dependencies || {};
+        const count = Object.keys(packages).length;
+        if (count > 400) {
+          push("MED", "large-graph", join(dir, lock), `Lockfile lists ${count} package entries`);
+        }
+      }
+    } catch {
+      push("MED", "lock-parse", join(dir, lock), "Lockfile unreadable as JSON");
+    }
+  }
+
+  return findings;
+}
+
+const roots = process.argv.slice(2);
+if (roots.length === 0) {
+  console.error("usage: node scripts/dep_risk_lint.mjs <project-dir> [...]");
+  process.exit(2);
+}
+
+const projects = roots.flatMap((r) => walkProjects(r));
+const all = projects.flatMap(checkProject);
+const byLevel = { HIGH: [], MED: [], LOW: [] };
+for (const f of all) byLevel[f.level].push(f);
+
+for (const level of ["HIGH", "MED", "LOW"]) {
+  for (const f of byLevel[level]) {
+    console.log(`${level}\t${f.id}\t${f.file}\t${f.msg}`);
+  }
+}
+
+const high = byLevel.HIGH.length;
+console.error(`dep_risk_lint: ${projects.length} projects, ${all.length} findings (${high} HIGH)`);
+process.exit(high > 0 ? 1 : 0);

package/skills/secrets-hygiene/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: "secrets-hygiene"
+description: "Secret hygiene for repos and environments: detection gates (pre-commit, CI, history), rotate-first incident response, secret manager patterns, env var rules, inventory and rotation policy. Use when auditing .env and git history for leaked credentials, planning a rotation, responding to a leak, or standing up scanning."
+license: "Apache-2.0"
+metadata:
+  author: Novahiz
+  organization: Novahiz
+  version: "1.0.0"
+  date: September 2026
+---
+
+# secrets-hygiene
+
+Credentials that reach git are compromised. Deletion and force-push clean history; only rotation kills the credential. This skill covers detection, response order, and the steady-state setup that keeps new leaks from shipping.
+
+## Detection gates
+
+| Gate | Where | Tool shape | Limits |
+|---|---|---|---|
+| Pre-commit | Developer machine | gitleaks / git-secrets hook on the diff | `--no-verify` bypass; hook must be installed |
+| CI | PR and default branch | gitleaks detect, TruffleHog, platform secret scanning | Misses secrets only in old history |
+| History | Full repo, periodic | `gitleaks git`, TruffleHog history mode | Slow on large repos; needs triage |
+
+Enable all three. Tune false positives weekly until the team stops disabling hooks; a noisy scanner gets switched off.
+
+## When a secret lands in git
+
+Order is fixed. Do not start with history surgery.
+
+1. **Identify** the credential type, scope, and where it is used.
+2. **Rotate or revoke** at the provider. The old value must stop working before anything else.
+3. **Update** every consumer (deploy env, secret store, local `.env` that is not committed).
+4. **Purge history** with `git filter-repo` (or BFG), force-push, coordinate re-clones and fork deletion.
+5. **Verify**: full-history scan clean; only the new credential authenticates; provider audit log reviewed for use of the old key.
+
+Public remote or CI logs: assume the scrapers already have it. Rotate first, always.
+
+## Steady state
+
+- Never commit `.env`, key files, or PEM blocks. `.env.example` holds names only.
+- Load secrets at runtime from the platform secret manager or injected env; never hardcode in source or tests.
+- Short TTL where the provider supports it; prefer workload identity over long-lived static keys.
+- Inventory: every credential has type, owner, rotation policy, and where it lives. You cannot rotate what you do not know.
+- Metric: time from detect to confirmed rotation (target under a few hours for production).
+
+## Redaction in logs
+
+Log auth events without the secret itself. Truncate tokens in error pages. Scrub request/response bodies in support tooling.
+
+## Checklist
+
+- [ ] Pre-commit scanner installed and required (or CI enforces equivalent).
+- [ ] CI scan on every PR and on schedule against default branch.
+- [ ] Full-history scan run once at adoption; baseline file for old accepted findings if needed.
+- [ ] `.env` gitignored; example file has placeholders.
+- [ ] No live credentials in fixtures or snapshots.
+- [ ] Rotation runbook names the person and the console for each credential class.
+- [ ] Post-incident: revoke confirmed, history purged, scan green.
+
+## Sources
+
+Gitleaks and TruffleHog project docs; AWS git-secrets patterns; OWASP and industry guidance that history rewrite is cleanup while rotation is containment. Original Novahiz synthesis; no upstream skill text.

package/skills/secrets-hygiene/references/rotation-playbook.md

@@ -0,0 +1,27 @@
+# Rotation playbook
+
+## Trigger
+
+Secret found in commit, PR, log, ticket, or provider alert.
+
+## Steps
+
+1. Classify: provider, scope (read/write, prod/dev), age, who has clone access.
+2. Rotate at provider immediately. Confirm old value rejected.
+3. Push new value to secret store / deploy config. Redeploy if cached.
+4. Purge git history (`git filter-repo --replace-text`), force-push, ask collaborators to re-clone, delete stale forks.
+5. Rescan full history; confirm zero findings for that secret fingerprint.
+6. Review provider audit log for unexpected use of the old key.
+7. File incident note: detection source, time-to-rotate, gaps (missing gate, shared key, no inventory).
+
+## Owners
+
+| Credential class | Rotate by | Console / runbook |
+|---|---|---|
+| Cloud access keys | | |
+| Deploy tokens | | |
+| DB passwords | | |
+| API third-party | | |
+| TLS / signing | | |
+
+Fill before the first real incident, not during it.