@lifeaitools/rdc-skills 0.24.37 → 0.24.39

package/skills/rdc-extract-verifier-rules/SKILL.md

@@ -1,191 +1,191 @@
----
-name: rdc-extract-verifier-rules
-version: 0.1.0
-description: |
-  Read recent enhancement-log entries, cluster failures by pattern, generate candidate verifier rules, test them against the known-good corpus and the failure corpus, and propose pull requests adding the highest-confidence rules to forbidden-patterns.json. Use this skill on a nightly cadence (3 AM PT), or manually when the user says "extract verifier rules", "promote enhancement log", "what new rules should we add", or after a significant brochure run produced many failures.
-triggers:
-  - "rdc:extract-verifier-rules"
-  - "extract verifier rules"
-  - "promote enhancement log"
-  - "what new rules should we add"
-  - "verifier corpus update"
-  - nightly cron at 3:00 AM PT
----
-
-# rdc:extract-verifier-rules
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Return candidate rules, evidence, and PR status directly; do not dump raw tool logs.
-
-The self-learning loop. The verifier corpus is the moat (per `DECISIONS-LOG.md` D-009). This skill is how the corpus grows.
-
-## What it does
-
-1. Read `enhancement-log.jsonl` entries since last run timestamp
-2. Cluster entries by fingerprint similarity + reason text
-3. For each cluster with `N >= 3` occurrences:
-   - Generate a candidate regex or AST pattern
-   - Test the pattern against the **known-good corpus** (last 100 successful brochures) for false positives
-   - Test the pattern against the **failure cluster** for recall
-   - If false-positive rate = 0 AND recall ≥ 80%, mark as `propose`
-4. For each `propose` candidate:
-   - Open a PR on `regen-root` adding the rule to `verifiers/forbidden-patterns.json`
-   - Auto-merge if confidence ≥ 95% AND a maintainer's auto-merge flag is enabled
-   - Otherwise, await human review
-5. Write a markdown summary to `.rdc/reports/verifier-{YYYY-MM-DD}.md`
-
-## Cluster algorithm
-
-Two-stage clustering:
-
-**Stage 1 — Fingerprint clustering:**
-- Each enhancement-log entry has an `input_fingerprint` (sha256 of the offending JSX block)
-- Entries with identical fingerprints cluster trivially (same exact mistake)
-
-**Stage 2 — Semantic clustering:**
-- For unique fingerprints, embed the `reason` and `pattern` fields with `@xenova/transformers` (384-dim, local — no API)
-- Cosine similarity ≥ 0.85 → same cluster
-- Use HDBSCAN with min_samples=3 to identify real clusters vs. noise
-
-## Candidate rule generation
-
-For each cluster, generate one of:
-
-### Regex candidate
-- Take all `pattern` strings in the cluster
-- Find common substring or template
-- Generalize literal values to character classes
-- Validate the regex is well-formed and not catastrophic
-
-Example:
-```
-Cluster patterns:
-  <div className="flex flex-col gap-4">
-  <div className="flex flex-col gap-6">
-  <div className="flex flex-row items-center">
-
-Generated regex:
-  <div[^>]*className="[^"]*\\bflex\\b
-```
-
-### AST candidate
-- For cluster entries with rich AST context, build an AST query string
-- Test with @typescript-eslint/parser
-
-Example:
-```
-AST candidate:
-  JSXOpeningElement[name.name='div'] > JSXAttribute[name.name='className'] CallExpression[callee.name='clsx']
-```
-
-## False-positive check
-
-Run the candidate against the known-good corpus:
-- The 12 Phase 1 reference brochures
-- All design-partner brochures with `final_grade >= 85`
-- Any brochure tagged `corpus:reference` in Supabase
-
-If the candidate matches any known-good output → reject the candidate. False positives in the verifier corpus are unacceptable because they break working flows.
-
-## Recall check
-
-Run the candidate against the failure cluster:
-- Must match ≥ 80% of cluster entries
-- Below 80%, the candidate is too specific; widen and retry
-
-## PR generation
-
-For each promoted candidate, create a PR on `LIFEAI/regen-root`:
-
-```
-Title: [verifier-corpus] Add rule FP0{N} — {short description}
-
-Body:
-This rule was generated by rdc:extract-verifier-rules on {date}.
-
-**Cluster size:** {N} occurrences over {time span}
-**False positive rate:** {rate}
-**Recall:** {percent}
-
-**Sample failures:**
-{3-5 example enhancement-log entries}
-
-**Generated rule:**
-```json
-{rule JSON}
-```
-
-**Reviewer checklist:**
-- [ ] Verify the rule doesn't match any known-good brochure
-- [ ] Verify the suggested fix is reasonable
-- [ ] Confirm severity level
-- [ ] Confirm category
-
-Auto-merging: {yes/no based on confidence}
-```
-
-## Auto-merge policy
-
-Auto-merge if **all** are true:
-- False-positive rate = 0
-- Recall ≥ 95%
-- Cluster size ≥ 10
-- The rule pattern is a strict subset of an existing pattern (not a fundamentally new category)
-- A maintainer's auto-merge flag is enabled in `.rdc/config.json`
-
-Otherwise, await human review.
-
-## Output: nightly report
-
-`.rdc/reports/verifier-{YYYY-MM-DD}.md`:
-
-```markdown
-# Verifier Corpus Update — {date}
-
-## Summary
-
-- Enhancement log entries since last run: {N}
-- Clusters identified: {C}
-- Rules proposed: {R}
-- Rules auto-merged: {A}
-- Rules awaiting review: {W}
-
-## Top clusters
-
-| Cluster | Size | Pattern | Status |
-|---|---|---|---|
-| ...
-
-## Open PRs
-
-- #{N}: FP0{X} — {description}
-- ...
-
-## False-positive rejections
-
-Candidates that failed the known-good test:
-- {summary}
-
-## Corpus growth
-
-- Total rules in forbidden-patterns.json: {before} → {after}
-- Total component-allowlist entries: unchanged
-- Pagination rules: unchanged
-```
-
-## Manual invocation
-
-A maintainer can run this skill manually after a significant brochure run to immediately promote lessons learned:
-
-```
-rdc:extract-verifier-rules --since "2026-05-27" --auto-merge=false
-```
-
-The `--auto-merge=false` flag forces human review on all proposals regardless of confidence.
-
-## Why this matters
-
-The verifier corpus is the asset. Anyone can copy the kit. Anyone can copy the ESLint plugin. **Replicating 12 months of customer-tested failure patterns is the moat.** This skill is how that moat compounds. Every brochure run feeds it. Every nightly run grows it.
-
-After 12 months at moderate scale, the corpus will contain ~500-2,000 rules, calibrated against real customer documents, with each rule's hit count visible. New competitors entering this category will face a starting position 12 months behind.
-
-That is the point.
+---
+name: rdc-extract-verifier-rules
+version: 0.1.0
+description: |
+  Read recent enhancement-log entries, cluster failures by pattern, generate candidate verifier rules, test them against the known-good corpus and the failure corpus, and propose pull requests adding the highest-confidence rules to forbidden-patterns.json. Use this skill on a nightly cadence (3 AM PT), or manually when the user says "extract verifier rules", "promote enhancement log", "what new rules should we add", or after a significant brochure run produced many failures.
+triggers:
+  - "rdc:extract-verifier-rules"
+  - "extract verifier rules"
+  - "promote enhancement log"
+  - "what new rules should we add"
+  - "verifier corpus update"
+  - nightly cron at 3:00 AM PT
+---
+
+# rdc:extract-verifier-rules
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Return candidate rules, evidence, and PR status directly; do not dump raw tool logs.
+
+The self-learning loop. The verifier corpus is the moat (per `DECISIONS-LOG.md` D-009). This skill is how the corpus grows.
+
+## What it does
+
+1. Read `enhancement-log.jsonl` entries since last run timestamp
+2. Cluster entries by fingerprint similarity + reason text
+3. For each cluster with `N >= 3` occurrences:
+   - Generate a candidate regex or AST pattern
+   - Test the pattern against the **known-good corpus** (last 100 successful brochures) for false positives
+   - Test the pattern against the **failure cluster** for recall
+   - If false-positive rate = 0 AND recall ≥ 80%, mark as `propose`
+4. For each `propose` candidate:
+   - Open a PR on `regen-root` adding the rule to `verifiers/forbidden-patterns.json`
+   - Auto-merge if confidence ≥ 95% AND a maintainer's auto-merge flag is enabled
+   - Otherwise, await human review
+5. Write a markdown summary to `.rdc/reports/verifier-{YYYY-MM-DD}.md`
+
+## Cluster algorithm
+
+Two-stage clustering:
+
+**Stage 1 — Fingerprint clustering:**
+- Each enhancement-log entry has an `input_fingerprint` (sha256 of the offending JSX block)
+- Entries with identical fingerprints cluster trivially (same exact mistake)
+
+**Stage 2 — Semantic clustering:**
+- For unique fingerprints, embed the `reason` and `pattern` fields with `@xenova/transformers` (384-dim, local — no API)
+- Cosine similarity ≥ 0.85 → same cluster
+- Use HDBSCAN with min_samples=3 to identify real clusters vs. noise
+
+## Candidate rule generation
+
+For each cluster, generate one of:
+
+### Regex candidate
+- Take all `pattern` strings in the cluster
+- Find common substring or template
+- Generalize literal values to character classes
+- Validate the regex is well-formed and not catastrophic
+
+Example:
+```
+Cluster patterns:
+  <div className="flex flex-col gap-4">
+  <div className="flex flex-col gap-6">
+  <div className="flex flex-row items-center">
+
+Generated regex:
+  <div[^>]*className="[^"]*\\bflex\\b
+```
+
+### AST candidate
+- For cluster entries with rich AST context, build an AST query string
+- Test with @typescript-eslint/parser
+
+Example:
+```
+AST candidate:
+  JSXOpeningElement[name.name='div'] > JSXAttribute[name.name='className'] CallExpression[callee.name='clsx']
+```
+
+## False-positive check
+
+Run the candidate against the known-good corpus:
+- The 12 Phase 1 reference brochures
+- All design-partner brochures with `final_grade >= 85`
+- Any brochure tagged `corpus:reference` in Supabase
+
+If the candidate matches any known-good output → reject the candidate. False positives in the verifier corpus are unacceptable because they break working flows.
+
+## Recall check
+
+Run the candidate against the failure cluster:
+- Must match ≥ 80% of cluster entries
+- Below 80%, the candidate is too specific; widen and retry
+
+## PR generation
+
+For each promoted candidate, create a PR on `LIFEAI/regen-root`:
+
+```
+Title: [verifier-corpus] Add rule FP0{N} — {short description}
+
+Body:
+This rule was generated by rdc:extract-verifier-rules on {date}.
+
+**Cluster size:** {N} occurrences over {time span}
+**False positive rate:** {rate}
+**Recall:** {percent}
+
+**Sample failures:**
+{3-5 example enhancement-log entries}
+
+**Generated rule:**
+```json
+{rule JSON}
+```
+
+**Reviewer checklist:**
+- [ ] Verify the rule doesn't match any known-good brochure
+- [ ] Verify the suggested fix is reasonable
+- [ ] Confirm severity level
+- [ ] Confirm category
+
+Auto-merging: {yes/no based on confidence}
+```
+
+## Auto-merge policy
+
+Auto-merge if **all** are true:
+- False-positive rate = 0
+- Recall ≥ 95%
+- Cluster size ≥ 10
+- The rule pattern is a strict subset of an existing pattern (not a fundamentally new category)
+- A maintainer's auto-merge flag is enabled in `.rdc/config.json`
+
+Otherwise, await human review.
+
+## Output: nightly report
+
+`.rdc/reports/verifier-{YYYY-MM-DD}.md`:
+
+```markdown
+# Verifier Corpus Update — {date}
+
+## Summary
+
+- Enhancement log entries since last run: {N}
+- Clusters identified: {C}
+- Rules proposed: {R}
+- Rules auto-merged: {A}
+- Rules awaiting review: {W}
+
+## Top clusters
+
+| Cluster | Size | Pattern | Status |
+|---|---|---|---|
+| ...
+
+## Open PRs
+
+- #{N}: FP0{X} — {description}
+- ...
+
+## False-positive rejections
+
+Candidates that failed the known-good test:
+- {summary}
+
+## Corpus growth
+
+- Total rules in forbidden-patterns.json: {before} → {after}
+- Total component-allowlist entries: unchanged
+- Pagination rules: unchanged
+```
+
+## Manual invocation
+
+A maintainer can run this skill manually after a significant brochure run to immediately promote lessons learned:
+
+```
+rdc:extract-verifier-rules --since "2026-05-27" --auto-merge=false
+```
+
+The `--auto-merge=false` flag forces human review on all proposals regardless of confidence.
+
+## Why this matters
+
+The verifier corpus is the asset. Anyone can copy the kit. Anyone can copy the ESLint plugin. **Replicating 12 months of customer-tested failure patterns is the moat.** This skill is how that moat compounds. Every brochure run feeds it. Every nightly run grows it.
+
+After 12 months at moderate scale, the corpus will contain ~500-2,000 rules, calibrated against real customer documents, with each rule's hit count visible. New competitors entering this category will face a starting position 12 months behind.
+
+That is the point.

