@lifeaitools/rdc-skills 0.24.38 → 0.24.41

package/skills/rpms-filemap/SKILL.md

@@ -1,111 +1,111 @@
----
-name: rpms-filemap
-description: "Generated RPMS file map — RULE #1, canonical homes, and Context Export pointers served from regen-root manifest."
-slash: "rdc:rpms-filemap"
-category: "tooling"
-usage: "rdc:rpms-filemap"
-requires: []
-triggers:
-  - "rpms file map"
-  - "rule #1"
-  - "context export"
-  - "where does this file belong"
-  - "where should pm artifacts go"
----
-# RPMS File Map
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Return the requested file-map guidance directly; do not dump raw manifests or logs.
-
-> GENERATED FILE - DO NOT HAND-EDIT.
-> Source of truth: `docs/architecture/rpms.locations.json`
-> Regenerate: `pnpm rpms:gen-filemap`
-
-## RULE #1
-
-**Name the entity -> read its `_context.md` -> you are oriented.**
-
-The operational door is pinned in `docs/architecture/CONTEXT-EXPORT.md` and in RPMS section 8.1.
-If you are touching an entity, read its generated `_context.md` before any local reasoning, and never hand-edit that projection.
-
-## Pointers
-
-- RPMS section 6a: Asset lens and branch-store split
-- RPMS section 6b: Corpus disk layout
-- RPMS section 8.1: Session-start ritual and locked-decision read order
-
-## Canonical Map
-
-### Canonical Sources
-
-| Artifact | Home | RW | Law | Enforcement | Owner | Status |
-|----------|------|----|-----|-------------|-------|--------|
-| `canon.rpms.architecture` | `docs/architecture/regenerative-project-management-system.md` | `read_only` | One Home Per Fact, One Door | `block_wrong_home`<br />`path_conformance` | docs/architecture/regenerative-project-management-system.md | `active` |
-| `canon.context-export.single-door` | `docs/architecture/CONTEXT-EXPORT.md` | `read_only` | One Direction, One Door | `block_wrong_home`<br />`path_conformance` | docs/architecture/CONTEXT-EXPORT.md | `active` |
-
-### Session Start
-
-| Artifact | Home | RW | Law | Enforcement | Owner | Status |
-|----------|------|----|-----|-------------|-------|--------|
-| `session-start.claude-ai.root` | `CLAUDE.ai.md` | `read_only` | One Door | `block_wrong_home`<br />`path_conformance` | repo-root | `active` |
-| `session-start.claude.root` | `CLAUDE.md` | `read_only` | One Door | `block_wrong_home`<br />`path_conformance` | repo-root | `active` |
-| `session-start.decision.spine-lock` | `.rdc/plans/project-relationship-graph-approval.md` | `read_only` | One Spine, One Door | `block_wrong_home`<br />`path_conformance` | .rdc/plans/project-relationship-graph-approval.md | `active` |
-| `session-start.decision.cs2-lock` | `.rdc/plans/mdk-knowledge-decisions-and-workitems-2026-06-02.md` | `read_only` | One Direction, One Door | `block_wrong_home`<br />`path_conformance` | .rdc/plans/mdk-knowledge-decisions-and-workitems-2026-06-02.md | `active` |
-| `session-start.glossary.layer-model` | `docs/systems/cs2/LAYER-MODEL-AND-VOCABULARY.md` | `read_only` | One Door | `block_wrong_home`<br />`path_conformance` | docs/systems/cs2/LAYER-MODEL-AND-VOCABULARY.md | `active` |
-
-### Database Gates
-
-| Artifact | Home | RW | Law | Enforcement | Owner | Status |
-|----------|------|----|-----|-------------|-------|--------|
-| `session-start.work-items.queue` | `table:work_items via rpc:get_open_epics` | `rpc_only` | One Home Per Fact, One Door | `rpc_only`<br />`rpc_contract`<br />CRUD stays behind insert_work_item/update_work_item_status/update_checklist_item/submit_implementation_report. | public.work_items + RPC gate | `active` |
-
-### Place Corpus
-
-| Artifact | Home | RW | Law | Enforcement | Owner | Status |
-|----------|------|----|-----|-------------|-------|--------|
-| `session-start.entity-context.place` | `places/*/_context.md`<br />created_by: `apps/studio/src/lib/context-export-writer.ts` | `generated` | One Direction, One Door | `block_manual_edit`<br />`projection_drift` | context-export writer | `active` |
-| `place.identity.place-md` | `places/*/PLACE.md` | `authored` | One Home Per Fact, One Door | `allow_declared_home`<br />`path_conformance` | place stewards | `active` |
-| `place.history.history-md` | `places/*/HISTORY.md` | `append_only` | One Direction, One Home Per Fact | `allow_declared_home`<br />`path_conformance` | place stewards | `active` |
-| `place.corpus.index` | `places/*/corpus/INDEX.md` | `authored` | One Home Per Fact, One Door | `allow_declared_home`<br />`path_conformance` | place corpus | `active` |
-| `place.corpus.documents` | `places/*/corpus/**` | `authored` | One Home Per Fact | `block_binary_commit`<br />`binary_ban`<br />Text and markdown live here; binaries route to branch stores. | place corpus | `active` |
-| `place.artifacts.outputs` | `places/*/artifacts/**` | `generated` | One Direction | `allow_declared_home`<br />`path_conformance` | render pipelines | `active` |
-| `place.legacy.asset-bundles` | `places/*/*.assets/**` | `legacy_frozen` | One Direction, One Home Per Fact | `block_manual_edit`<br />`path_conformance`<br />Bridge-state allowlist for current repo reality; no new writes here. | legacy bridge until asset-lens migration | `active` |
-| `place.tracker.pm-docs` | `places/*/tracker/**` | `authored` | One Home Per Fact | `block_binary_commit`<br />`binary_ban` | place operators | `active` |
-
-### Shared Corpus
-
-| Artifact | Home | RW | Law | Enforcement | Owner | Status |
-|----------|------|----|-----|-------------|-------|--------|
-| `session-start.entity-context.project-node` | `corpus/_shared/*/_context.md`<br />created_by: `apps/studio/src/lib/context-export-writer.ts` | `generated` | One Direction, One Door | `block_manual_edit`<br />`projection_drift` | context-export writer | `active` |
-| `shared.index` | `corpus/_shared/*/INDEX.md` | `authored` | One Home Per Fact, One Door | `allow_declared_home`<br />`path_conformance` | shared corpus | `active` |
-| `shared.framework.documents` | `corpus/_shared/*/framework/**` | `authored` | One Home Per Fact | `block_binary_commit`<br />`binary_ban` | shared corpus | `active` |
-| `shared.research.documents` | `corpus/_shared/*/research/**` | `authored` | One Home Per Fact | `block_binary_commit`<br />`binary_ban` | shared corpus | `active` |
-| `shared.legacy.design-assets` | `corpus/_shared/*/design/**/assets/**` | `legacy_frozen` | One Direction, One Home Per Fact | `block_manual_edit`<br />`path_conformance`<br />Bridge-state allowlist for current repo reality; no new writes here. | legacy bridge until asset-lens migration | `active` |
-| `shared.corpus.documents` | `corpus/_shared/` | `authored` | One Home Per Fact | `block_binary_commit`<br />`binary_ban`<br />Generated _context.md remains separately governed by projection drift. | shared corpus | `active` |
-
-### Asset Lens
-
-| Artifact | Home | RW | Law | Enforcement | Owner | Status |
-|----------|------|----|-----|-------------|-------|--------|
-| `asset-lens.entity-assets.registry` | `table:entity_assets` | `deferred` | One Spine, One Home Per Fact | `deferred`<br />`deferred`<br />Manifest records the canonical home now; implementation remains deferred per plan section 6a E7. | RPMS E7 | `deferred` |
-
-### Operational Door
-
-| Artifact | Home | RW | Law | Enforcement | Owner | Status |
-|----------|------|----|-----|-------------|-------|--------|
-| `operational-door.rdc.plans` | `.rdc/plans/**` | `authored` | One Home Per Fact, One Direction | `allow_declared_home`<br />`path_conformance` | RDC planning workflow | `active` |
-| `operational-door.rdc.reports` | `.rdc/reports/**` | `generated` | One Direction | `allow_declared_home`<br />`path_conformance` | rdc:report | `active` |
-| `operational-door.rdc.lessons` | `.rdc/lessons/**` | `append_only` | One Direction, One Home Per Fact | `allow_declared_home`<br />`path_conformance` | RDC lesson capture workflow | `active` |
-| `operational-door.rpms-filemap.rule` | `.claude/rules/rpms-filemap.md`<br />created_by: `scripts/rpms/gen-filemap.ts` | `generated` | One Home Per Fact, One Direction, One Door | `block_manual_edit`<br />`projection_drift` | scripts/rpms/gen-filemap.ts | `active` |
-
-### App Guides
-
-| Artifact | Home | RW | Law | Enforcement | Owner | Status |
-|----------|------|----|-----|-------------|-------|--------|
-| `session-start.app-guide` | `apps/*/CLAUDE.md` | `read_only` | One Door | `block_wrong_home`<br />`path_conformance` | app-local architecture guides | `active` |
-
-## Projection Contract
-
-- Generated projections (`_context.md`, this rule) are never hand-edited.
-- Authored markdown stays in its declared home; do not create second homes elsewhere.
-- `work_items` stays RPC-only even when the location is documented here.
-- Corpus homes are text-first; binaries route to branch stores, not git under `places/` or `corpus/`.
+---
+name: rpms-filemap
+description: "Generated RPMS file map — RULE #1, canonical homes, and Context Export pointers served from regen-root manifest."
+slash: "rdc:rpms-filemap"
+category: "tooling"
+usage: "rdc:rpms-filemap"
+requires: []
+triggers:
+  - "rpms file map"
+  - "rule #1"
+  - "context export"
+  - "where does this file belong"
+  - "where should pm artifacts go"
+---
+# RPMS File Map
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Return the requested file-map guidance directly; do not dump raw manifests or logs.
+
+> GENERATED FILE - DO NOT HAND-EDIT.
+> Source of truth: `docs/architecture/rpms.locations.json`
+> Regenerate: `pnpm rpms:gen-filemap`
+
+## RULE #1
+
+**Name the entity -> read its `_context.md` -> you are oriented.**
+
+The operational door is pinned in `docs/architecture/CONTEXT-EXPORT.md` and in RPMS section 8.1.
+If you are touching an entity, read its generated `_context.md` before any local reasoning, and never hand-edit that projection.
+
+## Pointers
+
+- RPMS section 6a: Asset lens and branch-store split
+- RPMS section 6b: Corpus disk layout
+- RPMS section 8.1: Session-start ritual and locked-decision read order
+
+## Canonical Map
+
+### Canonical Sources
+
+| Artifact | Home | RW | Law | Enforcement | Owner | Status |
+|----------|------|----|-----|-------------|-------|--------|
+| `canon.rpms.architecture` | `docs/architecture/regenerative-project-management-system.md` | `read_only` | One Home Per Fact, One Door | `block_wrong_home`<br />`path_conformance` | docs/architecture/regenerative-project-management-system.md | `active` |
+| `canon.context-export.single-door` | `docs/architecture/CONTEXT-EXPORT.md` | `read_only` | One Direction, One Door | `block_wrong_home`<br />`path_conformance` | docs/architecture/CONTEXT-EXPORT.md | `active` |
+
+### Session Start
+
+| Artifact | Home | RW | Law | Enforcement | Owner | Status |
+|----------|------|----|-----|-------------|-------|--------|
+| `session-start.claude-ai.root` | `CLAUDE.ai.md` | `read_only` | One Door | `block_wrong_home`<br />`path_conformance` | repo-root | `active` |
+| `session-start.claude.root` | `CLAUDE.md` | `read_only` | One Door | `block_wrong_home`<br />`path_conformance` | repo-root | `active` |
+| `session-start.decision.spine-lock` | `.rdc/plans/project-relationship-graph-approval.md` | `read_only` | One Spine, One Door | `block_wrong_home`<br />`path_conformance` | .rdc/plans/project-relationship-graph-approval.md | `active` |
+| `session-start.decision.cs2-lock` | `.rdc/plans/mdk-knowledge-decisions-and-workitems-2026-06-02.md` | `read_only` | One Direction, One Door | `block_wrong_home`<br />`path_conformance` | .rdc/plans/mdk-knowledge-decisions-and-workitems-2026-06-02.md | `active` |
+| `session-start.glossary.layer-model` | `docs/systems/cs2/LAYER-MODEL-AND-VOCABULARY.md` | `read_only` | One Door | `block_wrong_home`<br />`path_conformance` | docs/systems/cs2/LAYER-MODEL-AND-VOCABULARY.md | `active` |
+
+### Database Gates
+
+| Artifact | Home | RW | Law | Enforcement | Owner | Status |
+|----------|------|----|-----|-------------|-------|--------|
+| `session-start.work-items.queue` | `table:work_items via rpc:get_open_epics` | `rpc_only` | One Home Per Fact, One Door | `rpc_only`<br />`rpc_contract`<br />CRUD stays behind insert_work_item/update_work_item_status/update_checklist_item/submit_implementation_report. | public.work_items + RPC gate | `active` |
+
+### Place Corpus
+
+| Artifact | Home | RW | Law | Enforcement | Owner | Status |
+|----------|------|----|-----|-------------|-------|--------|
+| `session-start.entity-context.place` | `places/*/_context.md`<br />created_by: `apps/studio/src/lib/context-export-writer.ts` | `generated` | One Direction, One Door | `block_manual_edit`<br />`projection_drift` | context-export writer | `active` |
+| `place.identity.place-md` | `places/*/PLACE.md` | `authored` | One Home Per Fact, One Door | `allow_declared_home`<br />`path_conformance` | place stewards | `active` |
+| `place.history.history-md` | `places/*/HISTORY.md` | `append_only` | One Direction, One Home Per Fact | `allow_declared_home`<br />`path_conformance` | place stewards | `active` |
+| `place.corpus.index` | `places/*/corpus/INDEX.md` | `authored` | One Home Per Fact, One Door | `allow_declared_home`<br />`path_conformance` | place corpus | `active` |
+| `place.corpus.documents` | `places/*/corpus/**` | `authored` | One Home Per Fact | `block_binary_commit`<br />`binary_ban`<br />Text and markdown live here; binaries route to branch stores. | place corpus | `active` |
+| `place.artifacts.outputs` | `places/*/artifacts/**` | `generated` | One Direction | `allow_declared_home`<br />`path_conformance` | render pipelines | `active` |
+| `place.legacy.asset-bundles` | `places/*/*.assets/**` | `legacy_frozen` | One Direction, One Home Per Fact | `block_manual_edit`<br />`path_conformance`<br />Bridge-state allowlist for current repo reality; no new writes here. | legacy bridge until asset-lens migration | `active` |
+| `place.tracker.pm-docs` | `places/*/tracker/**` | `authored` | One Home Per Fact | `block_binary_commit`<br />`binary_ban` | place operators | `active` |
+
+### Shared Corpus
+
+| Artifact | Home | RW | Law | Enforcement | Owner | Status |
+|----------|------|----|-----|-------------|-------|--------|
+| `session-start.entity-context.project-node` | `corpus/_shared/*/_context.md`<br />created_by: `apps/studio/src/lib/context-export-writer.ts` | `generated` | One Direction, One Door | `block_manual_edit`<br />`projection_drift` | context-export writer | `active` |
+| `shared.index` | `corpus/_shared/*/INDEX.md` | `authored` | One Home Per Fact, One Door | `allow_declared_home`<br />`path_conformance` | shared corpus | `active` |
+| `shared.framework.documents` | `corpus/_shared/*/framework/**` | `authored` | One Home Per Fact | `block_binary_commit`<br />`binary_ban` | shared corpus | `active` |
+| `shared.research.documents` | `corpus/_shared/*/research/**` | `authored` | One Home Per Fact | `block_binary_commit`<br />`binary_ban` | shared corpus | `active` |
+| `shared.legacy.design-assets` | `corpus/_shared/*/design/**/assets/**` | `legacy_frozen` | One Direction, One Home Per Fact | `block_manual_edit`<br />`path_conformance`<br />Bridge-state allowlist for current repo reality; no new writes here. | legacy bridge until asset-lens migration | `active` |
+| `shared.corpus.documents` | `corpus/_shared/` | `authored` | One Home Per Fact | `block_binary_commit`<br />`binary_ban`<br />Generated _context.md remains separately governed by projection drift. | shared corpus | `active` |
+
+### Asset Lens
+
+| Artifact | Home | RW | Law | Enforcement | Owner | Status |
+|----------|------|----|-----|-------------|-------|--------|
+| `asset-lens.entity-assets.registry` | `table:entity_assets` | `deferred` | One Spine, One Home Per Fact | `deferred`<br />`deferred`<br />Manifest records the canonical home now; implementation remains deferred per plan section 6a E7. | RPMS E7 | `deferred` |
+
+### Operational Door
+
+| Artifact | Home | RW | Law | Enforcement | Owner | Status |
+|----------|------|----|-----|-------------|-------|--------|
+| `operational-door.rdc.plans` | `.rdc/plans/**` | `authored` | One Home Per Fact, One Direction | `allow_declared_home`<br />`path_conformance` | RDC planning workflow | `active` |
+| `operational-door.rdc.reports` | `.rdc/reports/**` | `generated` | One Direction | `allow_declared_home`<br />`path_conformance` | rdc:report | `active` |
+| `operational-door.rdc.lessons` | `.rdc/lessons/**` | `append_only` | One Direction, One Home Per Fact | `allow_declared_home`<br />`path_conformance` | RDC lesson capture workflow | `active` |
+| `operational-door.rpms-filemap.rule` | `.claude/rules/rpms-filemap.md`<br />created_by: `scripts/rpms/gen-filemap.ts` | `generated` | One Home Per Fact, One Direction, One Door | `block_manual_edit`<br />`projection_drift` | scripts/rpms/gen-filemap.ts | `active` |
+
+### App Guides
+
+| Artifact | Home | RW | Law | Enforcement | Owner | Status |
+|----------|------|----|-----|-------------|-------|--------|
+| `session-start.app-guide` | `apps/*/CLAUDE.md` | `read_only` | One Door | `block_wrong_home`<br />`path_conformance` | app-local architecture guides | `active` |
+
+## Projection Contract
+
+- Generated projections (`_context.md`, this rule) are never hand-edited.
+- Authored markdown stays in its declared home; do not create second homes elsewhere.
+- `work_items` stays RPC-only even when the location is documented here.
+- Corpus homes are text-first; binaries route to branch stores, not git under `places/` or `corpus/`.

package/skills/self-test/SKILL.md

@@ -1,132 +1,132 @@
----
-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
-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
-   node {RDC_SKILLS_ROOT}/scripts/self-test.mjs
-   # 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)
-
-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:**
-   - `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:**
-   ```bash
-   node scripts/self-test.mjs --tier2                    # all skills with manifests
-   node scripts/self-test.mjs --tier2 --skill rdc:build  # single skill
-   node scripts/self-test.mjs --tier2 --parallel 3       # up to 3 skills in parallel
-   node scripts/self-test.mjs --tier2 --quick            # skip long-running assertions
-   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
-   - 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:**
-   - `.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.
-- 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`.
+---
+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
+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
+   node {RDC_SKILLS_ROOT}/scripts/self-test.mjs
+   # 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)
+
+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:**
+   - `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:**
+   ```bash
+   node scripts/self-test.mjs --tier2                    # all skills with manifests
+   node scripts/self-test.mjs --tier2 --skill rdc:build  # single skill
+   node scripts/self-test.mjs --tier2 --parallel 3       # up to 3 skills in parallel
+   node scripts/self-test.mjs --tier2 --quick            # skip long-running assertions
+   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
+   - 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:**
+   - `.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.
+- 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`.