@lifeaitools/rdc-skills 0.25.0 → 0.25.2

package/skills/review/SKILL.md

@@ -1,152 +1,160 @@
----
-name: rdc:review
-description: "Usage `rdc:review [--unattended]` — Post-build quality gate: tsc, tests, stale docs, export conflicts, and a mandatory pr-review-toolkit:code-reviewer pass across modified packages. Fixes what it can automatically, escalates the rest. Call after rdc:build and before merging to main."
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
-
-> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`), then `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md` (fallback: `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md`).
-
-> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
-
-
-# rdc:review — Quality Gate
-
-## When to Use
-- After a build session (especially overnight builds)
-- Before merging development → main/production
-- Project lead asks "review the work", "is everything clean"
-- Before any production deployment
-- Called by `rdc:overnight` after each epic build completes
-
-## Arguments
-- `rdc:review` — interactive review, pauses on issues needing judgment
-- `rdc:review --unattended` — silent mode, auto-fixes everything fixable
-
-## Procedure
-
-1. **Identify modified packages:**
-   ```bash
-   git diff --name-only origin/main...HEAD | grep "^packages/" | cut -d/ -f2 | sort -u
-   ```
-
-2. **Run tests for each modified package:**
-   ```bash
-   cd packages/<name> && npx vitest run 2>&1 | tail -10
-   ```
-   Report: package → test count → pass/fail → new tests added
-
-   **IMPORTANT:** `pnpm build` must NEVER be run (crashes system). Use `npx tsc --noEmit --project <path>/tsconfig.json` for typecheck instead. For packages without tests, typecheck is the verification method. Do NOT run vitest across the entire monorepo — check only modified packages individually.
-
-3. **Check test coverage delta:**
-   ```bash
-   git diff origin/main...HEAD -- packages/*/src/ | grep -c "^+" | head -5
-   git diff origin/main...HEAD -- packages/*/test* packages/*/src/**/*.test.* packages/*/src/**/*.spec.* 2>/dev/null | grep -c "^+" || echo 0
-   ```
-   Flag any package where implementation lines added > 50 but test lines added = 0.
-
-4. **Check for export conflicts:**
-   - Read `packages/*/src/index.ts` for any package with new exports
-   - Look for duplicate export names across the barrel
-   - Verify aliased exports don't shadow each other
-
-5. **Check for TODO/FIXME/HACK:**
-   ```bash
-   grep -rn "TODO\|FIXME\|HACK\|XXX" packages/*/src/ --include="*.ts" --include="*.tsx"
-   ```
-
-6. **Check package versions:**
-   - Any package with significant new code should have a version bump
-   - Compare package.json versions to what's in `docs/SYSTEM-STATE.md`
-
-7. **Check for stale CLAUDE.md:**
-   - If new modules were added to a package, does its CLAUDE.md mention them?
-   - Flag any package where exports grew by >10 lines but CLAUDE.md wasn't updated
-
-8. **Orphan work item audit:**
-   ```sql
-   SELECT id, title, item_type, status, source, created_at::date
-   FROM work_items
-   WHERE parent_id IS NULL
-     AND item_type NOT IN ('epic', 'bug')
-     AND status NOT IN ('done', 'archived')
-   ORDER BY created_at DESC;
-   ```
-   For each orphaned task found:
-   - If it clearly belongs to an open epic → **do not run raw SQL**. No RPC exists for re-parenting. Create a work item: `SELECT insert_work_item(p_title := 'Re-parent orphaned task <task-id> to epic <epic-id>', p_priority := 'normal', p_source := 'agent')` and flag for supervisor to re-parent manually.
-   - If unclear → report (interactive) or flag in REVIEW_STATUS (unattended)
-   - Never silently leave orphaned tasks
-   - **⛔ Raw `UPDATE work_items SET parent_id = ...` is forbidden** — bypasses RLS and all constraint checks
-
-8b. **Mandatory code-review gate — dispatch pr-review-toolkit:code-reviewer:**
-
-   ⛔ **No CLEAN verdict without a code-review pass.** This is the second half of the quality gate; tsc/vitest catch type and behavior errors, code-reviewer catches logic, security, and convention drift.
-
-   Dispatch ONE `pr-review-toolkit:code-reviewer` agent on the full diff under review:
-
-   ```
-   Agent({
-     subagent_type: "pr-review-toolkit:code-reviewer",
-     description: "rdc:review code-review pass",
-     prompt: "Review `git diff origin/main...HEAD` on the development branch.
-              Focus on: bugs, logic errors, security vulnerabilities, project-convention
-              adherence (.claude/rules/*, CLAUDE.md, engineering-behavior.md).
-              Confidence-based filtering — high-confidence findings only.
-              Return CODE_REVIEW_COMPLETE with: { critical_count, high_count, medium_count,
-              low_count, findings: [{severity, file:line, issue, suggested_fix}] }."
-   })
-   ```
-
-   **Severity gate:**
-   - `critical` or `high` → verdict cannot be CLEAN. Interactive: report and pause. Unattended: auto-fix if mechanical (rename, missing await, obvious null check), otherwise escalate via advisor and mark HAS_ISSUES.
-   - `medium` or `low` → record in the review report's "Issues" section; verdict can still be CLEAN.
-   - Zero findings → log `CODE_REVIEW: CLEAN` and continue.
-
-   Under `RDC_TEST=1`: echo `[RDC_TEST] skipping code-review dispatch` and continue.
-
-9. **Verification gate — dispatch the verify agent:**
-   After any fixes land, run the verify gate on every touched package. See `guides/agents/verify.md`.
-   Apply `guides/engineering-behavior.md` while reviewing: flag unnecessary abstraction, drive-by refactors, missing assumptions, hidden uncertainty, out-of-scope edits, and prose-only verification.
-   **Iron Law: no CLEAN verdict without fresh evidence.** Quote the checklist decomposition verdict, vitest output, and tsc output in the report.
+---
+name: rdc:review
+description: "Usage `rdc:review [--unattended]` — Post-build quality gate: tsc, tests, stale docs, export conflicts, and a mandatory pr-review-toolkit:code-reviewer pass across modified packages. Fixes what it can automatically, escalates the rest. Call after rdc:build and before merging to main."
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`), then `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md` (fallback: `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md`).
+
+> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
+
+
+# rdc:review — Quality Gate
+
+## When to Use
+- After a build session (especially overnight builds)
+- Before merging development → main/production
+- Project lead asks "review the work", "is everything clean"
+- Before any production deployment
+- Called by `rdc:overnight` after each epic build completes
+
+## Arguments
+- `rdc:review` — interactive review, pauses on issues needing judgment
+- `rdc:review --unattended` — silent mode, auto-fixes everything fixable
+
+## Procedure
+
+1. **Identify modified packages:**
+   ```bash
+   git diff --name-only origin/main...HEAD | grep "^packages/" | cut -d/ -f2 | sort -u
+   ```
+
+2. **Run tests for each modified package:**
+   ```bash
+   cd packages/<name> && npx vitest run 2>&1 | tail -10
+   ```
+   Report: package → test count → pass/fail → new tests added
+
+   **IMPORTANT:** `pnpm build` must NEVER be run (crashes system). Use `npx tsc --noEmit --project <path>/tsconfig.json` for typecheck instead. For packages without tests, typecheck is the verification method. Do NOT run vitest across the entire monorepo — check only modified packages individually.
+
+3. **Check test coverage delta:**
+   ```bash
+   git diff origin/main...HEAD -- packages/*/src/ | grep -c "^+" | head -5
+   git diff origin/main...HEAD -- packages/*/test* packages/*/src/**/*.test.* packages/*/src/**/*.spec.* 2>/dev/null | grep -c "^+" || echo 0
+   ```
+   Flag any package where implementation lines added > 50 but test lines added = 0.
+
+4. **Check for export conflicts:**
+   - Read `packages/*/src/index.ts` for any package with new exports
+   - Look for duplicate export names across the barrel
+   - Verify aliased exports don't shadow each other
+
+5. **Check for TODO/FIXME/HACK:**
+   ```bash
+   grep -rn "TODO\|FIXME\|HACK\|XXX" packages/*/src/ --include="*.ts" --include="*.tsx"
+   ```
+
+6. **Check package versions:**
+   - Any package with significant new code should have a version bump
+   - Compare package.json versions to what's in `docs/SYSTEM-STATE.md`
+
+7. **Check for stale CLAUDE.md:**
+   - If new modules were added to a package, does its CLAUDE.md mention them?
+   - Flag any package where exports grew by >10 lines but CLAUDE.md wasn't updated
+
+8. **Orphan work item audit:**
+   ```sql
+   SELECT id, title, item_type, status, source, created_at::date
+   FROM work_items
+   WHERE parent_id IS NULL
+     AND item_type NOT IN ('epic', 'bug')
+     AND status NOT IN ('done', 'archived')
+   ORDER BY created_at DESC;
+   ```
+   For each orphaned task found:
+   - If it clearly belongs to an open epic → **do not run raw SQL**. No RPC exists for re-parenting. Create a work item: `SELECT insert_work_item(p_title := 'Re-parent orphaned task <task-id> to epic <epic-id>', p_priority := 'normal', p_source := 'agent')` and flag for supervisor to re-parent manually.
+   - If unclear → report (interactive) or flag in REVIEW_STATUS (unattended)
+   - Never silently leave orphaned tasks
+   - **⛔ Raw `UPDATE work_items SET parent_id = ...` is forbidden** — bypasses RLS and all constraint checks
+
+8b. **Mandatory code-review gate — dispatch pr-review-toolkit:code-reviewer:**
+
+   ⛔ **No CLEAN verdict without a code-review pass.** This is the second half of the quality gate; tsc/vitest catch type and behavior errors, code-reviewer catches logic, security, and convention drift.
+
+   Dispatch ONE `pr-review-toolkit:code-reviewer` agent on the full diff under review:
+
+   ```
+   Agent({
+     subagent_type: "pr-review-toolkit:code-reviewer",
+     description: "rdc:review code-review pass",
+     prompt: "Review `git diff origin/main...HEAD` on the development branch.
+              Focus on: bugs, logic errors, security vulnerabilities, project-convention
+              adherence (.claude/rules/*, CLAUDE.md, engineering-behavior.md).
+              Confidence-based filtering — high-confidence findings only.
+              Return CODE_REVIEW_COMPLETE with: { critical_count, high_count, medium_count,
+              low_count, findings: [{severity, file:line, issue, suggested_fix}] }."
+   })
+   ```
+
+   **Severity gate:**
+   - `critical` or `high` → verdict cannot be CLEAN. Interactive: report and pause. Unattended: auto-fix if mechanical (rename, missing await, obvious null check), otherwise escalate via advisor and mark HAS_ISSUES.
+   - `medium` or `low` → record in the review report's "Issues" section; verdict can still be CLEAN.
+   - Zero findings → log `CODE_REVIEW: CLEAN` and continue.
+
+   Under `RDC_TEST=1`: echo `[RDC_TEST] skipping code-review dispatch` and continue.
+
+9. **Verification gate — dispatch the verify agent:**
+   After any fixes land, run the verify gate on every touched package. See `guides/agents/verify.md`.
+   Apply `guides/engineering-behavior.md` while reviewing: flag unnecessary abstraction, drive-by refactors, missing assumptions, hidden uncertainty, out-of-scope edits, and prose-only verification.
+   **Iron Law: no CLEAN verdict without fresh evidence.** Quote the checklist decomposition verdict, vitest output, and tsc output in the report.
    The verify agent must reject any work item that lacks passed `decomp-*` checklist rows, whose rows are too coarse to prove one observable behavior at a time, OR whose checklist falls below the per-surface completeness floor (a feature WP with 5-6 rows where its surfaces demand 12-20 attested rows is a REJECT).
-   If verify fails → do NOT emit CLEAN. Loop back, fix, re-run verify.
-
-10. **Fix issues found:**
-   - Failing tests → fix and commit
-   - Export conflicts → resolve and commit
-   - Missing version bumps → bump and commit
-   - All fixes as separate commits with descriptive messages
-
-   **Judgment calls:**
-   - Interactive: report — don't guess
-   - Unattended: escalate via advisor tool with: error message, surrounding context,
-     two most likely fix paths. Resume with advisor's recommendation.
-     If advisor unavailable: take the most conservative path, flag in status block.
-
-11. **Report:**
-    - Interactive:
-      ```
-      ## Review Results
-      | Package | Tests | Pass/Fail | New Tests | Issues |
-      ## Fixed
-      ## Remaining Issues
-      ## Verdict: CLEAN / HAS ISSUES
-      ```
-    - Unattended: emit status block only:
-      ```
-      REVIEW_STATUS: { verdict: "CLEAN|HAS_ISSUES", packages_checked, tests_passed, tests_failed, new_tests_added, fixes_applied, escalations }
-      ```
-
-## Rules
-- Do NOT run `pnpm build` (crashes system) — vitest only
-- Interactive: fix what you can, flag what needs decision
-- Unattended: fix everything fixable; escalate judgment calls to advisor
-- Each fix is a separate commit (not batched)
-- Always push fixes to origin after committing *(skip if `$RDC_TEST=1` — echo `[RDC_TEST] skipping git push` instead)*
-- Unattended: NEVER pause for input
-
-## Capture lessons (exit step)
-
-Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-review-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.
+   **Durable workflow hard gate:** If the diff adds or changes a queue/job,
+   background worker, storage hand-off, retry/lease, webhook, or async
+   cross-process path, require a committed E2E harness and a fresh receipt from
+   a deploy-equivalent container plus real disposable dependencies (or isolated
+   mirror). It must invoke public ingress, prove the complete state transition,
+   verify every persisted output, and prove `finally` cleanup. Unit tests,
+   mocks, migrations, Docker construction, and route-health probes are not
+   substitutes; missing evidence means `HAS_ISSUES`, never `CLEAN`.
+   If verify fails → do NOT emit CLEAN. Loop back, fix, re-run verify.
+
+10. **Fix issues found:**
+   - Failing tests → fix and commit
+   - Export conflicts → resolve and commit
+   - Missing version bumps → bump and commit
+   - All fixes as separate commits with descriptive messages
+
+   **Judgment calls:**
+   - Interactive: report — don't guess
+   - Unattended: escalate via advisor tool with: error message, surrounding context,
+     two most likely fix paths. Resume with advisor's recommendation.
+     If advisor unavailable: take the most conservative path, flag in status block.
+
+11. **Report:**
+    - Interactive:
+      ```
+      ## Review Results
+      | Package | Tests | Pass/Fail | New Tests | Issues |
+      ## Fixed
+      ## Remaining Issues
+      ## Verdict: CLEAN / HAS ISSUES
+      ```
+    - Unattended: emit status block only:
+      ```
+      REVIEW_STATUS: { verdict: "CLEAN|HAS_ISSUES", packages_checked, tests_passed, tests_failed, new_tests_added, fixes_applied, escalations }
+      ```
+
+## Rules
+- Do NOT run `pnpm build` (crashes system) — vitest only
+- Interactive: fix what you can, flag what needs decision
+- Unattended: fix everything fixable; escalate judgment calls to advisor
+- Each fix is a separate commit (not batched)
+- Always push fixes to origin after committing *(skip if `$RDC_TEST=1` — echo `[RDC_TEST] skipping git push` instead)*
+- Unattended: NEVER pause for input
+
+## Capture lessons (exit step)
+
+Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-review-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.

package/skills/self-test/SKILL.md

@@ -1,100 +1,100 @@
----
-name: rdc:self-test
-description: "Usage `rdc:self-test [--strict]` — Validate all rdc:* skills, plugin manifest, and tooling consistency. Use after editing skills, upgrading the plugin, or when a skill behaves unexpectedly."
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw runner dumps — summarize.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
-
-> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Tier 2 behavioral runs and any git push are skipped under `RDC_TEST=1`; Tier 1 static lint runs normally.
-
-
-# rdc:self-test — Skill Library Self-Test (Tier 1)
-
-## When to Use
-- Before every `rdc:release rdc-skills` tag push
-- After editing any skill description or frontmatter
-- When a skill mysteriously disappears from the menu (backtick bug repro)
-- In CI on every rdc-skills PR (once wired)
-
-## Tiers
-
-| Tier | What it checks | Status |
-|------|----------------|--------|
-| Tier 1 | Static lint — frontmatter, Usage line, referenced files, name match | ✅ live |
+---
+name: rdc:self-test
+description: "Usage `rdc:self-test [--strict]` — Validate all rdc:* skills, plugin manifest, and tooling consistency. Use after editing skills, upgrading the plugin, or when a skill behaves unexpectedly."
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw runner dumps — summarize.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Tier 2 behavioral runs and any git push are skipped under `RDC_TEST=1`; Tier 1 static lint runs normally.
+
+
+# rdc:self-test — Skill Library Self-Test (Tier 1)
+
+## When to Use
+- Before every `rdc:release rdc-skills` tag push
+- After editing any skill description or frontmatter
+- When a skill mysteriously disappears from the menu (backtick bug repro)
+- In CI on every rdc-skills PR (once wired)
+
+## Tiers
+
+| Tier | What it checks | Status |
+|------|----------------|--------|
+| Tier 1 | Static lint — frontmatter, Usage line, referenced files, name match | ✅ live |
 | Tier 2 | Behavioral — headless Claude or Codex runs each skill in sandbox, asserts artifacts | ✅ live — 30 manifests; acceptance harness records transcripts, tool calls, artifacts, and lessons learned |
-| Tier 3 | Golden checklists — snapshot output format, regress on drift | 🔒 future |
-
-## Interactive UI
-
-Launch the interactive menu — pick tier, pick skill, see live output:
-
-```bash
+| Tier 3 | Golden checklists — snapshot output format, regress on drift | 🔒 future |
+
+## Interactive UI
+
+Launch the interactive menu — pick tier, pick skill, see live output:
+
+```bash
 node {RDC_SKILLS_ROOT}/scripts/self-test-ui.mjs
-```
-
-Menu options:
-- **1** — Full Tier 1 test (all skills)
-- **2** — Pick a specific skill from a numbered list
-- **3** — Choose tier (Tier 1 static lint | Tier 2 behavioral | Tier 3 🔒 future)
-
-Test output streams live to the terminal. No server, no extra processes.
-
-## Procedure (Tier 1)
-
-1. **Run the linter (direct or via UI):**
-   ```bash
+```
+
+Menu options:
+- **1** — Full Tier 1 test (all skills)
+- **2** — Pick a specific skill from a numbered list
+- **3** — Choose tier (Tier 1 static lint | Tier 2 behavioral | Tier 3 🔒 future)
+
+Test output streams live to the terminal. No server, no extra processes.
+
+## Procedure (Tier 1)
+
+1. **Run the linter (direct or via UI):**
+   ```bash
    node {RDC_SKILLS_ROOT}/scripts/self-test.mjs
-   # or interactively:
+   # or interactively:
    node {RDC_SKILLS_ROOT}/scripts/self-test-ui.mjs
-   ```
-
-2. **Interpret exit codes:**
-   - `0` = all skills pass
-   - `1` = at least one FAIL or (in `--strict` mode) at least one WARN
-   - `2` = runner itself crashed (e.g., skills dir unreadable)
-   - `3` = `.claude-plugin/plugin.json` missing entirely (distinct from skill failures)
-
-3. **Common findings and fixes:**
-
-   | Finding code | Cause | Fix |
-   |---|---|---|
-   | `description-backtick-leading` | Folded YAML starts with `` ` `` — parser drops skill | Rewrite description to start with a word |
-   | `usage-marker-missing` | No `` Usage `rdc:name <args>` `` in description | Front-load arg contract |
-   | `usage-marker-mismatch` | `Usage` line references a different skill's name (copy-paste drift) | Fix the skill name in the Usage marker |
-   | `name-filename-mismatch` | frontmatter `name:` ≠ filename | `--fix` auto-renames; or rewrite name |
-   | `guide-not-found` / `rule-not-found` / `hook-not-found` | Dead reference in skill body | Create file or fix link |
-   | `banner-missing` | Skill missing OUTPUT CONTRACT banner | `--fix` auto-inserts |
-   | `manifest-missing` / `manifest-version-mismatch` | `.claude-plugin/plugin.json` missing or out-of-sync with `package.json` | Create/update manifest |
-   | `duplicate-skill-name` / `skill-guide-filename-collision` | Two skills claim same name, or skill collides with agent guide | Rename one |
-   | `orphan-hook` | File under `hooks/` isn't referenced by any skill, settings.json, or plugin.json | Wire it up or delete |
-
-4. **Flags:**
-   - `--strict` — promotes warnings to failures (use in CI and before release)
-   - `--skill <name>` — run against a single skill (e.g. `--skill rdc:build`)
-   - `--json` — machine-readable schema v2 (per-skill `findings[]` with `code` + `level`, plugin_manifest block, global_findings, summary.exit_code). Consumed by Tier 2 runner as pre-gate.
-   - `--fix` — auto-repair fixable findings: insert missing OUTPUT CONTRACT banner, rename files to match frontmatter name. Prints `FIXED:` lines + touched file list so you can git diff + commit. Backtick-leading descriptions are NOT auto-fixed (need human rewrite).
-
-5. **Report to the project lead:**
-   ```
-   Self-test: X/Y pass, Z warnings, W failures
-   Failures: <list>
-   Verdict: PASS | FAIL
-   ```
-
-## Procedure (Tier 2)
-
+   ```
+
+2. **Interpret exit codes:**
+   - `0` = all skills pass
+   - `1` = at least one FAIL or (in `--strict` mode) at least one WARN
+   - `2` = runner itself crashed (e.g., skills dir unreadable)
+   - `3` = `.claude-plugin/plugin.json` missing entirely (distinct from skill failures)
+
+3. **Common findings and fixes:**
+
+   | Finding code | Cause | Fix |
+   |---|---|---|
+   | `description-backtick-leading` | Folded YAML starts with `` ` `` — parser drops skill | Rewrite description to start with a word |
+   | `usage-marker-missing` | No `` Usage `rdc:name <args>` `` in description | Front-load arg contract |
+   | `usage-marker-mismatch` | `Usage` line references a different skill's name (copy-paste drift) | Fix the skill name in the Usage marker |
+   | `name-filename-mismatch` | frontmatter `name:` ≠ filename | `--fix` auto-renames; or rewrite name |
+   | `guide-not-found` / `rule-not-found` / `hook-not-found` | Dead reference in skill body | Create file or fix link |
+   | `banner-missing` | Skill missing OUTPUT CONTRACT banner | `--fix` auto-inserts |
+   | `manifest-missing` / `manifest-version-mismatch` | `.claude-plugin/plugin.json` missing or out-of-sync with `package.json` | Create/update manifest |
+   | `duplicate-skill-name` / `skill-guide-filename-collision` | Two skills claim same name, or skill collides with agent guide | Rename one |
+   | `orphan-hook` | File under `hooks/` isn't referenced by any skill, settings.json, or plugin.json | Wire it up or delete |
+
+4. **Flags:**
+   - `--strict` — promotes warnings to failures (use in CI and before release)
+   - `--skill <name>` — run against a single skill (e.g. `--skill rdc:build`)
+   - `--json` — machine-readable schema v2 (per-skill `findings[]` with `code` + `level`, plugin_manifest block, global_findings, summary.exit_code). Consumed by Tier 2 runner as pre-gate.
+   - `--fix` — auto-repair fixable findings: insert missing OUTPUT CONTRACT banner, rename files to match frontmatter name. Prints `FIXED:` lines + touched file list so you can git diff + commit. Backtick-leading descriptions are NOT auto-fixed (need human rewrite).
+
+5. **Report to the project lead:**
+   ```
+   Self-test: X/Y pass, Z warnings, W failures
+   Failures: <list>
+   Verdict: PASS | FAIL
+   ```
+
+## Procedure (Tier 2)
+
 Tier 2 runs each skill end-to-end in an isolated sandbox and asserts on observed state (files touched, commits made, work items, exit code). Build acceptance additionally records all observable engine events/tool calls, assistant output, stdout/stderr artifacts, lessons learned, and next build optimizations. It supports `--engine claude` and `--engine codex`; both engines use the same manifests, worktree sandbox, JSONL evidence, and Markdown report. Use it before shipping behavioral changes — Tier 1 alone can't catch runtime drift.
-
-1. **Prerequisites:**
+
+1. **Prerequisites:**
    - `claude` CLI on PATH for Claude runs (headless mode: `claude --print`)
    - `codex` CLI on PATH for Codex runs (headless mode: `codex exec --json`)
-   - clauth daemon unlocked (`curl -s http://127.0.0.1:52437/ping`)
-   - Supabase MCP reachable (runner creates a throwaway test branch)
-   - Clean git tree in `rdc-skills` (worktrees are added under `.rdc/sandbox/<run-id>/`)
-
-2. **Run:**
+   - clauth daemon unlocked (`curl -s http://127.0.0.1:52437/ping`)
+   - Supabase MCP reachable (runner creates a throwaway test branch)
+   - Clean git tree in `rdc-skills` (worktrees are added under `.rdc/sandbox/<run-id>/`)
+
+2. **Run:**
    ```bash
    node scripts/self-test.mjs --tier2                    # all skills with manifests
    node scripts/self-test.mjs --tier2 --skill rdc:build  # single skill
@@ -103,30 +103,30 @@ Tier 2 runs each skill end-to-end in an isolated sandbox and asserts on observed
    node scripts/acceptance.mjs --skill rdc:build         # build acceptance with JSONL/tool-call evidence
    node scripts/acceptance.mjs --engine codex --skill rdc:build
    ```
-
-3. **What it does:**
-   - Runs Tier 1 as a pre-gate (fails fast if static lint fails)
-   - Creates one Supabase test branch for the run
+
+3. **What it does:**
+   - Runs Tier 1 as a pre-gate (fails fast if static lint fails)
+   - Creates one Supabase test branch for the run
    - For each skill: `git worktree add` into `.rdc/sandbox/<run-id>/<skill>/`, sets `RDC_TEST=1`, invokes the selected headless engine with the skill prompt, waits for exit
    - Asserts per the skill's manifest: exit code, files touched, commits made, stdout patterns
    - Build acceptance writes JSONL evidence and extracts tool calls from the engine stream
    - Cleans up worktrees + deletes the Supabase branch at the end (even on failure)
-
-4. **Reports:**
+
+4. **Reports:**
    - `.rdc/reports/self-test-tier2-<iso>.json` — full per-skill result, findings, timings
    - `.rdc/reports/acceptance-*.jsonl` and `.rdc/reports/acceptance-*.md` — build acceptance evidence, transcript artifact pointers, lessons learned, and next build optimizations
    - Exit codes: `0` pass, `1` fail (one or more skills failed assertions), `2` runner error (couldn't set up sandbox / branch)
-
-5. **Adding a new manifest:**
-   - Create `skills/tests/<skill>.test.json` (one per skill, colocated)
-   - Validate the shape against the schema at `scripts/lib/manifest-schema.mjs`
-   - Test it in isolation: `node scripts/self-test.mjs --tier2 --skill rdc:name`
-   - Commit the manifest alongside any skill body changes
-
-## Rules
-- Run Tier 1 **before every `rdc:release rdc-skills`** — it catches the backtick-drift class of bugs that break the skill menu silently.
-- Use `--strict` in CI. Warnings matter in the release path.
-- Do NOT skip findings by relaxing the linter. Fix the skill.
-- Run Tier 2 before tagging a release. Gate the tag if any manifested skill fails.
+
+5. **Adding a new manifest:**
+   - Create `skills/tests/<skill>.test.json` (one per skill, colocated)
+   - Validate the shape against the schema at `scripts/lib/manifest-schema.mjs`
+   - Test it in isolation: `node scripts/self-test.mjs --tier2 --skill rdc:name`
+   - Commit the manifest alongside any skill body changes
+
+## Rules
+- Run Tier 1 **before every `rdc:release rdc-skills`** — it catches the backtick-drift class of bugs that break the skill menu silently.
+- Use `--strict` in CI. Warnings matter in the release path.
+- Do NOT skip findings by relaxing the linter. Fix the skill.
+- Run Tier 2 before tagging a release. Gate the tag if any manifested skill fails.
 - Headless sessions must not steal focus. The runner uses hidden process launch options where supported; if windows flash or focus is grabbed, inspect `scripts/lib/runner.mjs` before changing skill behavior.
 - If Tier 2 tests fail with `exit_code: -1`, verify the runner still passes `--dangerously-skip-permissions` and sets `RDC_TEST=1`.