package/skills/release/SKILL.md

@@ -1,140 +1,140 @@
----
-name: rdc:release
-description: "Usage `rdc:release <repo> [version|--patch|--minor|--major|--dry-run]` — bump, commit, tag, push, wait for CI/publish, install, and verify a package or project using repo-local release metadata."
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw git/npm/CI dumps.
-> One checklist upfront, updated in place, shown again at end with 1-line verdict.
-
-> **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:release — Generic Release
-
-## When to Use
-
-- The user explicitly asks to release, publish, promote, ship, tag, or bump a repo.
-- A package or app needs versioning plus verification.
-- A repo provides release metadata in `package.json`, `.rdc/release.json`, README release instructions, or CI config.
-
-Never release without explicit user authorization.
-
-## Inputs
-
-- `rdc:release <repo>` — patch release by default.
-- `rdc:release <repo> <version>` — explicit version.
-- `rdc:release <repo> --patch|--minor|--major`
-- `rdc:release <repo> --dry-run`
-
-If `<repo>` is not resolvable from the current workspace, ask for its local path or GitHub slug.
-
-## Checklist
-
-```
-rdc:release: <repo> vX.Y.Z -> vA.B.C
-[ ] PUBLISH.md status gate: status=active AND prod in environments (block if not)
-[ ] Source path resolved
-[ ] Release metadata read
-[ ] Working tree clean or user-approved dirty scope identified
-[ ] Current version detected
-[ ] New version computed
-[ ] Dry-run gate handled
-[ ] Version files updated
-[ ] Tests/self-test passed
-[ ] Mandatory release code-review (pr-review-toolkit:code-reviewer on `git diff <last-released-tag>..HEAD`). Block release on `critical`/`high` findings; record `medium`/`low` in the release notes and proceed.
-[ ] Commit created
-[ ] Tag created
-[ ] Branch and tag pushed
-[ ] CI/publish status verified
-[ ] Registry/package/deploy target shows vA.B.C, if applicable
-[ ] Local install/update executed, if applicable
-[ ] Installed/runtime version verified
-[ ] Smoke test passed
-✅ rdc:release <repo>: vA.B.C live and verified
-```
-
-## PUBLISH.md Status Gate (Step 0 — before any production-touching step)
-
-Before touching any production system, read `PUBLISH.md` from the app root and validate promotion eligibility.
-
-```bash
-PUBLISH_MD="<monorepo_path>/PUBLISH.md"
-```
-
-**Block promotion if ANY of the following are true:**
-
-1. **PUBLISH.md is missing AND the app has a row in `app_deployments`** — emit warn and continue (during rollout period); becomes a hard block after Option A rollout is complete.
-2. **PUBLISH.md exists AND `status` field is NOT `active`** — hard block regardless of rollout status.
-   - `status: draft` → `BLOCKED: PUBLISH.md status=draft for <slug> — promote requires status=active`
-   - `status: deprecated` → `BLOCKED: PUBLISH.md status=deprecated for <slug> — promote requires status=active`
-3. **PUBLISH.md exists AND `environments` array does not include `prod`** → `BLOCKED: PUBLISH.md environments=[dev] for <slug> — prod must be declared before promotion`
-4. **Any required surface field is missing** (`source_dir` or `path` absent on any surface) → `BLOCKED: PUBLISH.md surface <id> missing required field for <slug>`
-
-If blocked, abort immediately with the message above. Do NOT proceed to the version bump, commit, or any Coolify call.
-
-If PUBLISH.md is absent and app has no `app_deployments` row (library/package), skip this gate.
-
-## Resolution Order
-
-1. Current repo if `<repo>` is `.` or omitted and the user clearly refers to the current workspace.
-2. Sibling directory matching `<repo>`.
-3. GitHub slug `<owner>/<repo>`.
-4. Repo-local `.rdc/release.json` if present.
-5. Ask for the missing path or release mechanism.
-
-## Generic Commands
-
-Use repo-local package tooling when available. Examples:
-
-```bash
-npm version patch --no-git-tag-version
-npm test
-git add package.json package-lock.json
-git commit -m "chore(release): vA.B.C"
-git tag vA.B.C
-git push origin HEAD
-git push origin vA.B.C
-npm view <package-name> version
-```
-
-Never use `--force` or bypass hooks. If a hook fails, fix the cause.
-
-## ⛔ Standalone-repo staging guard (no `git add -A`)
-
-Standalone repos (`rdc-skills`, `clauth`, `build-corpus`) have NO pre-commit
-doc-sync/scope guard to catch contamination. In them:
-
-- **REFUSE `git add -A` / `git add .`.** Stage explicit declared paths only
-  (`git add skills/<name>/SKILL.md package.json ...`).
-- Run `git status --porcelain` FIRST. If untracked files exist that are not part
-  of the declared change, STOP — list or stash them; do not sweep them in.
-- **Pre-tag guard: refuse to tag if `git diff --cached --name-only` includes any
-  path outside the declared change set.** A broad add swept 4 pre-existing
-  untracked skill files into a tagged release that CI published before anyone
-  noticed (lesson 2026-06-08-release-git-add-all-swept-untracked-wip). Same
-  dirty-tree contamination class as a lockfile generated against a dirty tree.
-
-## ⛔ Cross-platform prepack + verify the PUBLISHED tarball
-
-- **Prepack must be OS-agnostic.** A bash-style `prepack` chain (`node A || true && node B || true && node stamp`) short-circuits under Windows **cmd.exe** (npm runs lifecycle scripts via cmd, not bash; `true` is not a cmd builtin and `||`/`&&` evaluate differently), so an appended step silently never runs (lesson 2026-06-13-release-windows-cmd-prepack-shortcircuit). When a prepack step must run cross-platform, use a node wrapper / `shx` / `cross-env` — never rely on `|| true` shell semantics that differ between cmd and bash.
-- **Validate the PUBLISHED artifact, not a local Windows `npm pack`.** A local Windows `npm pack` is NOT a faithful rehearsal of the CI (ubuntu/bash) publish. After publish, verify the real tarball:
-  ```bash
-  npm pack <pkg>@<version>            # downloads the PUBLISHED tarball
-  tar -xzOf <pkg>-<version>.tgz package/<file>   # inspect the shipped file
-  ```
-  Confirm the published artifact carries what CI's prepack was supposed to stamp (e.g. `git_sha == tag commit`).
-
-## RDC Skills Package
-
-For this package, prefer the npm installer binary after publish:
-
-```bash
-npm install -g @lifeaitools/rdc-skills@latest
-rdc-skills-install --profile core
-```
-
-Use `--profile lifeai` only on a workstation that intentionally has the LIFEAI project layout and services.
-
-## 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>-release-<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.
+---
+name: rdc:release
+description: "Usage `rdc:release <repo> [version|--patch|--minor|--major|--dry-run]` — bump, commit, tag, push, wait for CI/publish, install, and verify a package or project using repo-local release metadata."
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw git/npm/CI dumps.
+> One checklist upfront, updated in place, shown again at end with 1-line verdict.
+
+> **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:release — Generic Release
+
+## When to Use
+
+- The user explicitly asks to release, publish, promote, ship, tag, or bump a repo.
+- A package or app needs versioning plus verification.
+- A repo provides release metadata in `package.json`, `.rdc/release.json`, README release instructions, or CI config.
+
+Never release without explicit user authorization.
+
+## Inputs
+
+- `rdc:release <repo>` — patch release by default.
+- `rdc:release <repo> <version>` — explicit version.
+- `rdc:release <repo> --patch|--minor|--major`
+- `rdc:release <repo> --dry-run`
+
+If `<repo>` is not resolvable from the current workspace, ask for its local path or GitHub slug.
+
+## Checklist
+
+```
+rdc:release: <repo> vX.Y.Z -> vA.B.C
+[ ] PUBLISH.md status gate: status=active AND prod in environments (block if not)
+[ ] Source path resolved
+[ ] Release metadata read
+[ ] Working tree clean or user-approved dirty scope identified
+[ ] Current version detected
+[ ] New version computed
+[ ] Dry-run gate handled
+[ ] Version files updated
+[ ] Tests/self-test passed
+[ ] Mandatory release code-review (pr-review-toolkit:code-reviewer on `git diff <last-released-tag>..HEAD`). Block release on `critical`/`high` findings; record `medium`/`low` in the release notes and proceed.
+[ ] Commit created
+[ ] Tag created
+[ ] Branch and tag pushed
+[ ] CI/publish status verified
+[ ] Registry/package/deploy target shows vA.B.C, if applicable
+[ ] Local install/update executed, if applicable
+[ ] Installed/runtime version verified
+[ ] Smoke test passed
+✅ rdc:release <repo>: vA.B.C live and verified
+```
+
+## PUBLISH.md Status Gate (Step 0 — before any production-touching step)
+
+Before touching any production system, read `PUBLISH.md` from the app root and validate promotion eligibility.
+
+```bash
+PUBLISH_MD="<monorepo_path>/PUBLISH.md"
+```
+
+**Block promotion if ANY of the following are true:**
+
+1. **PUBLISH.md is missing AND the app has a row in `app_deployments`** — emit warn and continue (during rollout period); becomes a hard block after Option A rollout is complete.
+2. **PUBLISH.md exists AND `status` field is NOT `active`** — hard block regardless of rollout status.
+   - `status: draft` → `BLOCKED: PUBLISH.md status=draft for <slug> — promote requires status=active`
+   - `status: deprecated` → `BLOCKED: PUBLISH.md status=deprecated for <slug> — promote requires status=active`
+3. **PUBLISH.md exists AND `environments` array does not include `prod`** → `BLOCKED: PUBLISH.md environments=[dev] for <slug> — prod must be declared before promotion`
+4. **Any required surface field is missing** (`source_dir` or `path` absent on any surface) → `BLOCKED: PUBLISH.md surface <id> missing required field for <slug>`
+
+If blocked, abort immediately with the message above. Do NOT proceed to the version bump, commit, or any Coolify call.
+
+If PUBLISH.md is absent and app has no `app_deployments` row (library/package), skip this gate.
+
+## Resolution Order
+
+1. Current repo if `<repo>` is `.` or omitted and the user clearly refers to the current workspace.
+2. Sibling directory matching `<repo>`.
+3. GitHub slug `<owner>/<repo>`.
+4. Repo-local `.rdc/release.json` if present.
+5. Ask for the missing path or release mechanism.
+
+## Generic Commands
+
+Use repo-local package tooling when available. Examples:
+
+```bash
+npm version patch --no-git-tag-version
+npm test
+git add package.json package-lock.json
+git commit -m "chore(release): vA.B.C"
+git tag vA.B.C
+git push origin HEAD
+git push origin vA.B.C
+npm view <package-name> version
+```
+
+Never use `--force` or bypass hooks. If a hook fails, fix the cause.
+
+## ⛔ Standalone-repo staging guard (no `git add -A`)
+
+Standalone repos (`rdc-skills`, `clauth`, `build-corpus`) have NO pre-commit
+doc-sync/scope guard to catch contamination. In them:
+
+- **REFUSE `git add -A` / `git add .`.** Stage explicit declared paths only
+  (`git add skills/<name>/SKILL.md package.json ...`).
+- Run `git status --porcelain` FIRST. If untracked files exist that are not part
+  of the declared change, STOP — list or stash them; do not sweep them in.
+- **Pre-tag guard: refuse to tag if `git diff --cached --name-only` includes any
+  path outside the declared change set.** A broad add swept 4 pre-existing
+  untracked skill files into a tagged release that CI published before anyone
+  noticed (lesson 2026-06-08-release-git-add-all-swept-untracked-wip). Same
+  dirty-tree contamination class as a lockfile generated against a dirty tree.
+
+## ⛔ Cross-platform prepack + verify the PUBLISHED tarball
+
+- **Prepack must be OS-agnostic.** A bash-style `prepack` chain (`node A || true && node B || true && node stamp`) short-circuits under Windows **cmd.exe** (npm runs lifecycle scripts via cmd, not bash; `true` is not a cmd builtin and `||`/`&&` evaluate differently), so an appended step silently never runs (lesson 2026-06-13-release-windows-cmd-prepack-shortcircuit). When a prepack step must run cross-platform, use a node wrapper / `shx` / `cross-env` — never rely on `|| true` shell semantics that differ between cmd and bash.
+- **Validate the PUBLISHED artifact, not a local Windows `npm pack`.** A local Windows `npm pack` is NOT a faithful rehearsal of the CI (ubuntu/bash) publish. After publish, verify the real tarball:
+  ```bash
+  npm pack <pkg>@<version>            # downloads the PUBLISHED tarball
+  tar -xzOf <pkg>-<version>.tgz package/<file>   # inspect the shipped file
+  ```
+  Confirm the published artifact carries what CI's prepack was supposed to stamp (e.g. `git_sha == tag commit`).
+
+## RDC Skills Package
+
+For this package, prefer the npm installer binary after publish:
+
+```bash
+npm install -g @lifeaitools/rdc-skills@latest
+rdc-skills-install --profile core
+```
+
+Use `--profile lifeai` only on a workstation that intentionally has the LIFEAI project layout and services.
+
+## 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>-release-<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.