@lifeaitools/rdc-skills 0.37.2 → 0.37.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.37.2",
+  "version": "0.37.4",
   "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight unattended builds with work-item tracking and TDD enforcement.",
   "author": {
     "name": "LIFEAI",

package/clauth-plugin.json

@@ -1,7 +1,7 @@
 {
   "schema": "lifeai.plugin.v1",
   "id": "rdc-skills",
-  "version": "0.37.2",
+  "version": "0.37.4",
   "publisher": "LIFEAI",
   "core": false,
   "documentation": {

package/git-sha.json

@@ -1,3 +1,3 @@
 {
-  "sha": "c22b3e63abdb2c8628348bd436077688b1243b41"
+  "sha": "7174da1ee88b03b186bfc102a951ac2f770aec6c"
 }

package/guides/lessons-learned-spec.md

@@ -35,7 +35,7 @@ propose-rule for one domain. This generalizes that pattern fleet-wide.
 
 ### Why lessons are not files any more
 
-Until 2026-09 every lesson was a markdown file in the capturing repository's
+Until 2026-09-17 every lesson was a markdown file in the capturing repository's
 `.rdc/lessons/`. A census of one repository found 315 of them: 157 already enforced in code,
 where the file only repeated what a guard or test already guaranteed, and 32 enforced
 nowhere, sitting in a directory the owner of the fix never reads. A lesson filed where it
@@ -48,6 +48,13 @@ So the record now follows the fix:
 - **An unencoded lesson is a GitHub issue in the repository the fix belongs to**, labelled
   `lesson` + `proposal`. **An issue proposes; a work item commits.**
 
+### Retired on-disk log
+
+The old lesson log and its `.session-*.done` sentinels were retired from the active
+regen-root tree by `247571602` on 2026-09-17. They remain recoverable from Git history;
+they are not a conversion backlog and must not be recreated. The active record is now the
+owning-repository lesson issue, its work item when accepted, and the enforcing commit.
+
 ---
 
 ## When to capture (at skill exit)
@@ -218,9 +225,8 @@ the command exits 1. Treat that as an incomplete triage, never as "no lessons th
      API/MCP changes, skill-contract changes affecting multiple skills). When unsure, it is
      architectural.
 3. Route per the mode below.
-4. Work the conversion backlog (§ Existing `.rdc/lessons/` files) with whatever capacity is left.
-5. Summarize in the housekeeping report: open / recurred / accepted / closed-fixed /
-   closed-won't-fix counts with issue URLs, plus backlog files converted and remaining.
+4. Summarize in the housekeeping report: open / recurred / accepted / closed-fixed /
+   closed-won't-fix counts with issue URLs.
 
 ### Attended mode (default — a human is present)
 
@@ -255,17 +261,13 @@ reason, is the audit trail.
 
 ---
 
-## Existing `.rdc/lessons/` files — the conversion backlog
-
-Files written under the old procedure are retired by state: an encoded lesson's file is
-deleted and links to it point at the enforcing artifact; an unencoded one becomes an issue in
-its owning repository. **The files that remain — doc-only lessons and product lessons — are a
-backlog to convert, not a place to capture.** Each is done when a guard or test carries it:
-ship that artifact, point any live link at it, and delete the file in the same commit.
+## Historical records and archive policy
 
-Housekeeping lists the remaining `.rdc/lessons/*.md` files for exactly that purpose and
-reports the count converted and remaining. Nothing new is written there: a new lesson — a
-doc-only one included — is an issue (§ Capture procedure).
+Do not create, scan, or modify `.rdc/lessons/` as part of normal capture or triage. The
+retired files are preserved by Git history. Lesson issues are also never deleted: a closed
+issue retains its evidence, comments, labels, and linked commit and can be reopened if the
+lesson recurs. Close an issue only after the fixing commit lands or with a clear won't-fix /
+duplicate reason; leave an unaccepted `proposal` issue open as the active queue.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.37.2",
+  "version": "0.37.4",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
@@ -19,7 +19,7 @@
     "type": "plugin",
     "skills": "skills/",
     "guides": "guides/",
-    "version": "0.37.2",
+    "version": "0.37.4",
     "commands": "commands/"
   },
   "bin": {

package/scripts/rdc-release.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Commit and tag one declared release change set.
+ *
+ * The wrapper owns the only documented commit/tag path so the staged-path
+ * guard runs while there is still something to reject.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+function fail(message) {
+  process.stderr.write(`rdc-release: ${message}\n`);
+  process.exit(2);
+}
+
+function git(repo, args, options = {}) {
+  return execFileSync('git', args, { cwd: repo, encoding: 'utf8', ...options });
+}
+
+function readArgs(argv) {
+  const result = { allow: [], dryRun: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--dry-run') {
+      result.dryRun = true;
+      continue;
+    }
+    if (!['--repo', '--allow', '--message', '--tag'].includes(arg)) fail(`unknown argument ${arg}`);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) fail(`${arg} requires a value`);
+    index += 1;
+    if (arg === '--allow') result.allow.push(value);
+    else result[arg.slice(2)] = value;
+  }
+  return result;
+}
+
+function normalizedPath(value) {
+  const normalized = value.replaceAll('\\', '/');
+  if (!normalized || path.posix.isAbsolute(normalized) || normalized.split('/').includes('..')) {
+    fail(`--allow must be a repository-relative path: ${value}`);
+  }
+  return normalized.replace(/^\.\//, '');
+}
+
+const options = readArgs(process.argv.slice(2));
+if (!options.repo || !options.message || !options.tag || options.allow.length === 0) {
+  fail('usage: rdc-release --repo <path> --allow <path> [--allow <path>] --message <message> --tag <tag> [--dry-run]');
+}
+
+const repo = path.resolve(options.repo);
+try {
+  git(repo, ['rev-parse', '--is-inside-work-tree']);
+} catch {
+  fail(`not a Git worktree: ${repo}`);
+}
+
+const allowed = new Set(options.allow.map(normalizedPath));
+// A rename is two release-relevant paths: the removed source and the added
+// destination. Disable Git's similarity presentation so neither can disappear
+// behind a single destination path in the allowlist check.
+const staged = git(repo, ['diff', '--cached', '--no-renames', '--name-only', '-z'])
+  .split('\0')
+  .filter(Boolean)
+  .map((value) => value.replaceAll('\\', '/'));
+if (staged.length === 0) fail('no staged release paths; run this before committing');
+
+const stagedSet = new Set(staged);
+const undeclared = staged.filter((file) => !allowed.has(file));
+const missing = [...allowed].filter((file) => !stagedSet.has(file));
+if (undeclared.length || missing.length) {
+  const details = [
+    undeclared.length ? `undeclared staged path(s): ${undeclared.join(', ')}` : null,
+    missing.length ? `declared path(s) not staged: ${missing.join(', ')}` : null,
+  ].filter(Boolean);
+  fail(details.join('; '));
+}
+
+const tagCheck = spawnSync('git', ['check-ref-format', `refs/tags/${options.tag}`], { cwd: repo, encoding: 'utf8' });
+if (tagCheck.status !== 0) fail(`invalid tag: ${options.tag}`);
+const existingTag = spawnSync('git', ['rev-parse', '--verify', '--quiet', `refs/tags/${options.tag}`], { cwd: repo, encoding: 'utf8' });
+if (existingTag.status === 0) fail(`tag already exists: ${options.tag}`);
+
+if (options.dryRun) {
+  process.stdout.write(`rdc-release: dry-run passed for ${staged.length} declared path(s); would commit and tag ${options.tag}\n`);
+  process.exit(0);
+}
+
+git(repo, ['commit', '-m', options.message], { stdio: 'inherit' });
+git(repo, ['tag', options.tag], { stdio: 'inherit' });
+process.stdout.write(`rdc-release: committed ${staged.length} declared path(s) and created ${options.tag}\n`);

package/skills/housekeeping/SKILL.md

@@ -185,11 +185,14 @@ When the weekly triage runs unattended, follow `.rdc/guides/lessons-learned-spec
 - **architectural with a single clear correct fix** (records an already-learned lesson — e.g. "add a gate", "encode X as a test") → accept, route through `rdc:plan` → `rdc:build` (or `rdc:fixit` if genuinely <5 files).
 - **architectural and genuinely ambiguous** (multiple valid approaches, real tradeoffs) → write a `human_items` row (`item_type='decision'`, with options in `suggested_agent_prompt`, `source_type='lesson'`, `source_fingerprint` = the issue URL for dedupe), accept the issue against a linked `work_item`. Decided in the morning. This is the asynchronous equivalent of the attended interview and honors `.claude/rules/architectural-change-approval.md`.
 
-### Conversion backlog — remaining lesson files
-
-List the lesson files still in the project (`.rdc/lessons/*.md`: doc-only and product lessons from before issues). They are a backlog to convert, not a place to capture: with the capacity left after the issues, pick files and encode each as a guard or test, point any live link at that artifact, and delete the file in the same commit (spec § Existing `.rdc/lessons/` files). Nothing new is written there — a new lesson, doc-only included, is an issue.
-
-Issues are closed, never deleted — a closed issue with its fixing commit or won't-fix reason is the audit trail. Report open / recurred / accepted / closed-fixed / closed-won't-fix counts with issue URLs, and backlog files converted / remaining, in the housekeeping report.
+### Retired lesson log
+
+Do not scan, recreate, or convert `.rdc/lessons/*.md`. The on-disk log and its sentinels
+were retired from the active tree by regen-root commit `247571602`; Git history preserves
+them for recovery. New and unresolved lessons live as owning-repository `lesson` + `proposal`
+issues. Issues are closed, never deleted — a closed issue with its fixing commit or won't-fix
+reason is the archive. Report open / recurred / accepted / closed-fixed / closed-won't-fix
+counts with issue URLs in the housekeeping report.
 
 ## Rules
 - Never run `pnpm build` — not needed for this audit

package/skills/release/SKILL.md

@@ -118,13 +118,19 @@ Use repo-local package tooling when available. Examples:
 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
+node scripts/rdc-release.mjs --repo <repo-path> \
+  --allow package.json --allow package-lock.json \
+  --message "chore(release): vA.B.C" --tag vA.B.C
 git push origin HEAD
 git push origin vA.B.C
 npm view <package-name> version
 ```
 
+The wrapper owns this documented commit-and-tag step. It compares the exact
+staged paths with the declared `--allow` set and refuses undeclared or missing
+paths before creating either a commit or a tag. Use `--dry-run` to prove the
+set without mutating the repository.
+
 Never use `--force` or bypass hooks. If a hook fails, fix the cause.
 
 ## ⛔ Standalone-repo staging guard (no `git add -A`)
@@ -136,11 +142,11 @@ doc-sync/scope guard to catch contamination. In them:
   (`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 (retired lesson 2026-06-08-release-git-add-all-swept-untracked-wip). Same
-  dirty-tree contamination class as a lockfile generated against a dirty tree.
+- **Release-scope guard: run `scripts/rdc-release.mjs` before committing. Refuse
+  undeclared staged paths before creating the commit or tag.** A broad add swept
+  4 pre-existing untracked skill files into a tagged release that CI published
+  before anyone noticed (retired 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
 

package/skills/rpms-filemap/SKILL.cloud.md

@@ -91,7 +91,7 @@ If you are touching an entity, read its generated `_context.md` before any local
 | `operational-door.rdc.plans` | `.rdc/areas/**/{plans,research,reports,decisions,logs,arch,guides}/**` | `authored` | One Home Per Fact, One Direction | `allow_declared_home`<br />`path_conformance` | RDC planning workflow | `active` |
 | `operational-door.rdc.plans.compatibility` | `.rdc/plans/**` | `generated` | One Home Per Fact, One Direction | `allow_declared_home`<br />`path_conformance`<br />Retire only through the approved area-first-v1 activation receipt. | RDC path migration compiler | `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.rdc.lesson-issues` | `GitHub: owning repository issues labelled lesson` | `stateful` | One Direction, One Home Per Fact | `rdc-lesson submit/accept/close`<br />`issue labels: proposal -> accepted -> closed` | 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

package/skills/rpms-filemap/SKILL.md

@@ -97,7 +97,7 @@ If you are touching an entity, read its generated `_context.md` before any local
 | `operational-door.rdc.plans` | `.rdc/areas/**/{plans,research,reports,decisions,logs,arch,guides}/**` | `authored` | One Home Per Fact, One Direction | `allow_declared_home`<br />`path_conformance` | RDC planning workflow | `active` |
 | `operational-door.rdc.plans.compatibility` | `.rdc/plans/**` | `generated` | One Home Per Fact, One Direction | `allow_declared_home`<br />`path_conformance`<br />Retire only through the approved area-first-v1 activation receipt. | RDC path migration compiler | `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.rdc.lesson-issues` | `GitHub: owning repository issues labelled lesson` | `stateful` | One Direction, One Home Per Fact | `rdc-lesson submit/accept/close`<br />`issue labels: proposal -> accepted -> closed` | 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

package/tests/release-guard.test.mjs

@@ -0,0 +1,93 @@
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { test } from 'node:test';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPT = path.join(ROOT, 'scripts', 'rdc-release.mjs');
+
+function git(repo, args) {
+  return execFileSync('git', args, { cwd: repo, encoding: 'utf8' });
+}
+
+function fixture() {
+  const repo = mkdtempSync(path.join(tmpdir(), 'rdc-release-guard-'));
+  git(repo, ['init']);
+  git(repo, ['config', 'user.email', 'test@example.invalid']);
+  git(repo, ['config', 'user.name', 'Release Guard Test']);
+  writeFileSync(path.join(repo, 'README.md'), 'base\n');
+  git(repo, ['add', 'README.md']);
+  git(repo, ['commit', '-m', 'base']);
+  return { repo, cleanup: () => rmSync(repo, { recursive: true, force: true }) };
+}
+
+function run(repo, args) {
+  return spawnSync(process.execPath, [SCRIPT, '--repo', repo, ...args], { encoding: 'utf8' });
+}
+
+test('release guard rejects an extra staged path and creates no tag', (t) => {
+  const sandbox = fixture();
+  t.after(sandbox.cleanup);
+  writeFileSync(path.join(sandbox.repo, 'package.json'), '{"version":"1.0.1"}\n');
+  writeFileSync(path.join(sandbox.repo, 'unrelated.md'), 'do not ship\n');
+  git(sandbox.repo, ['add', 'package.json', 'unrelated.md']);
+
+  const result = run(sandbox.repo, ['--allow', 'package.json', '--message', 'release: v1.0.1', '--tag', 'v1.0.1']);
+  assert.equal(result.status, 2, result.stderr);
+  assert.match(result.stderr, /undeclared staged path\(s\): unrelated\.md/);
+  assert.equal(git(sandbox.repo, ['tag', '--list']).trim(), '');
+  assert.equal(git(sandbox.repo, ['log', '--format=%s', '-1']).trim(), 'base');
+});
+
+test('release guard rejects a rename whose removed source is not declared', (t) => {
+  const sandbox = fixture();
+  t.after(sandbox.cleanup);
+  git(sandbox.repo, ['mv', 'README.md', 'package.json']);
+
+  const result = run(sandbox.repo, ['--allow', 'package.json', '--message', 'release: v1.0.1', '--tag', 'v1.0.1']);
+  assert.equal(result.status, 2, result.stderr);
+  assert.match(result.stderr, /undeclared staged path\(s\): README\.md/);
+  assert.equal(git(sandbox.repo, ['tag', '--list']).trim(), '');
+  assert.equal(git(sandbox.repo, ['log', '--format=%s', '-1']).trim(), 'base');
+});
+
+test('release guard rejects a declared path that was not staged', (t) => {
+  const sandbox = fixture();
+  t.after(sandbox.cleanup);
+  writeFileSync(path.join(sandbox.repo, 'package.json'), '{"version":"1.0.1"}\n');
+  git(sandbox.repo, ['add', 'package.json']);
+
+  const result = run(sandbox.repo, ['--allow', 'package.json', '--allow', 'README.md', '--message', 'release: v1.0.1', '--tag', 'v1.0.1']);
+  assert.equal(result.status, 2, result.stderr);
+  assert.match(result.stderr, /declared path\(s\) not staged: README\.md/);
+  assert.equal(git(sandbox.repo, ['tag', '--list']).trim(), '');
+  assert.equal(git(sandbox.repo, ['log', '--format=%s', '-1']).trim(), 'base');
+});
+
+test('release guard commits and tags only the declared staged set', (t) => {
+  const sandbox = fixture();
+  t.after(sandbox.cleanup);
+  writeFileSync(path.join(sandbox.repo, 'package.json'), '{"version":"1.0.1"}\n');
+  git(sandbox.repo, ['add', 'package.json']);
+
+  const result = run(sandbox.repo, ['--allow', 'package.json', '--message', 'release: v1.0.1', '--tag', 'v1.0.1']);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(git(sandbox.repo, ['tag', '--list']).trim(), 'v1.0.1');
+  assert.deepEqual(git(sandbox.repo, ['diff-tree', '--no-commit-id', '--name-only', '-r', 'HEAD']).trim().split('\n'), ['package.json']);
+});
+
+test('release guard dry-run validates the exact set without committing or tagging', (t) => {
+  const sandbox = fixture();
+  t.after(sandbox.cleanup);
+  writeFileSync(path.join(sandbox.repo, 'package.json'), '{"version":"1.0.1"}\n');
+  git(sandbox.repo, ['add', 'package.json']);
+
+  const result = run(sandbox.repo, ['--allow', 'package.json', '--message', 'release: v1.0.1', '--tag', 'v1.0.1', '--dry-run']);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /dry-run passed/);
+  assert.equal(git(sandbox.repo, ['tag', '--list']).trim(), '');
+  assert.equal(git(sandbox.repo, ['status', '--short']).trim(), 'A  package.json');
+});

package/tests/release-skill-contract.test.mjs

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const skill = readFileSync(path.join(ROOT, 'skills', 'release', 'SKILL.md'), 'utf8');
+
+test('release skill routes the scoped commit and tag through the executable guard', () => {
+  assert.match(skill, /node scripts\/rdc-release\.mjs --repo <repo-path>/);
+  assert.match(skill, /--allow package\.json --allow package-lock\.json/);
+  assert.match(skill, /staged paths.*before creating either a commit or a tag/is);
+});