@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/housekeep-files/scripts/housekeep-files.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+#
+# FILE: housekeep-files.sh
+# PURPOSE: Copy-not-move document organizer with a hash inventory, dry run,
+#          labeled copies, a JSONL catalog, and a verify gate. macOS/Linux twin
+#          of housekeep-files.ps1 (same plan.tsv, same outputs).
+#
+# OVERVIEW:
+# - inventory : sha256 + size of every source file -> work/inventory.csv;
+#               file counts of count-only folders -> work/count-only.csv
+# - dry-run   : work/preview.tsv with the action per file; no disk change
+# - apply     : cp only when the destination is absent, hash the copy, append
+#               _ai-catalog.jsonl at each catalog_root and work/catalog.jsonl,
+#               write apply-log.tsv. Never deletes.
+# - verify    : every inventory path exists at the same size, every copy
+#               re-hashes equal, every in-place file exists, count-only counts
+#               unchanged. Exit 1 on the first failure. -> work/verify-report.txt
+#
+# DEPENDENCIES: bash 3.2+, find, cp, stat, and shasum or sha256sum.
+#
+# USAGE:
+#   housekeep-files.sh inventory plan.tsv work count-only.txt
+#   housekeep-files.sh dry-run   plan.tsv work
+#   housekeep-files.sh apply     plan.tsv work
+#   housekeep-files.sh verify    plan.tsv work count-only.txt
+#   MAX_MB=200 MAX_PATH=200 override the caps.
+#
+# NOTES:
+# - No rm, mv, or rsync --delete anywhere in this file by design.
+# - plan.tsv is tab-separated so paths may contain commas, spaces, and CJK.
+# - Optional 10th column `exclude`: ';'-separated relative-path substrings cataloged in
+#   place instead of copied (code checkouts, caches). node_modules/.git/__pycache__/
+#   .venv/.next/.cache are always skipped.
+#
+set -u
+MODE="${1:-}"; PLAN="${2:-}"; OUT="${3:-}"; COUNT_ONLY="${4:-}"
+MAX_MB="${MAX_MB:-200}"; MAX_PATH="${MAX_PATH:-200}"
+[ -n "$MODE" ] && [ -n "$PLAN" ] && [ -n "$OUT" ] || { echo "usage: $0 inventory|dry-run|apply|verify plan.tsv work [count-only.txt]" >&2; exit 64; }
+case "$MODE" in inventory|dry-run|apply|verify) ;; *) echo "unknown mode $MODE" >&2; exit 64;; esac
+
+mkdir -p "$OUT"
+INV="$OUT/inventory.csv"; CNT="$OUT/count-only.csv"; PREVIEW="$OUT/preview.tsv"
+CATALOG="$OUT/catalog.jsonl"; APPLYLOG="$OUT/apply-log.tsv"; VERIFY="$OUT/verify-report.txt"
+RUN="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+DOC_EXT=" pdf doc docx xls xlsx xlsm ppt pptx csv txt md html htm xtx xml data zip jpg jpeg png heic svg gif webp rtf odt ods eml msg "
+ARTIFACT_RE='/(node_modules|\.git|__pycache__|\.venv|\.next|\.cache)/'
+SECRET_RE='credential|keystore|\.p8$|\.p12$|\.pem$|\.key$|\.jks$|mobileprovision|\.cer$|\.der$|certsigningrequest|\.b64$|service-account|client_secret|google-services\.json|googleservice-info|oauth|private-key|backup_code|\.env$|play-publisher|apple-credentials|env-backups|recovery|2fa|mfa|totp|アクセスキー'
+
+if command -v sha256sum >/dev/null 2>&1; then sha() { sha256sum "$1" | awk '{print $1}'; }
+elif command -v shasum >/dev/null 2>&1; then sha() { shasum -a 256 "$1" | awk '{print $1}'; }
+else echo "need sha256sum or shasum" >&2; exit 69; fi
+if stat -f%z / >/dev/null 2>&1; then fsize() { stat -f%z "$1"; }; else fsize() { stat -c%s "$1"; }; fi
+lower() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
+json_esc() { printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/\t/\\t/g'; }
+count_files() { [ -d "$1" ] || { echo -1; return; }; find "$1" -type f ! -name desktop.ini ! -name .DS_Store ! -name Thumbs.db | wc -l | tr -d ' '; }
+
+date_token() {  # $1 name, $2 parent name
+  local c y m d
+  for c in "$1" "$2"; do
+    [ -n "$c" ] || continue
+    if [[ "$c" =~ (20[0-9]{2})[-_.]?([0-9]{2})[-_.]?([0-9]{2}) ]]; then
+      y="${BASH_REMATCH[1]}"; m="${BASH_REMATCH[2]}"; d="${BASH_REMATCH[3]}"
+      if [ "$m" -ge 1 ] && [ "$m" -le 12 ] && [ "$d" -ge 1 ] && [ "$d" -le 31 ]; then echo "$y-$m-$d"; return; fi
+    fi
+    if [[ "$c" =~ (20[0-9]{2})[-_]?([0-9]{2}) ]]; then
+      y="${BASH_REMATCH[1]}"; m="${BASH_REMATCH[2]}"
+      if [ "$m" -ge 1 ] && [ "$m" -le 12 ]; then echo "$y-$m"; return; fi
+    fi
+  done
+  echo undated
+}
+
+# Expand plan into per-file item lines:
+# action|reason|source|destDir|newName|entity|area|project|doc_type|date|tags|catalog_root|bytes joined by \037 (unit separator).
+# Tab is whitespace to read(1) and collapses empty columns, so plan.tsv is re-separated with \037 first.
+expand_plan() {
+  local header=1 source destination entity area project doc_type tags prefix catalog_root
+  while IFS=$'\037' read -r source destination entity area project doc_type tags prefix catalog_root exclude _rest; do
+    if [ $header -eq 1 ]; then header=0; continue; fi
+    [ -n "$source" ] || continue
+    case "$source" in \#*) continue;; esac
+    if [ ! -e "$source" ]; then echo "plan source missing, skipped: $source" >&2; continue; fi
+    local files
+    if [ -d "$source" ]; then files=$(find "$source" -type f); else files="$source"; fi
+    while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      local name rel destDir relDir lp ext action reason bytes date newName cand
+      name="$(basename "$f")"
+      # OS / sync-client metadata files are recreated and removed by the client itself; never inventory them.
+      case "$name" in desktop.ini|.DS_Store|Thumbs.db) continue;; esac
+      if [ -d "$source" ]; then rel="${f#"$source"/}"; else rel="$name"; fi
+      destDir="$destination"; relDir="$(dirname "$rel")"
+      [ "$relDir" != "." ] && destDir="$destination/$relDir"
+      lp="$(lower "$f")"; ext="$(lower "${name##*.}")"; [ "$ext" = "$(lower "$name")" ] && ext=""
+      bytes="$(fsize "$f")"
+      action=copy; reason=""
+      local excluded=0 pat lrel; lrel="$(lower "$rel")"
+      IFS=';' read -ra _ex <<< "${exclude:-}"
+      for pat in "${_ex[@]}"; do pat="$(lower "$(printf '%s' "$pat" | sed 's/^ *//;s/ *$//')")"; [ -n "$pat" ] && [[ "$lrel" == *"$pat"* ]] && excluded=1; done
+      if printf '%s' "$lp" | grep -Eq "$SECRET_RE"; then action=indexed-in-place; reason=secret
+      elif [ $excluded -eq 1 ]; then action=indexed-in-place; reason=excluded
+      elif printf '%s' "$lp" | grep -Eq "$ARTIFACT_RE"; then action=indexed-in-place; reason=artifact
+      elif [[ "$DOC_EXT" != *" $ext "* ]]; then action=indexed-in-place; reason=ext
+      elif [ "$bytes" -gt $((MAX_MB * 1024 * 1024)) ]; then action=indexed-in-place; reason=size; fi
+      # Parent-folder date only inside a folder row; a loose file's parent is the old root.
+      local parentForDate=""
+      if [ -d "$source" ] && [ "$(dirname "$f")" != "$source" ]; then parentForDate="$(basename "$(dirname "$f")")"; fi
+      date="$(date_token "$name" "$parentForDate")"
+      newName="$name"
+      if [ "$action" = copy ] && [ "$prefix" = yes ]; then
+        if ! [[ "$name" =~ ^(20[0-9]{6}|20[0-9]{2}-[0-9]{2}|20[0-9]{2}_) ]] && [[ "$name" != "${entity}_"* ]]; then
+          cand="${entity}_${area}_${date}_${doc_type}__${name}"
+          [ ${#destDir} -le $((MAX_PATH - ${#cand} - 1)) ] && newName="$cand"
+        fi
+      fi
+      printf '%s\037%s\037%s\037%s\037%s\037%s\037%s\037%s\037%s\037%s\037%s\037%s\037%s\n' \
+        "$action" "$reason" "$f" "$destDir" "$newName" "$entity" "$area" "$project" "$doc_type" "$date" "$tags" "$catalog_root" "$bytes"
+    done <<< "$files"
+  done < <(tr -d '\r' < "$PLAN" | tr '\t' '\037')
+}
+
+catalog_line() { # args: entity area project doc_type date tags source name canonical bytes sha persist reason
+  local t tags_json="" first=1
+  IFS=',' read -ra _tags <<< "$6"
+  for t in "${_tags[@]}"; do t="$(printf '%s' "$t" | sed 's/^ *//;s/ *$//')"; [ -n "$t" ] || continue
+    [ $first -eq 1 ] || tags_json+=","; first=0; tags_json+="\"$(json_esc "$t")\""; done
+  printf '{"run":"%s","entity":"%s","area":"%s","project":"%s","doc_type":"%s","date":"%s","tags":[%s],"original_path":"%s","original_name":"%s","canonical_path":"%s","bytes":%s,"sha256":"%s","persist":"%s","reason":"%s"}\n' \
+    "$RUN" "$(json_esc "$1")" "$(json_esc "$2")" "$(json_esc "$3")" "$(json_esc "$4")" "$5" "$tags_json" \
+    "$(json_esc "$7")" "$(json_esc "$8")" "$(json_esc "$9")" "${10}" "${11}" "${12}" "$(json_esc "${13}")"
+}
+
+read_count_only() { [ -n "$COUNT_ONLY" ] && [ -f "$COUNT_ONLY" ] && grep -v '^[[:space:]]*#' "$COUNT_ONLY" | grep -v '^[[:space:]]*$' || true; }
+
+case "$MODE" in
+inventory)
+  echo "path,bytes,sha256" > "$INV"; n=0
+  while IFS=$'\037' read -r action reason src destDir newName entity area project doc_type date tags croot bytes; do
+    n=$((n+1)); [ $((n % 50)) -eq 0 ] && echo "hashing $n"
+    # Hash only what will be copied; in-place items are size-checked so a streaming drive is not forced to download them.
+    h=""; [ "$action" = copy ] && h="$(sha "$src")"
+    printf '"%s",%s,%s\n' "${src//\"/\"\"}" "$bytes" "$h" >> "$INV"
+  done < <(expand_plan)
+  echo "folder,files" > "$CNT"
+  while IFS= read -r folder; do printf '"%s",%s\n' "${folder//\"/\"\"}" "$(count_files "$folder")" >> "$CNT"; done < <(read_count_only)
+  echo "inventory: $n files -> $INV; count-only -> $CNT"
+  ;;
+dry-run)
+  printf 'action\treason\tsource\tdestination\tnew_name\tentity\tarea\tproject\tdoc_type\tdate\ttags\n' > "$PREVIEW"
+  while IFS=$'\037' read -r action reason src destDir newName entity area project doc_type date tags croot bytes; do
+    [ "$action" = copy ] && [ -e "$destDir/$newName" ] && action=skipped-exists
+    printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$action" "$reason" "$src" "$destDir" "$newName" "$entity" "$area" "$project" "$doc_type" "$date" "$tags" >> "$PREVIEW"
+  done < <(expand_plan)
+  echo "preview -> $PREVIEW"; tail -n +2 "$PREVIEW" | awk -F'\t' '{k=$1; if($2!="")k=k":"$2; c[k]++} END{for(k in c) printf "  %-24s %d\n",k,c[k]}'
+  ;;
+apply)
+  [ -f "$INV" ] || { echo "inventory.csv missing under $OUT — run inventory first" >&2; exit 65; }
+  printf 'action\tsource\tcanonical\tbytes\tsha256\n' > "$APPLYLOG"
+  copied=0 skipped=0 inplace=0 failed=0 copiedBytes=0 n=0
+  while IFS=$'\037' read -r action reason src destDir newName entity area project doc_type date tags croot bytes; do
+    n=$((n+1)); [ $((n % 50)) -eq 0 ] && echo "apply $n"
+    esc="${src//\"/\"\"}"
+    inv_line="$(grep -F -- "\"$esc\",$bytes," "$INV" | head -1)"
+    [ -n "$inv_line" ] || { echo "source not in inventory (plan changed after inventory?): $src" >&2; exit 65; }
+    sha_src="${inv_line##*,}"   # empty for in-place items, which are never hashed
+    canonical="$destDir/$newName"; persist=""
+    if [ "$action" = indexed-in-place ]; then persist=indexed-in-place; canonical="$src"; inplace=$((inplace+1))
+    elif [ -e "$canonical" ]; then persist=skipped-exists; skipped=$((skipped+1))
+    else
+      mkdir -p "$destDir"
+      if cp -p "$src" "$canonical" 2>/dev/null && [ "$(sha "$canonical")" = "$sha_src" ]; then
+        persist=copied-source-kept; copied=$((copied+1)); copiedBytes=$((copiedBytes+bytes))
+      else persist=failed; reason=copy-or-hash-error; failed=$((failed+1)); fi
+    fi
+    printf '%s\t%s\t%s\t%s\t%s\n' "$persist" "$src" "$canonical" "$bytes" "$sha_src" >> "$APPLYLOG"
+    line="$(catalog_line "$entity" "$area" "$project" "$doc_type" "$date" "$tags" "$src" "$(basename "$src")" "$canonical" "$bytes" "$sha_src" "$persist" "$reason")"
+    printf '%s\n' "$line" >> "$CATALOG"
+    if [ -n "$croot" ]; then
+      mkdir -p "$croot"; printf '%s\n' "$line" >> "$croot/_ai-catalog.jsonl"
+      if [ ! -f "$croot/_SEARCH.md" ]; then cat > "$croot/_SEARCH.md" <<'EOF'
+# _SEARCH.md — how to find a file here
+
+1. grep `_ai-catalog.jsonl` in this folder: tags, entity, area, doc_type, date, original_name.
+2. Search the prefixed filename: `{entity}_{area}_{date}_{doc_type}__{original name}`.
+3. Search the original name after `__`; it is unchanged.
+
+persist values: copied-source-kept (original still at original_path), indexed-in-place (only copy is at original_path), skipped-exists, failed.
+Keys, credentials, videos, and installers are never copied here; the catalog points to where they already live.
+EOF
+      fi
+    fi
+  done < <(expand_plan)
+  echo "apply done: copied=$copied skipped-exists=$skipped indexed-in-place=$inplace failed=$failed copiedMB=$((copiedBytes / 1048576))"
+  echo "log -> $APPLYLOG"; echo "catalog -> $CATALOG"
+  [ "$failed" -eq 0 ] || exit 2
+  ;;
+verify)
+  [ -f "$INV" ] || { echo "inventory.csv missing under $OUT" >&2; exit 65; }
+  : > "$VERIFY"; fail=0; checked=0; copies=0; inplace=0
+  echo "verify run $RUN" >> "$VERIFY"
+  while IFS= read -r row; do
+    p="$(printf '%s' "$row" | sed -E 's/^"(.*)",[0-9]+,[0-9a-f]*$/\1/' | sed 's/""/"/g')"
+    b="$(printf '%s' "$row" | sed -E 's/^".*",([0-9]+),[0-9a-f]*$/\1/')"
+    checked=$((checked+1))
+    if [ ! -e "$p" ]; then fail=$((fail+1)); echo "MISSING source: $p" >> "$VERIFY"
+    elif [ "$(fsize "$p")" != "$b" ]; then fail=$((fail+1)); echo "RESIZED source: $p" >> "$VERIFY"; fi
+  done < <(tail -n +2 "$INV")
+  echo "sources checked: $checked" >> "$VERIFY"
+  if [ -f "$CATALOG" ]; then
+    while IFS= read -r line; do
+      persist="$(printf '%s' "$line" | sed -E 's/.*"persist":"([^"]*)".*/\1/')"
+      if [ "$persist" = copied-source-kept ]; then
+        copies=$((copies+1))
+        c="$(printf '%s' "$line" | sed -E 's/.*"canonical_path":"((\\"|[^"])*)".*/\1/' | sed 's/\\"/"/g;s/\\\\/\\/g')"
+        h="$(printf '%s' "$line" | sed -E 's/.*"sha256":"([^"]*)".*/\1/')"
+        if [ ! -e "$c" ]; then fail=$((fail+1)); echo "MISSING copy: $c" >> "$VERIFY"
+        elif [ "$(sha "$c")" != "$h" ]; then fail=$((fail+1)); echo "HASH MISMATCH copy: $c" >> "$VERIFY"; fi
+      elif [ "$persist" = indexed-in-place ]; then
+        inplace=$((inplace+1))
+        o="$(printf '%s' "$line" | sed -E 's/.*"original_path":"((\\"|[^"])*)".*/\1/' | sed 's/\\"/"/g;s/\\\\/\\/g')"
+        [ -e "$o" ] || { fail=$((fail+1)); echo "MISSING in-place: $o" >> "$VERIFY"; }
+      fi
+    done < "$CATALOG"
+  fi
+  echo "copies re-hashed: $copies" >> "$VERIFY"; echo "in-place files present-checked: $inplace" >> "$VERIFY"
+  if [ -f "$CNT" ]; then cc=0
+    while IFS= read -r row; do
+      folder="$(printf '%s' "$row" | sed -E 's/^"(.*)",-?[0-9]+$/\1/' | sed 's/""/"/g')"
+      was="$(printf '%s' "$row" | sed -E 's/^".*",(-?[0-9]+)$/\1/')"
+      cc=$((cc+1)); now="$(count_files "$folder")"
+      [ "$now" = "$was" ] || { fail=$((fail+1)); echo "COUNT CHANGED: $folder $was -> $now" >> "$VERIFY"; }
+    done < <(tail -n +2 "$CNT")
+    echo "count-only folders rechecked: $cc" >> "$VERIFY"
+  fi
+  echo "failures: $fail" >> "$VERIFY"
+  if [ "$fail" -eq 0 ]; then echo "RESULT: PASS - every source present, every copy hash-equal, media counts unchanged" >> "$VERIFY"; else echo "RESULT: FAIL" >> "$VERIFY"; fi
+  cat "$VERIFY"; [ "$fail" -eq 0 ] || exit 1
+  ;;
+esac

package/skills/housekeep-gates/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: housekeep-gates
+description: >
+  Consolidate accreted CI gates, ratchets, and hooks into one required
+  aggregator check. Use after audit-gate-logic, or when "clean up our CI
+  checks", "we have three lint jobs", or "make one quality gate". Pipeline
+  cost → audit-cicd.
+license: MIT
+effort: high
+---
+
+# housekeep-gates — One required check, defined in code
+
+**Degree of freedom: MIXED — T1 is the priority.** Mapping and winner
+confirmation `[HIGH freedom]`; aggregator `needs:` + skip-fail, loser
+**deletion**, branch-protection, and Phase 4 probes `[LOW freedom — run
+exactly]`. **Net enforcement strictly ≥ before.**
+
+Apply-now. `audit-gate-logic` mapped the sprawl and named a winner per
+duplicate cluster; this makes the repo match the map. **Target state: one
+required check in branch protection, backed by an aggregator job that
+`needs:` every real gate — so "what blocks merge" has exactly one answer,
+in one file.**
+
+Every retirement is proven safe before deletion. Never weaken enforcement
+while consolidating. **Net enforcement strictly ≥ before.**
+
+This is the execution arm of `audit-gate-logic`, the same way
+`housekeep-design` executes `plan-uiux-unification`.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **housekeep-gates** (this) | Consolidate / delete / wire the aggregator |
+| `audit-gate-logic` | Read-only map — bypass, ratchets, archaeology |
+| `audit-cicd` | Pipeline cost, speed, storage |
+| `workflow-quality-gate` | *Runs* the pre-release sweep |
+| `enhance-agent-guardrails` | *Installs* new guard classes, not accreted-gate cleanup |
+| `workflow-green-repo` | Make the repo green — does not redesign the gate graph |
+| `housekeep-backlog` | Parked-work register — not CI gates |
+| `housekeep-dead-code` | Owns the dead-code `--max-issues` ratchet that joins this aggregator |
+
+## How to reason
+
+1. **Observe** — archaeology map: cluster, winner, loser, current required checks
+2. **Interpret** — would deleting this loser drop unique coverage?
+3. **Classify** — port-then-delete / keep / not-yet-mapped
+4. **Severity** — deleting the only server-side-enforced gate is a regression
+
+## Worked example
+
+> **Observe:** two lint jobs; old `lint.yml` is required; new `ci.yml` lint
+> is not. `paths:` skips `.github/**`.
+> **Interpret:** retiring `lint.yml` without porting + aggregator skip-fail
+> would let a workflow edit merge unlinted.
+> **Classify:** port unique rules, wire winner, delete loser; probe the skip path.
+> **Probe:** change matching the old skip filter → aggregator must go red, not skip-green.
+
+---
+
+## Phase 0 — Load the map (or make a quick one)  [HIGH freedom; confirm before edits]
+
+Consume the archaeology map from `audit-gate-logic` (duplicate clusters,
+winners, losers, ratchet findings). If none exists, run its Phase 0 + 2.5
+first — never consolidate gates you have not mapped. Deleting an "obvious
+duplicate" that was the only server-side-enforced one *weakens* the repo.
+
+Confirm which winners stand **before touching anything**. Branch-protection
+changes always get explicit confirmation.
+
+---
+
+## Phase 1 — Build the aggregator gate  [LOW freedom — fail on failed or skipped]
+
+Create (or adopt) the single-gate structure:
+
+- One job — conventionally `gate` / `all-green` — that `needs:` every real
+  check (lint, typecheck, tests, build, and the audit jobs worth blocking
+  on) and fails if any dependency failed **or was skipped** (`if: always()`
+  + explicit result check). Skipped-counts-as-success is the classic
+  aggregator bug.
+- Make that job the **only** required status check; remove scattered
+  required entries. Enforcement moves from a settings list nobody audits
+  to a `needs:` list that lives in code review.
+- If a merge queue is (or will be) in use: add `merge_group` to the
+  workflow triggers and keep check names identical across `pull_request`
+  and `merge_group`, or queued PRs wait on checks that never start.
+- Keep one fast always-runs job as the visible status link if the
+  aggregator's `needs:` delays its appearance.
+
+---
+
+## Phase 2 — Consolidate per the map  [LOW freedom — delete losers, do not disable]
+
+For each duplicate cluster, in this order:
+
+1. **Port unique value** from losers into the winner (a lint rule only the
+   old config had, a test only the old workflow ran). Diff configs before
+   deleting — retirement must not drop coverage.
+2. **Wire the winner** into the aggregator's `needs:`.
+3. **Retire the losers** — delete the workflow/config, do not
+   disable-and-keep. A disabled gate is comprehension debt and resurrection
+   bait for the next agent session.
+4. **Extract shared logic** into a reusable workflow or composite action
+   when the same steps exist in 2+ places.
+
+Also restore **hook/CI parity**: local pre-commit / pre-push hooks run the
+same commands (ideally the same scripts) as CI's gate jobs — one
+definition, two callers — so "passes locally" predicts "passes CI" and
+nobody learns `--no-verify`.
+
+---
+
+## Phase 3 — Normalize the ratchets  [HIGH freedom]
+
+- **One baseline per metric.** Competing thresholds (jest + codecov + a
+  committed floor) collapse to one enforcement point; the rest read from
+  it or die.
+- **Auto-tighten upward.** Floors track reality (threshold rises as the
+  metric improves, small flake tolerance) instead of sitting far below
+  actual.
+- **Resets are reviewed, separate acts.** Baseline regeneration happens in
+  its own PR with the diff visible. CI should fail if a baseline file
+  changes in the same PR as a metric regression, where the tooling allows
+  expressing that.
+- **No silent exemption growth.** Ignore-lists and inline-disable counts
+  become ratcheted metrics themselves where feasible.
+
+---
+
+## Phase 4 — Prove it  [LOW freedom — run both probes]
+
+- **Deliberate-violation probe** on a scratch branch: one violation per
+  consolidated gate class (lint error, failing test, coverage drop,
+  baseline edit bundled with a regression). Confirm the aggregator goes
+  red and the PR is unmergeable. A consolidation is not done until each
+  retired loser's job is demonstrably covered by the winner.
+- **Skip-path probe:** push a change matching any `paths:` filter that
+  previously skipped gates; confirm the aggregator still reports
+  (skipped-as-success is the failure mode to disprove).
+- Run a `workflow-green-repo`-style full pass to confirm the repo is green
+  under the new single gate.
+
+---
+
+## Definition of Done
+
+- [ ] Archaeology map confirmed with the user before edits
+- [ ] Aggregator job exists, fails on any failed **or skipped** dependency, and is the only required check
+- [ ] `merge_group` parity in place if a merge queue is used
+- [ ] Every cluster: unique value ported, winner wired, losers deleted (not disabled)
+- [ ] Shared steps extracted to one reusable definition; hooks and CI call the same commands
+- [ ] One baseline per metric; ratchets auto-tighten; resets require a separate reviewed PR; exemption lists cannot silently grow
+- [ ] Deliberate-violation + skip-path probes red as expected; repo green under the new gate
+- [ ] Net enforcement strictly ≥ before
+
+## Self-critique before claiming done  [LOW freedom — do not skip]
+
+1. **Map confirmed** — no "obvious duplicate" deleted unmapped
+2. **Skipped ≠ success** — aggregator checks dependency results
+3. **Losers deleted** — not disabled
+4. **Probes red** — violation + skip-path
+5. **Branch protection** — only after explicit confirmation
+
+## Output format
+
+1. **Before/after map** — old gates → new structure (aggregator + needs list)
+2. **Per-cluster log** — winner | value ported from losers | losers deleted
+3. **Ratchet policy** — metric | enforcement point | floor behavior | reset rule
+4. **Probe evidence** — violation | gate response | pass/fail
+
+Applied phase-by-phase. Pause for approval between phases when blast
+radius is large. Branch-protection changes always get explicit confirmation.

package/skills/iterate-agent-harness/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: iterate-agent-harness
+description: >
+  Turn an agent failure (premature stop, false completion, gamed check, missed
+  file) into a rule, hook, or CI guard with a regression test. Use when "the
+  agent stopped early again", "it gamed the test", or "add a guard so this
+  doesn't recur".
+license: MIT
+effort: high
+---
+
+# iterate-agent-harness — Failure → Durable Guard
+
+**Degree of freedom: MIXED.** Failure-class and smallest fix `[HIGH freedom]`;
+guard-fails-before-fix and the report shape `[LOW freedom — run exactly]`.
+
+When an agent run ends wrong, the fix is not just to redo the task — it is to
+change the harness so the whole class of failure cannot recur silently. This
+skill converts a single failure into a durable guard plus a regression check.
+
+> **A failure you cannot reproduce, you cannot prove you fixed.** Capture the
+> failure mode, add a guard that fails on it, then make the guard pass with the
+> smallest durable change.
+
+## How to reason
+
+1. **Observe** — happened vs should-have; transcript, state file, diff, CI
+2. **Interpret** — routing miss, missing guard, or a gate that passed wrongly
+3. **Classify** — premature stop / false completion / reward hacking / scope / handoff / context loss
+4. **Guard** — add a guard that fails on the unfixed behavior, then the smallest durable fix
+
+## Worked example
+
+> **Observe:** agent said complete-everything was done; `.cursor/complete-everything-state.md` still has 12 unchecked items.
+> **Interpret:** false completion — no harness stopped the claim.
+> **Classify:** false completion; gap is an unwired or skippable completion gate.
+> **Fix:** add a hook test that fails while unchecked items remain; confirm it fails on this tree; then wire the hook. Do not delete the open items to go green.
+
+## Self-critique before reporting
+
+- **Fail-then-pass** — the new guard failed on the unfixed tree
+- **Class, not incident** — the same failure mode would now be caught
+- **Guard not weakened** — passing did not mean deleting or narrowing the check
+- **Right owner** — app bug → `workflow-fix-and-ship`; new SKILL.md from scratch → `meta-skill-creator`
+
+## Phase 0 — Capture the failure precisely  [HIGH freedom]
+
+1. State what happened vs. what should have happened, in one sentence each.
+2. Classify the failure mode (borrow the taxonomy the toolkit already targets):
+   - **premature stop** — quit with actionable work remaining. Shapes to guard: ends the turn with a plan or status report instead of the work; asks a question the repo could answer; stops after a subagent returns without integrating its result; wraps up early believing context is running out (compaction exists — it should not)
+   - **false completion** — claimed done without evidence, including fabricated progress: a "ran", "checked", or "verified" with no matching tool result in the transcript
+   - **reward hacking** — satisfied the check, not the intent (skipped test,
+     narrowed assertion, `@ts-ignore`, blanket snapshot update)
+   - **scope boundary error** — treated the plan/visible list as the full scope
+   - **broken handoff** — a skill/command/subagent pointed at a missing or
+     wrong target, or a phase transition dropped work
+   - **context loss** — forgot earlier state after compaction
+3. Pull evidence from the agent transcript, `.cursor/*-state.md` files,
+   `git diff`, and CI logs. Link the concrete artifacts.
+
+## Phase 1 — Locate the harness gap  [HIGH freedom]
+
+Find where the harness *should* have caught it:
+
+- Was there a skill/rule that covered this, and it was not followed or not
+  triggered? → the description/routing or wording is the gap.
+- Was there no guard at all? → a new rule, hook, subagent check, or
+  verification script is warranted.
+- Did an enforcement gate exist but pass anyway (like a count check with
+  incomplete coverage)? → the gate's coverage is the gap.
+
+Name the single smallest change that closes the class, not just this instance.
+Prefer strengthening an existing skill/rule/hook over adding a new one; only
+add a new component when no existing one owns the concern.
+
+## Phase 2 — Add a regression guard first  [LOW freedom — fail before fix]
+
+Before fixing, add something that fails on the captured failure:
+
+- an executable check (a script under `scripts/`, a hook test like
+  `scripts/test-completion-gate.mjs`, a validation rule) — preferred; or
+- a documented, repeatable scenario with an explicit expected outcome when the
+  failure is judgment-based and not mechanically checkable.
+
+For premature-stop and false-completion classes, two guards are mechanical: (1) transcript audit — every claimed action maps to a tool result; (2) turn-ending check — the last paragraph of a turn lists done vs owed, and an owed item with no named blocker means the turn should not have ended. Encode those as the guard rather than a wording tweak.
+
+Confirm the guard actually fails against the current (unfixed) behavior — a
+guard that passes before the fix proves nothing.
+
+## Phase 3 — Make the smallest durable fix  [HIGH freedom]
+
+Apply the minimal change that makes the guard pass by satisfying intent:
+
+- tighten a skill/rule's wording or trigger; resolve a policy conflict;
+- fix or add a hook / subagent / verification script;
+- repair a broken skill/command/subagent reference or handoff.
+
+Do not weaken the guard to pass, and do not delete working behavior. Keep the
+public behavior of unrelated skills unchanged.
+
+## Phase 4 — Validate and record the lesson  [LOW freedom — do not skip]
+
+1. Re-run the guard: it now passes for the right reason. Run the repo's full
+   check suite (`npm test` or equivalent) so the new guard is wired in.
+2. Record a concise lesson: the failure mode, the trigger, the guard, and the
+   fix — in `CHANGELOG.md` and/or a durable lessons note, so the same mistake
+   surfaces a reference next time.
+3. If the failure recurred despite an existing guard, note why the guard was
+   insufficient and strengthen it rather than duplicating it.
+
+## Phase 5 — Report  [LOW freedom — this shape]
+
+```md
+## Harness Iteration — <date>
+Failure mode: <class> — <one-sentence description>
+Root gap: <missing/weak guard or conflicting rule>
+Guard added: <script/test/rule> — failed before, passes after
+Durable fix: <smallest change>
+Validation: <check suite> → green
+Lesson recorded: <where>
+```
+
+## Guardrails
+
+- Improve the harness for the **class**, not just the one incident.
+- A new guard must fail before the fix and pass after — never the reverse.
+- Never satisfy a guard by weakening it; that repeats the reward-hacking
+  failure this skill exists to prevent.
+- Prefer editing an existing skill/rule/hook to adding a new one.
+
+## Related
+
+- `verification-before-completion` — the evidence discipline guards enforce
+- `completion-judge` — independent verdict that catches false completion
+- `complete-everything` / `burndown-full` — the closure loops guards protect
+- `create-skill` / `create-rule` / `create-hook` — build the new guard
+- `meta-skill-creator` — author or refine a skill correctly

package/skills/iterate-gtm-weekly/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: iterate-gtm-weekly
+description: >
+  Weekly go-to-market review for a shipped product: funnel by source,
+  activation cohort, top drop-off, launch results, then one experiment and one
+  post, scorecard row appended. Use when "weekly growth review", "what should
+  we do this week for growth", "GTM check-in". Production bugs →
+  iterate-post-launch.
+license: MIT
+disable-model-invocation: true
+---
+
+# iterate-gtm-weekly — One number, one fix, one post
+
+**Degree of freedom: MIXED.** Which lever to pull `[HIGH freedom]`; the
+five-line review, the single-experiment rule, and the scorecard update
+`[LOW freedom — run exactly]`.
+
+The loop after `workflow-gtm`. Thirty minutes a week: read what the funnel
+did, name the one step that lost the most, ship one experiment against it,
+publish one thing, write it down. `iterate-post-launch` owns production
+defects; this owns growth.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **iterate-gtm-weekly** (this) | Weekly funnel read → one experiment → one post → scorecard |
+| `iterate-post-launch` | Sentry / production signals → fix |
+| `workflow-gtm` | The initial plan-to-apply run this loop follows |
+| `audit-analytics` | When a funnel cell is blind, add the event first |
+| `docs-launch-kit` | The post, when it is a launch |
+| `workflow-feedback-to-closure` | Turning user feedback into tickets |
+
+Do **not** fire for "errors spiked in production" → `iterate-post-launch`.
+
+## How to reason
+
+1. **Read** — the six funnel cells by source for the last 7 days vs the prior 7
+2. **Locate** — the single step with the largest absolute loss (not the smallest percentage)
+3. **Attribute** — did last week's experiment or post move anything; say so with the number
+4. **Choose** — one experiment on the losing step, one post, both small enough for this week
+5. **Record** — scorecard row appended; next review scheduled
+
+## Worked example
+
+> **Read:** visits 4,120 (+9%), signups 310 (−4%), activated 71 (23%, flat), paid 6, refer 2; Show HN source dried up, organic docs traffic up.
+> **Locate:** signup → activated loses 239 users; visit → signup lost 22 more than last week but far fewer in absolute terms.
+> **Attribute:** last week's hero rewrite: visit→signup 7.9% → 7.5% — no lift; keep for one more week (sample small).
+> **Choose:** experiment — pre-fill the workspace with sample data for the "explore" JTBD answer (`enhance-onboarding`); post — a short comparison page announcement.
+> **Record:** row appended to `plan-gtm.md` scorecard; review next Monday.
+
+## Self-critique before reporting
+
+- **Five lines** — the review fits: funnel by source · activation cohort · top drop-off · last experiment result · one post
+- **One experiment** — exactly one, with a metric and a stop date; a second becomes next week's
+- **Attributed** — last week's change has a number beside it, even if "no change" or "unmeasured"
+- **Recorded** — scorecard row appended in `plan-gtm.md` (or the file `workflow-gtm` produced)
+- **Right owner** — production errors → `iterate-post-launch`; new events → `audit-analytics`
+
+---
+
+## Procedure  [LOW freedom — run exactly]
+
+1. **Pull numbers** — analytics dashboard or export for Visit → Signup →
+   Activated → Habit → Paid → Refer, by `utm_source` / referrer, this week vs
+   last. Blind cell → write **unmeasured** and file the event with
+   `audit-analytics` as this week's experiment if it is the losing step.
+2. **Launch results** — fill any `docs/launch/*.md` Results table older than 7 days.
+3. **Locate the loss** — absolute users lost per step; pick the largest.
+4. **Attribute** — last week's experiment: metric before / after; keep, revert, or extend.
+5. **Choose** — one experiment (owner skill named) + one post (channel named).
+6. **Write the row** and schedule next week.
+
+## Levers by losing step  [HIGH freedom]
+
+| Losing step | First levers | Skill |
+|---|---|---|
+| Visit → Signup | hero five-second test, CTA verb, "no card" line, ungated try | `enhance-web-conversion` |
+| Signup → Activated | cut a field, sample data, checklist end = activation, day-1 nudge | `enhance-onboarding`, `enhance-lifecycle-email` |
+| Activated → Habit | day-3/7 nudges, saved-state reminder, second aha | `enhance-lifecycle-email` |
+| Habit → Paid | limit-moment prompt, price shown, annual toggle wording | `enhance-web-conversion`, `plan-pricing` |
+| Paid → Refer | badge, share artifact, referral credit on activation | `enhance-growth-loops` |
+| Visits themselves | one comparison page, one launch post, registry listing | `docs-comparison-pages`, `docs-launch-kit`, `audit-registry-listing` |
+
+## Scorecard row  [LOW freedom — shape]
+
+```markdown
+| Week | Visit | Signup | Activated | Habit | Paid | Refer | Top loss | Experiment (metric, stop date) | Post | Last week's result |
+```
+
+## Guardrails
+
+- **One experiment.** Two changes on one step make attribution impossible.
+- **Absolute loss, not percentage.** A 90% drop on 10 users is not the priority.
+- **Numbers or "unmeasured".** No estimates presented as measurements.
+- **Thirty minutes.** If the review grows, the instrumentation is the problem — file it.
+
+## Chains with
+
+- **`workflow-gtm`** → produces the scorecard this loop appends to.
+- **`audit-analytics`** → blind cells.
+- **`enhance-onboarding`**, **`enhance-web-conversion`**, **`enhance-lifecycle-email`**, **`enhance-growth-loops`**, **`docs-comparison-pages`**, **`docs-launch-kit`** → the levers.