@adia-ai/adia-ui-forge 0.1.3 → 0.8.1

package/skills/adia-ui-ops/references/recipes/recommend-then-validate.md

@@ -1,199 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - self-healing-hooks.md
-  - audit-existing-repo.md
-  - ../guidance/reliability-dial.md
-  - ../audit-patterns/audit-history-ledger.md
-primary_sources:
-  - Steve Yegge, "Welcome to Gas City" — multi-agent consensus pattern
-  - https://docs.anthropic.com/en/docs/claude-code/sub-agents — Claude Code subagent pattern
-status: research-verified
----
-
-# Recommend-then-validate (the two-agent fix pattern)
-
-> _"You should never just have one coding agent managing infrastructure… you should always have at least two or three working together on a little crew. Any agent can go temporarily insane, at any time, and make a bad call."_
-> — Steve Yegge, "Welcome to Gas City"
-
-## What this delivers
-
-A single agent's apply-mode pass is **one source of truth, no consensus**. If that agent hallucinates a fix, the bad fix lands. The recommend-then-validate pattern splits the work:
-
-1. **Recommender** — reads the audit; proposes specific fixes; produces a structured fix plan.
-2. **Validator** — receives the fix plan; dry-runs each fix against the trip-wires; vetoes any fix that would break an invariant; opens the PR with only the surviving fixes.
-
-The validator is *not* a critic. It's an execution gate that runs the same trip-wires after a hypothetical fix and confirms they still pass. A fix that introduces a new violation gets rejected.
-
-This pattern is **required for `strict` strictness** (per `../guidance/reliability-dial.md`) and **optional but recommended for `normal`** for any apply-mode pass touching >5 files.
-
-## The fix-plan contract
-
-The recommender emits a structured plan; the validator consumes it.
-
-```yaml
-# .brain/fix-plan-2026-04-27.yaml (transient; consumed then discarded)
-strictness: normal
-findings_addressed:
-  - id: DRIFT-CLAUDE-AGENTS
-    severity: critical
-fixes:
-  - kind: symlink
-    target: CLAUDE.md
-    points_to: AGENTS.md
-    reason: "Eliminates drift; satisfies Promise 1."
-  - kind: edit
-    file: AGENTS.md
-    description: "Compress 'Conventions' from 80 to 30 lines (Promise 2)."
-    diff_preview: |
-      [diff body]
-  - kind: archive
-    file: docs/old-plan.md
-    move_to: .brain/archive/old-plan-2026-04-27.md
-    reason: "Orphan, last modified 2024-08-15."
-```
-
-Each fix is *typed* (`symlink | edit | archive | create | delete`). The validator knows how to dry-run each kind.
-
-## The validator's veto rules
-
-After a hypothetical fix, the validator re-runs the relevant trip-wires:
-
-| Fix kind | Validator checks |
-|---|---|
-| `symlink` | Symlink target exists; ownership/permissions correct |
-| `edit` | Resulting file still <200 lines (entry files); frontmatter still valid; no new broken links introduced |
-| `archive` | File is genuinely orphaned (per `../audit-patterns/orphan-detection.md`); not within active grace window |
-| `create` | Path valid; doesn't conflict with existing file; YAML frontmatter present |
-| `delete` | **Always vetoed.** Move to `.brain/archive/` instead. Hard rule, no overrides. |
-
-If any veto fires, the fix is dropped from the plan and a finding is emitted: `VETO — <fix> rejected because <rule>`. The PR opens with the surviving fixes only.
-
-## Implementation paths
-
-### Path A — Sequential within Claude Code (simplest)
-
-Use the Claude Code subagent pattern. Main agent acts as recommender; spawns a validator subagent via the Agent tool with a fresh context.
-
-```
-1. Main agent runs the audit, builds fix plan, writes .brain/fix-plan-*.yaml
-2. Main agent spawns validator subagent: "Read .brain/fix-plan-*.yaml;
-   dry-run each fix; emit veto report."
-3. Validator subagent returns veto list (fresh context — can't share rationalization)
-4. Main agent removes vetoed fixes from plan; opens PR with remainder
-```
-
-The validator runs in fresh context, so it can't accidentally rationalize the recommender's earlier reasoning. Independent re-evaluation is the load-bearing property.
-
-### Path B — Distributed via GitHub Actions
-
-Two-job CI workflow. Job 1 (recommender) emits the fix plan as a workflow artifact. Job 2 (validator) downloads the artifact, dry-runs, opens the PR.
-
-```yaml
-# .github/workflows/repo-fixer-apply.yml
-jobs:
-  recommend:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: bash scripts/audit.sh > /tmp/audit.json
-      - run: bash scripts/build-fix-plan.sh /tmp/audit.json > /tmp/fix-plan.yaml
-      - uses: actions/upload-artifact@v4
-        with: { name: fix-plan, path: /tmp/fix-plan.yaml }
-
-  validate:
-    needs: recommend
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
-        with: { name: fix-plan }
-      - run: bash scripts/validate-fix-plan.sh fix-plan.yaml > /tmp/vetoes.txt
-      - run: bash scripts/apply-survivors.sh fix-plan.yaml /tmp/vetoes.txt
-      - uses: peter-evans/create-pull-request@v6
-        with:
-          title: '[repo-fixer] Apply audited fixes'
-          body-path: /tmp/pr-body.md
-```
-
-Job isolation ensures the validator can't share state with the recommender — Yegge's insight in cleanest form.
-
-## Iterating within a budget (autoresearch DNA)
-
-> Inspired by Karpathy's [autoresearch](https://github.com/karpathy/autoresearch) — autonomous propose-evaluate-iterate within a fixed budget. Repo-fixer scopes the spirit, not the overnight unattended shape: bounded rounds, deterministic eval, every iteration logged to the audit history ledger.
-
-The base pattern above is one round. For high-finding-count audits or `strict` strictness, that single round may leave fixes on the table — vetoed because of a *fixable* issue (e.g., a proposed AGENTS.md compression would still exceed 200 lines, but a tighter version wouldn't).
-
-The iterate-within-budget extension: when the validator vetoes fixes, feed the veto reasons back to the recommender and let it re-propose. Bounded by an explicit budget.
-
-### Configuration
-
-`.brain/config.toml`:
-
-```toml
-[ops-repo.iteration]
-enabled = false       # default: false (opt-in)
-max_rounds = 3        # hard cap; loop exits early if no new fixes survive
-wall_clock_seconds = 300  # 5 minutes total across all rounds
-```
-
-Each round, the recommender receives:
-
-1. The original audit findings (unchanged)
-2. The previous round's veto report (new — the agent reads "your symlink fix was vetoed because the target wasn't valid; here's why")
-3. The set of already-applied fixes from prior rounds (so it doesn't re-propose them)
-
-Each round logs to the audit history ledger as a separate entry within the run.
-
-### When iteration helps
-
-| Scenario | Outcome with 1 round | Outcome with 3 rounds |
-|---|---|---|
-| Recommender proposes 200-line AGENTS.md compression that would exceed the budget | Vetoed; user gets a TODO | Round 2 produces a 150-line version that passes |
-| Recommender suggests archiving a doc still in the 30-day grace window | Vetoed | Round 2 skips that doc; archives others |
-| All fixes pass first-round validation | PR with N fixes | Same PR — loop exits early |
-
-### When iteration doesn't help
-
-- Single-finding fixes (no benefit beyond round 1)
-- Vetoes that are fundamentally un-fixable (e.g., `delete-always-vetoed` — the rule will never let it through)
-- `lax` strictness (over-engineered for the use case)
-
-### Stop conditions
-
-The loop terminates when ANY of:
-
-1. All proposed fixes pass validation (early success)
-2. Two consecutive rounds produce zero new survivors (convergence)
-3. `max_rounds` reached
-4. `wall_clock_seconds` exhausted
-
-The PR opens with the union of surviving fixes across rounds, plus a final veto report listing what didn't survive.
-
-### How autoresearch DNA maps in (and where it stops)
-
-Autoresearch runs overnight, fully unattended, hill-climbing on a single file with a single metric. This loop runs in a single CI invocation, budgeted in minutes, human-reviewed via PR. We take *bounded propose-evaluate-iterate with a deterministic eval function* — we don't take overnight autonomy. Yegge alignment ("shepherds, not auto-pilots") stays intact.
-
-## When NOT to use this pattern
-
-- **Single-file fixes.** Symlinking CLAUDE.md once doesn't need two agents; the trip-wire itself is the validation.
-- **`lax` strictness on prototypes.** Friction unjustified.
-- **Repos with no production cost of doc breakage.** Solo side projects.
-
-The pattern earns its keep on multi-file passes where one bad fix can cascade.
-
-## Anti-patterns
-
-- **Recommender and validator share context.** Defeats the purpose. Validator must run in fresh context (subagent or separate CI job).
-- **Validator can edit the plan.** No. Validator only vetoes; the recommender's fixes are immutable inputs. Editing happens in the next round.
-- **Skipping the veto report.** The PR body should include the full veto list — humans need to see what *wasn't* applied and why.
-- **Auto-merging the PR.** No. The validator gate is necessary but not sufficient; humans still review and merge.
-- **Three or more agents in parallel for the same plan.** Diminishing returns; coordination cost dominates after two. Yegge says "two or three" for *different problems*, not redundant validators on one problem.
-
-## Cross-references
-
-- Reliability dial (which `strictness` levels require this pattern): `../guidance/reliability-dial.md`
-- Self-healing hooks (the trip-wires the validator runs): `self-healing-hooks.md`
-- Audit recipe (the input to the recommender): `audit-existing-repo.md`
-- Audit history (vetoes get recorded): `../audit-patterns/audit-history-ledger.md`

package/skills/adia-ui-ops/references/recipes/self-healing-hooks.md

@@ -1,366 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - continuous-learning-loop.md
-  - audit-existing-repo.md
-  - ../audit-patterns/staleness-tooling.md
-  - ../audit-patterns/redundancy-detection.md
-primary_sources:
-  - https://github.com/lycheeverse/lychee-action
-  - https://github.com/typicode/husky
-  - https://pre-commit.com/
-  - https://docs.github.com/actions/using-workflows/triggering-a-workflow
-  - https://djw.fyi/portfolio/preventing-drift/
-status: research-verified
----
-
-# Self-healing hooks (delivers Promise 4)
-
-> **The premise.** A repo without trip-wires can't honor the "self-healing" promise — it can only be clean today and rotten tomorrow. This recipe installs the hooks that catch breakage before it lands and the workflows that keep watch on a schedule.
-
-## What "self-healing" means concretely
-
-A self-healing repo:
-
-1. **Refuses to merge PRs** that introduce drift between CLAUDE.md and AGENTS.md.
-2. **Refuses to merge PRs** with broken intra-repo or external links in `.brain/` or `docs/`.
-3. **Refuses commits** that bloat AGENTS.md / CLAUDE.md past the 200-line ceiling.
-4. **Auto-archives** orphaned docs after a 30-day grace period.
-5. **Surfaces stale content** weekly (scheduled CI), not on a someone-remembered-to-look basis.
-6. **Captures decisions** at the moment of decision (ADR-on-architectural-change), not retroactively.
-
-The first three are pre-commit / PR-time gates. The fourth is a scheduled workflow. The fifth is a scheduled audit. The sixth is a `continuous-learning-loop.md` flow.
-
-## The hook stack
-
-### Layer 1 — pre-commit hooks (local; catch problems before they leave the machine)
-
-Use `pre-commit` (Python) or `husky` (Node). The skill recommends `pre-commit` for cross-language repos and `husky` for Node-monoculture.
-
-#### pre-commit (`.pre-commit-config.yaml`)
-
-```yaml
-# .pre-commit-config.yaml
-repos:
-  # Lint Markdown structure
-  - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.42.0
-    hooks:
-      - id: markdownlint
-        files: '\.(md|MD)$'
-
-  # Repo-brain trip-wires (custom, local hooks)
-  - repo: local
-    hooks:
-      # Trip-wire 1: AGENTS.md / CLAUDE.md must not drift
-      - id: agents-claude-drift
-        name: AGENTS.md / CLAUDE.md must not have drifted prose
-        entry: bash -c 'bash scripts/check-agents-claude-drift.sh'
-        language: system
-        files: '^(AGENTS\.md|CLAUDE\.md)$'
-        pass_filenames: false
-
-      # Trip-wire 2: AGENTS.md / CLAUDE.md must stay <200 lines
-      - id: entry-file-length
-        name: Entry files <200 lines (warn at 150)
-        entry: bash -c 'for f in AGENTS.md CLAUDE.md; do if [ -f "$f" ] && [ ! -L "$f" ]; then n=$(wc -l <"$f"); if [ "$n" -gt 200 ]; then echo "ERROR: $f is $n lines (>200)"; exit 1; elif [ "$n" -gt 150 ]; then echo "WARN: $f is $n lines (>150)"; fi; fi; done'
-        language: system
-        pass_filenames: false
-
-      # Trip-wire 3: docs in .brain/ or docs/ must have a date
-      - id: doc-frontmatter-date
-        name: .brain/*.md and docs/*.md must have date frontmatter or "Last reviewed:" line
-        entry: bash -c 'bash scripts/check-doc-dates.sh'
-        language: system
-        files: '^(\.brain|docs)/.*\.md$'
-        pass_filenames: true
-```
-
-#### `scripts/check-agents-claude-drift.sh`
-
-```bash
-#!/usr/bin/env bash
-# Trip-wire: AGENTS.md and CLAUDE.md must not have drifted prose.
-# Pass cases:
-#   (a) CLAUDE.md is a symlink to AGENTS.md → identical content.
-#   (b) CLAUDE.md is a thin pointer (≤15 lines) referencing AGENTS.md.
-#   (c) AGENTS.md exists, CLAUDE.md does not.
-# Fail: both exist as fat (>15 lines) divergent files.
-
-set -euo pipefail
-
-if [ ! -f AGENTS.md ] && [ ! -f CLAUDE.md ]; then
-    exit 0  # Neither exists; not this hook's problem
-fi
-
-if [ ! -f AGENTS.md ]; then
-    echo "ERROR: CLAUDE.md exists but AGENTS.md does not. Promote CLAUDE.md → AGENTS.md."
-    exit 1
-fi
-
-if [ ! -f CLAUDE.md ]; then
-    exit 0  # AGENTS.md only; fine
-fi
-
-# CLAUDE.md is a symlink? (clean)
-if [ -L CLAUDE.md ]; then
-    target="$(readlink CLAUDE.md)"
-    if [ "$target" = "AGENTS.md" ]; then
-        exit 0
-    else
-        echo "ERROR: CLAUDE.md is a symlink to '$target', not AGENTS.md."
-        exit 1
-    fi
-fi
-
-# CLAUDE.md is thin? (clean)
-claude_lines=$(wc -l < CLAUDE.md)
-if [ "$claude_lines" -le 15 ]; then
-    if grep -q -i "AGENTS\.md" CLAUDE.md; then
-        exit 0
-    else
-        echo "ERROR: CLAUDE.md is short but doesn't reference AGENTS.md."
-        exit 1
-    fi
-fi
-
-# Both fat → drift risk.
-echo "ERROR: Both AGENTS.md ($(wc -l <AGENTS.md) lines) and CLAUDE.md ($claude_lines lines) are fat."
-echo "       Demote one to a thin pointer or symlink. See ops-repo/standards/claude-md-convention.md."
-exit 1
-```
-
-#### `scripts/check-doc-dates.sh`
-
-```bash
-#!/usr/bin/env bash
-# Trip-wire: every .brain/*.md and docs/*.md must have a date.
-set -euo pipefail
-fail=0
-for f in "$@"; do
-    if grep -qE '^date:[[:space:]]*[0-9]{4}-[0-9]{2}-[0-9]{2}' "$f"; then
-        continue  # YAML frontmatter date OK
-    fi
-    if grep -qE '_Last reviewed:[[:space:]]*[0-9]{4}-[0-9]{2}-[0-9]{2}' "$f"; then
-        continue  # Inline "Last reviewed:" line OK
-    fi
-    echo "ERROR: $f has no date frontmatter or 'Last reviewed:' line."
-    fail=1
-done
-exit $fail
-```
-
-### Layer 2 — PR-time CI (catch problems before merge)
-
-#### `.github/workflows/repo-brain-pr.yml`
-
-```yaml
-name: Repo-brain (PR)
-
-on:
-  pull_request:
-    paths: ['**.md', '.brain/**', 'docs/**', 'AGENTS.md', 'CLAUDE.md', '.cursor/**', '.windsurfrules', '.github/copilot-instructions.md']
-
-jobs:
-  links:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Lychee link check
-        uses: lycheeverse/lychee-action@v2
-        with:
-          args: --cache --max-cache-age=1d --no-progress '.brain/**/*.md' 'docs/**/*.md' '*.md'
-          fail: true
-
-  drift-and-length:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: bash scripts/check-agents-claude-drift.sh
-      - run: bash scripts/check-entry-file-length.sh
-
-  doc-dates:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
-      - run: |
-          changed=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- '.brain/**/*.md' 'docs/**/*.md' || true)
-          if [ -n "$changed" ]; then
-            bash scripts/check-doc-dates.sh $changed
-          fi
-
-  llm-doc-drift:
-    if: ${{ vars.LLM_DOC_DRIFT_ENABLED == 'true' }}
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
-      - name: Ask LLM if code diff requires doc updates
-        env:
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-        run: bash scripts/llm-doc-drift-check.sh
-```
-
-The `llm-doc-drift` job is opt-in (gated on `vars.LLM_DOC_DRIFT_ENABLED`) — costs API calls per PR. Worth it for high-traffic repos; overkill for hobby projects.
-
-### Layer 3 — scheduled CI (find problems no commit triggered)
-
-#### `.github/workflows/repo-brain-weekly.yml`
-
-```yaml
-name: Repo-brain (weekly audit)
-
-on:
-  schedule:
-    - cron: '0 13 * * 1'  # Mondays 13:00 UTC
-  workflow_dispatch:
-
-jobs:
-  full-audit:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
-
-      - name: External link check (full)
-        uses: lycheeverse/lychee-action@v2
-        with:
-          args: --no-progress '.brain/**/*.md' 'docs/**/*.md' '*.md'
-          fail: false  # Don't fail; report
-
-      - name: Stale-doc detection (mtime + frontmatter)
-        run: bash scripts/find-stale-docs.sh > stale-report.md
-
-      - name: Orphan detection
-        run: bash scripts/find-orphan-docs.sh > orphan-report.md
-
-      - name: Open issue if findings
-        if: always()
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const fs = require('fs');
-            const stale = fs.readFileSync('stale-report.md', 'utf8');
-            const orphans = fs.readFileSync('orphan-report.md', 'utf8');
-            if (stale.trim() || orphans.trim()) {
-              await github.rest.issues.create({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                title: `[ops-repo] Weekly audit findings — ${new Date().toISOString().slice(0,10)}`,
-                body: `## Stale docs\n\n${stale}\n\n## Orphans\n\n${orphans}`,
-                labels: ['docs', 'ops-repo']
-              });
-            }
-```
-
-### Layer 4 — auto-archive (the orphan grace-period flow)
-
-#### `scripts/find-orphan-docs.sh`
-
-```bash
-#!/usr/bin/env bash
-# Find docs in .brain/ or docs/ not referenced by any entry file or other doc.
-set -euo pipefail
-all_docs=$(find .brain docs -type f -name '*.md' 2>/dev/null)
-referenced=$(
-  cat AGENTS.md CLAUDE.md README.md .brain/**/*.md docs/**/*.md 2>/dev/null \
-  | grep -oE '\[[^]]+\]\(([^)]+)\)' \
-  | grep -oE '\(([^)]+)\)' \
-  | tr -d '()' \
-  | sort -u
-)
-for f in $all_docs; do
-    base=$(basename "$f")
-    if ! echo "$referenced" | grep -q -F "$base"; then
-        # Orphan candidate.
-        last_modified=$(git log -1 --format=%cs -- "$f")
-        echo "- $f (last modified: $last_modified)"
-    fi
-done
-```
-
-#### `.github/workflows/repo-brain-auto-archive.yml`
-
-```yaml
-name: Repo-brain (auto-archive orphans after 30-day grace)
-on:
-  schedule:
-    - cron: '0 13 * * 1'  # Mondays
-  workflow_dispatch:
-
-jobs:
-  archive:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
-      - name: Move stale orphans to .brain/archive/
-        run: |
-          # An orphan unmodified for 30+ days AND not in /archive/ → archive it.
-          while IFS= read -r line; do
-            [[ -z "$line" ]] && continue
-            f=$(echo "$line" | cut -d' ' -f2)
-            [[ "$f" == .brain/archive/* ]] && continue
-            [[ "$f" == docs/archive/* ]] && continue
-            mtime=$(git log -1 --format=%ct -- "$f")
-            now=$(date +%s)
-            age_days=$(( (now - mtime) / 86400 ))
-            if [ "$age_days" -gt 30 ]; then
-              mkdir -p .brain/archive
-              git mv "$f" ".brain/archive/$(basename "$f")"
-              echo "Archived: $f (orphan for ${age_days}d)"
-            fi
-          done < <(bash scripts/find-orphan-docs.sh)
-      - name: Open PR
-        uses: peter-evans/create-pull-request@v6
-        with:
-          base: main           # see the gotcha below — required for tag-push triggers
-          title: '[ops-repo] Auto-archive stale orphan docs'
-          body: 'Auto-archived orphan docs untouched for 30+ days. Review and merge or revert.'
-          branch: ops-repo/auto-archive
-```
-
-The PR step is critical — **never silently delete or move docs**. Always open a PR so a human can review.
-
-### Gotcha — `peter-evans/create-pull-request` needs `base: main` on tag-push
-
-If your workflow also triggers on tag pushes (e.g., a build-log harvest that fires on every release tag), the GitHub Actions runner checks out the *tag* — which is a detached HEAD, not a branch. Without an explicit `base` input, `create-pull-request` exits with:
-
-```
-##[error]When the repository is checked out on a commit instead of a branch,
-the 'base' input must be supplied.
-```
-
-**Symptom**: every tag-push run of the workflow fails at the PR-opening step. Cron and `workflow_dispatch` runs (which check out the branch) succeed; tag-push runs fail. The audit ledger drops entries silently — the harvester writes the JSON, but the PR never opens, so the entry never lands on `main`.
-
-**Fix**: always set `base: main` (or your default branch). It's a no-op on cron / dispatch runs (the action would auto-detect `main` anyway) and load-bearing on tag-push runs.
-
-Observed in the wild on 2026-04-28 — a build-log workflow at `adiahealth/gen-ui-kit` failed for 8 consecutive tag-push runs because the action wouldn't open the PR. The cron path worked but the entry sat in an unmerged PR (`ops-repo/build-log` branch) for 2 days, so the ledger appeared frozen at the last manually-merged entry. The fix is one line.
-
-## What the audit verifies
-
-When `ops-repo` audits a repo, the self-healing check looks for:
-
-1. ✅ `.pre-commit-config.yaml` exists OR `.husky/` has equivalent hooks.
-2. ✅ The `agents-claude-drift`, `entry-file-length`, `doc-frontmatter-date` hooks are wired.
-3. ✅ `.github/workflows/repo-brain-pr.yml` (or equivalent) exists and includes lychee.
-4. ✅ `.github/workflows/repo-brain-weekly.yml` (or equivalent scheduled audit) exists.
-5. ✅ `scripts/check-agents-claude-drift.sh` and the other helper scripts exist.
-
-If any are missing, the audit emits a `MISSING TRIP-WIRE` finding with severity = high (because the promise of self-healing isn't being delivered).
-
-## Common anti-patterns
-
-- **Hooks defined but not installed** — `.pre-commit-config.yaml` exists but no one ran `pre-commit install`. The audit cannot detect installation; this is a `setup` step in `recipes/greenfield-setup.md`.
-- **Auto-archive without PR step** — silently moving files breaks links. Always go through PR.
-- **Lychee with `fail: false` everywhere** — defeats the gate. Use `fail: true` on PR; `fail: false` only on scheduled audits where issue-opening is the action.
-- **No grace period on orphans** — files get archived on the first scan after they go orphaned. 30 days is the recommended floor.
-
-## Cross-references
-
-- Continuous-learning loop (Promise 5): `continuous-learning-loop.md`
-- Staleness tooling deep dive: `../audit-patterns/staleness-tooling.md`
-- Redundancy detection: `../audit-patterns/redundancy-detection.md`
-- Full audit recipe: `audit-existing-repo.md`

package/skills/adia-ui-ops/references/recipes/skill-stewardship-loop.md

@@ -1,113 +0,0 @@
-# Skill stewardship loop
-
-The continuously-learning loop for procedural memory (skills) — the
-analog of `harvest ops-repo` for the doc surface.
-
-**Authored:** 2026-05-02 — implements Step 2 of the ops-repo v2.0
-skill-stewardship evolution. Pairs with `scripts/skills/audit-skills.mjs`
-+ `scripts/skills/draft-skill.mjs` + `scripts/skills/check-skill-frontmatter.mjs`.
-
-## The cadence
-
-Run `npm run audit:skills` at three triggers:
-
-1. **Session-end** of any major work (release cut, multi-day arc,
-   postmortem). Surfaces candidates from procedures the session walked.
-2. **Quarterly** as part of the `/ops-repo` audit. Catches accumulated
-   drift — stale refs, redundancy, low-utility skills.
-3. **On-demand** when the user asks "is anything stale?" or "what
-   skills should we have?".
-
-Each run produces 0–N findings. Triage by severity:
-
-- **Errors** (currently none from `audit:skills`; `check:skills` produces
-  errors for missing frontmatter).
-- **Warns** — stale refs, description redundancy. Fix immediately or
-  document as deferred.
-- **Info** — procedure-recurrence candidates, graduation gaps,
-  description-divergence hints. Review; promote to drafts via
-  `npm run draft:skill <name>` when appropriate.
-
-## The 6 detection signals (recap)
-
-| # | Signal | Threshold | What it surfaces |
-|---|---|---|---|
-| 1 | Pattern recurrence in journals | ≥ 2 sessions | Procedures walked enough to deserve a skill |
-| 2 | Graduations without skills | row mentions script but no skill | Permanent infrastructure that lacks procedural skill capture |
-| 3 | Memory citation count | ≥ 3 citations | Memory entries hot enough to warrant skill promotion |
-| 4 | Stale path/tag refs in SKILL.md | path doesn't resolve | Skills referencing renamed code |
-| 5 | Description-vs-body divergence | body churn ≥ 100 lines | Skills whose body has evolved beyond the description |
-| 6 | Pairwise description similarity | Jaccard ≥ 0.6 | Likely-redundant skill pairs |
-
-Thresholds tunable via `.brain/config.toml` (when implemented; today
-they're hardcoded in `audit-skills.mjs`).
-
-## The triage flow
-
-```
-audit-skills (read-only)
-    │
-    ▼
-finding cluster
-    │
-    ├─→ stale-skill-ref ──────→ iterate skill --update (fix paths)
-    │                            (or: just edit SKILL.md directly)
-    │
-    ├─→ description-similarity ──→ iterate skill --merge OR
-    │                              edit descriptions to differentiate
-    │
-    ├─→ procedure-recurrence ──→ draft-skill <name> --journal-section ...
-    │                            (operator reviews + commits)
-    │
-    ├─→ graduation-without-skill → draft-skill <name> --audit-finding ...
-    │                              (or: skip if mechanical infra is enough)
-    │
-    └─→ description-divergence-hint ──→ review SKILL.md description vs body;
-                                        edit description if stale
-```
-
-## Anti-patterns
-
-- **Acting on every info finding.** Info-level signals are advisory.
-  Procedure-recurrence in journals doesn't *always* mean a skill is
-  warranted — sometimes the recurring section is "Verification" which
-  is just session-end discipline, not a procedure. Triage before
-  promoting.
-
-- **Auto-archiving stale skills.** `audit-skills` doesn't have an
-  `archive` mode for the same reason `ops-repo` doesn't auto-delete
-  orphan docs: a stale skill might just need an `iterate skill --update`
-  pass, not deletion. Archive only after explicit superseded-by
-  designation.
-
-- **Filling out the skeleton in one pass.** `draft-skill` produces a
-  TODO-heavy SKILL.md. The skeleton lays the canvas; **synthesis is a
-  separate pass**, ideally invoking `meta-skill` /
-  `meta-expert-author` against the skeleton. Don't ship a draft as
-  if it were a finished skill — `check:skills` catches the
-  description-too-short and trigger-phrases-thin cases, but only after
-  you ask CI to validate.
-
-- **Treating user-level skills as in scope.** This audit walks
-  `.agents/skills/` (project-local) only. User-level skills at
-  `~/.claude/skills/` (or `~/.pi/agent/skills/` for Pi) are managed by a separate cadence — they travel
-  across projects and shouldn't be governed by any single project's
-  audit. Run a separate user-level audit quarterly if needed.
-
-## Pairs with
-
-- `lockstep-release` — every coordinated cut graduates infrastructure;
-  the post-publish admin should include `audit:skills` to capture any
-  procedures the cut walked.
-- `stale-audit` — sibling sweep for the doc surface.
-- `ops-postmortem` — postmortems often surface graduation
-  candidates that map to skills.
-- `ops-memory` — when memory entries are superseded by
-  skills, the entry's description should flag the supersession.
-
-## Future evolution
-
-- **Telemetry-based utility detection.** When the harness logs `Skill({skill: X})` invocations, low-utility skills (zero invocations across N sessions despite matching prompts) become detectable. Today only the heuristic divergence-hint exists.
-- **Description-vs-body diff.** Today's body-churn-since-description-edit is approximate. A real diff would track which lines of the description haven't been touched since the body changes.
-- **Cross-skill pairs-with graph audit.** When skill A says "pairs with B" but B doesn't say "pairs with A", the graph is asymmetric. An audit signal could flag.
-- **Skill lifecycle states in frontmatter.** Adding `status: candidate | draft | active | stale | superseded | archived` would let the audit transition skills explicitly through the graph.