@lifeaitools/rdc-skills 0.9.37 → 0.10.0

package/guides/publish-md-spec.md

@@ -0,0 +1,289 @@
+---
+type: spec
+role: publish-md
+systems: [deploy, release, plan]
+schema_version: "1.0"
+tags: [publish-md, spec, rdc-skills]
+---
+# PUBLISH.md — Authoritative Specification
+> Version: 1.0 | Effective: 2026-05-22
+> Architectural approval: 2026-05-22 interview (Option A — Full Rollout)
+
+Every deployable target in the RDC ecosystem MAY carry a `PUBLISH.md` file
+in its root directory. Skills that deploy, release, and plan read this file
+to derive watch paths, surface metadata, and promotion gates.
+
+---
+
+## Schema
+
+A `PUBLISH.md` file consists of two parts:
+
+1. **YAML frontmatter** — app-level metadata, bounded by `---` delimiters.
+2. **One or more surface sections** — per-surface metadata, bounded by
+   HTML comment markers (`<!-- SURFACE:<name> -->` … `<!-- /SURFACE:<name> -->`).
+
+Frontmatter is authoritative. Surface sections are the publish manifest.
+
+---
+
+## Frontmatter Fields
+
+All fields are required unless marked optional.
+
+```yaml
+---
+schema_version: "1.0"          # (required) always "1.0" for this revision
+entity_slug: <slug>            # (required) matches app_deployments.app_slug
+artifact_type: <type>          # (required) one of: website | api | package | worker | mcp-server
+environments: [dev]            # (required) array; subset of: dev, prod
+status: active                 # (required) one of: active | draft | deprecated
+notes: ""                      # (optional) free-text, ignored by validator
+---
+```
+
+### Field Reference
+
+| Field | Type | Required | Allowed Values |
+|-------|------|----------|---------------|
+| `schema_version` | string | yes | `"1.0"` |
+| `entity_slug` | string | yes | must match `app_deployments.app_slug` |
+| `artifact_type` | string | yes | `website` · `api` · `package` · `worker` · `mcp-server` |
+| `environments` | string[] | yes | subset of `[dev, prod]`; at least one required |
+| `status` | string | yes | `active` · `draft` · `deprecated` |
+| `notes` | string | no | free-text annotation |
+
+#### `environments` semantics
+
+- `[dev]` — surface is only available on the PM2 dev server
+- `[prod]` — surface is only available on the Coolify production instance
+- `[dev, prod]` — surface exists in both tiers
+
+The validator enforces: each value in `environments` must match an
+`app_deployments.environment` row for the same `entity_slug`.
+
+#### `status` semantics
+
+- `active` — `rdc:release` promotion is allowed
+- `draft` — `rdc:release` will block and print a warning; dev deploy is allowed
+- `deprecated` — `rdc:release` will block; validator flags as warn
+
+---
+
+## Surface Sections
+
+Each deployable surface gets one managed section inside the PUBLISH.md body.
+Sections are bounded by HTML comment markers so skills can read and rewrite
+them without clobbering hand-authored prose.
+
+```
+<!-- SURFACE:<name> -->
+path: /
+source_dir: apps/baru-website
+build_type: nextjs
+visibility: public
+cache: no-store
+watch_paths:
+  - apps/baru-website/**
+  - packages/ui/**
+  - packages/supabase/**
+<!-- /SURFACE:<name> -->
+```
+
+### Surface Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `path` | string | yes | URL path prefix served by this surface (e.g. `/`, `/api`) |
+| `source_dir` | string | yes | Monorepo-relative path to the source directory |
+| `build_type` | string | yes | `nextjs` · `static` · `docker` · `node` · `edge` |
+| `visibility` | string | yes | `public` · `private` · `internal` |
+| `cache` | string | yes | HTTP cache directive: `no-store` · `immutable` · `stale-while-revalidate` · `max-age=N` |
+| `watch_paths` | string[] | yes | gitignore-style globs; at least one required. These are unioned to derive Coolify `watch_paths`. |
+| `artifact_id` | string | no | Stable ID for `artifact_registry` upserts; defaults to `<entity_slug>/<name>` |
+
+### `<name>` convention
+
+The surface name appears in the comment markers and must be a short,
+lowercase, hyphen-separated identifier that describes the surface:
+
+- `website` — primary web UI
+- `api` — REST/GraphQL API
+- `mcp` — Model Context Protocol server endpoint
+- `worker` — background worker or cron
+- `static` — purely static asset serving
+
+Multiple surfaces are allowed per file (e.g. a Next.js app that also exposes
+an API surface under `/api`).
+
+---
+
+## Environments Array
+
+The top-level `environments` field declares which deployment tiers host this app.
+Each surface inherits the app-level `environments` unless overridden at the
+surface level (not supported in schema v1.0 — planned for v1.1).
+
+Validator enforcement:
+1. At least one environment must be declared.
+2. Each declared environment must be one of `dev` or `prod`.
+3. Each declared environment must have a corresponding `app_deployments` row for the `entity_slug`.
+
+`rdc:deploy` uses `environments` to determine whether a dev or prod deploy is
+appropriate for the given target. `rdc:release` requires `prod` to be present
+before promoting.
+
+---
+
+## Opt-out (File Absence)
+
+**PUBLISH.md absence = opt-out.** There is no sentinel field, no `publish: false`.
+
+A deployable target without a `PUBLISH.md`:
+- Is skipped by `rdc:deploy`'s watch-paths derivation step.
+- Is NOT inserted into `artifact_registry` on deploy.
+- Is flagged as a **warn** (not fail) by the validator during the Option A rollout period.
+- Will become a **fail** once the rollout is complete (controlled by the `--strict` flag on the validator).
+
+Packages and libraries that are not independently deployed (e.g. `@regen/ui`)
+do not require a `PUBLISH.md`. Only targets with a row in `app_deployments` are in scope.
+
+---
+
+## Validator Contract
+
+The validator (`scripts/validate-publish-manifests.js`) operates in two modes:
+
+### Warn mode (default, during rollout)
+
+In warn mode the validator:
+- Queries `app_deployments` for all `status = 'active'` rows.
+- For each row, checks whether a `PUBLISH.md` exists at the expected path.
+- For rows without `PUBLISH.md`: emits a `WARN` line and continues.
+- For rows WITH `PUBLISH.md`: parses YAML frontmatter and validates all required fields.
+- If frontmatter is invalid (missing required field, bad enum value): emits a `FAIL` line.
+- Exits 0 if there are no `FAIL` lines (warns are non-fatal in this mode).
+
+### Strict mode (`--strict`)
+
+In strict mode:
+- Missing `PUBLISH.md` is treated as `FAIL`, not `WARN`.
+- Exits non-zero if any registered active app is missing a manifest.
+- Used in CI after Option A rollout is complete.
+
+### Field validation rules
+
+| Check | Fail condition |
+|-------|---------------|
+| `schema_version` present | missing or not `"1.0"` |
+| `entity_slug` present | missing or empty string |
+| `artifact_type` present | missing or not in allowed set |
+| `environments` present | missing, empty array, or contains unknown value |
+| `status` present | missing or not in allowed set |
+| At least one surface section | no `<!-- SURFACE: -->` markers found |
+| `watch_paths` non-empty | surface section has no `watch_paths` entries |
+
+---
+
+## Consumer Skills
+
+### `rdc:deploy`
+
+Reads PUBLISH.md during the deploy pre-flight step:
+
+1. Locates `PUBLISH.md` in the app's `source_dir`.
+2. Parses YAML frontmatter — fails deploy if invalid.
+3. Unions all `watch_paths` across surface sections.
+4. Updates `app_deployments.watch_paths` with the union.
+5. After a successful deploy, calls `storeArtifact` (INSERT into `artifact_registry`) for each surface section.
+
+If `PUBLISH.md` is absent, `rdc:deploy` skips steps 2–5 and proceeds with the deploy without watch-path derivation.
+
+### `rdc:release`
+
+Reads PUBLISH.md during the promotion pre-flight gate:
+
+1. Locates `PUBLISH.md` in the app's `source_dir`.
+2. Checks `status` field — blocks promotion if `status != "active"`.
+3. Checks `environments` array — blocks promotion if `prod` is not declared.
+4. If checks pass, proceeds with Coolify promotion.
+
+### `rdc:plan`
+
+When scaffolding a new app, reads the `PUBLISH.md.template` from
+`scaffold/templates/` and hydrates it with the app's metadata to produce
+a starter `PUBLISH.md` in the new app directory.
+
+---
+
+## Example PUBLISH.md — baru-website
+
+```markdown
+---
+schema_version: "1.0"
+entity_slug: baru-website
+artifact_type: website
+environments: [dev]
+status: active
+notes: "Baru.dev — reference implementation for PUBLISH.md convention"
+---
+
+# baru-website
+
+<!-- SURFACE:website -->
+path: /
+source_dir: apps/baru-website
+build_type: nextjs
+visibility: public
+cache: no-store
+watch_paths:
+  - apps/baru-website/**
+  - packages/ui/**
+  - packages/supabase/**
+<!-- /SURFACE:website -->
+```
+
+---
+
+## Example PUBLISH.md — regen-media MCP server
+
+```markdown
+---
+schema_version: "1.0"
+entity_slug: regen-media
+artifact_type: mcp-server
+environments: [dev, prod]
+status: active
+notes: "Regen Media MCP — R2 image library, Flux/MJ generation, embeddings"
+---
+
+# regen-media
+
+<!-- SURFACE:mcp -->
+path: /mcp
+source_dir: mcp-servers/regen-media
+build_type: docker
+visibility: internal
+cache: no-store
+watch_paths:
+  - mcp-servers/regen-media/**
+<!-- /SURFACE:mcp -->
+
+<!-- SURFACE:api -->
+path: /api
+source_dir: mcp-servers/regen-media
+build_type: docker
+visibility: private
+cache: no-store
+watch_paths:
+  - mcp-servers/regen-media/**
+<!-- /SURFACE:api -->
+```
+
+---
+
+## Changelog
+
+| Version | Date | Change |
+|---------|------|--------|
+| 1.0 | 2026-05-22 | Initial spec — OQ-1/OQ-2/OQ-3 resolved; Option A Full Rollout approved |

package/hooks/check-cwd.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
-// Hard blocks session if CWD is not the regen-root project directory.
+// Hard blocks session if CWD is not the expected project directory.
 // Exits with code 1 to fail the hook + outputs a blocking systemMessage.
 
 const { execSync } = require('child_process');
 const hookLog = require('./hook-logger');
 const cwd     = process.cwd().replace(/\\/g, '/');
 
-let expected = 'regen-root';
+let expected = process.env.RDC_PROJECT_SCOPE || 'regen-root';
 try {
   expected = execSync('git rev-parse --show-toplevel', { encoding: 'utf8', stdio: 'pipe' })
     .trim().replace(/\\/g, '/');
 } catch (_) {}
 
-if (!cwd.endsWith('regen-root')) {
+if (!cwd.endsWith(expected)) {
   hookLog('check-cwd', 'SessionStart', 'block', { cwd, expected });
   process.stdout.write(JSON.stringify({
     systemMessage:

package/hooks/no-stop-open-epics.js

@@ -5,7 +5,7 @@
  * Fires on every Stop event where Claude decided to end_turn.
  * Queries get_open_epics() via Supabase REST.
  * Only blocks if epics with status=todo exist — in_progress means another session owns them.
- * Only fires in the regen-root project (scope guard on event.cwd).
+ * Only fires in the configured project scope (scope guard on event.cwd).
  *
  * Exit codes:
  *   0 = allow stop
@@ -15,8 +15,9 @@
  *   NEXT_PUBLIC_SUPABASE_URL=https://<ref>.supabase.co
  *   NEXT_PUBLIC_SUPABASE_ANON_KEY=<key>
  *
- * PROJECT SCOPE in package.json or plugin config:
- *   "hookScope": "regen-root"   ← folder name that must appear in event.cwd
+ * PROJECT SCOPE:
+ *   RDC_PROJECT_SCOPE=<folder-name>   folder name that must appear in event.cwd
+ *   RDC_PROJECT_ROOT=<path>           root used to find .rdc/overnight.lock and .env.local
  */
 
 const fs = require('fs');
@@ -24,11 +25,12 @@ const path = require('path');
 
 // ── Config — override these per project ──────────────────────────────────────
 
-const PROJECT_SCOPE = 'regen-root'; // only block in sessions inside this folder name
-const OVERNIGHT_SENTINEL = 'C:/Dev/regen-root/.rdc/overnight.lock'; // only fire when this exists
+const PROJECT_SCOPE = process.env.RDC_PROJECT_SCOPE || 'regen-root'; // LIFEAI default; override per project
+const PROJECT_ROOT = process.env.RDC_PROJECT_ROOT || process.cwd();
+const OVERNIGHT_SENTINEL = process.env.RDC_OVERNIGHT_LOCK || path.join(PROJECT_ROOT, '.rdc', 'overnight.lock');
 const ENV_PATHS = [
-  'C:/Dev/regen-root/apps/rdc-marketing-engine/.env.local',
-  'C:/Dev/regen-root/.env.local',
+  ...(process.env.RDC_ENV_PATHS ? process.env.RDC_ENV_PATHS.split(path.delimiter) : []),
+  path.join(PROJECT_ROOT, '.env.local'),
 ];
 const SUPABASE_URL = process.env.SUPABASE_URL || readEnvVar('NEXT_PUBLIC_SUPABASE_URL');
 

package/hooks/require-work-item-on-commit.js

@@ -18,10 +18,11 @@
 
 const fs      = require('fs');
 const path    = require('path');
+const os      = require('os');
 const hookLog = require('./hook-logger');
 
 const MARKER_FILE = path.join(
-  process.env.USERPROFILE || process.env.HOME || 'C:/Users/DaveLadouceur',
+  process.env.USERPROFILE || process.env.HOME || os.homedir(),
   '.claude',
   'fixit.marker'
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.9.37",
+  "version": "0.10.0",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
@@ -19,15 +19,23 @@
     "type": "plugin",
     "skills": "skills/",
     "guides": "guides/",
-    "version": "0.9.37",
+    "version": "0.10.0",
     "commands": "commands/"
   },
+  "bin": {
+    "rdc-skills-install": "scripts/install-rdc-skills.js",
+    "rdc-skills-self-test": "scripts/self-test.mjs"
+  },
   "scripts": {
     "install-rdc-skills": "node scripts/install-rdc-skills.js",
     "uninstall:win": "powershell -ExecutionPolicy Bypass -File scripts/uninstall.ps1",
     "uninstall:unix": "bash scripts/uninstall.sh",
     "validate": "node tests/validate-skills.js",
     "rdc-design": "node scripts/rdc-design-cli.mjs",
-    "test:hooks": "node scripts/test-rdc-hooks.mjs"
+    "test:hooks": "node scripts/test-rdc-hooks.mjs",
+    "prepack": "node scripts/validate-publish-manifests.js --mode warn || true && node scripts/validate-place-histories.js --mode warn || true"
+  },
+  "devDependencies": {
+    "yaml": "^2.9.0"
   }
 }

package/scaffold/templates/HISTORY.md.template

@@ -0,0 +1,39 @@
+---
+schema_version: "1.0"
+prt_slug: "PRT_SLUG"
+project_type: PROJECT_TYPE
+location:
+  county: LOCATION_COUNTY
+  state: LOCATION_STATE
+  country: LOCATION_COUNTRY
+  parcel_apn: PARCEL_APN
+  area_acres: AREA_ACRES
+  centroid: [LAT, LNG]
+acquired: "ACQUIRED_DATE"
+steward: STEWARD_NAME
+research_status: draft
+last_reviewed: "LAST_REVIEWED_DATE"
+contributors: []
+---
+
+> This is a draft stub. Research pending. Status will be promoted to in-research once primary sources are identified.
+
+## Land lineage
+
+TODO: Research land lineage of PROJECT_NAME. Cover indigenous stewardship, land grants, ownership transitions, and government survey references (PLSS township/range/section).
+
+## Stewardship transitions
+
+TODO: Document major ownership and use transitions for PROJECT_NAME from earliest recorded title to present. Include conservation easements, deed restrictions, and use-change inflection points.
+
+## Ecological context
+
+TODO: Document the ecoregion, watershed, soil classifications (NRCS Web Soil Survey), vegetation communities, water resources, wildlife corridors, and fire history for PROJECT_NAME.
+
+## Cultural significance
+
+TODO: Research indigenous place names and cultural associations, historic structures, archaeological sites, community significance (grazing allotments, water rights, access traditions), and scenic values for PROJECT_NAME.
+
+## Regulatory record
+
+TODO: Document zoning, conservation easements, water rights adjudications, federal and state permits, tax status, and any open title or lien issues of record for PROJECT_NAME.

package/scaffold/templates/PUBLISH.md.template

@@ -0,0 +1,21 @@
+---
+schema_version: "1.0"
+entity_slug: "ENTITY_SLUG"
+artifact_type: "ARTIFACT_TYPE"
+environments: [dev]
+status: draft
+notes: ""
+---
+
+# ENTITY_SLUG
+
+<!-- SURFACE:website -->
+path: /
+source_dir: SOURCE_DIR
+build_type: BUILD_TYPE
+visibility: public
+cache: no-store
+watch_paths:
+  - SOURCE_DIR/**
+  - packages/ui/**
+<!-- /SURFACE:website -->

package/scripts/install-rdc-skills.js

@@ -766,8 +766,12 @@ async function main() {
   console.log('');
 
   if (!fs.existsSync(claudeHome)) {
-    fail(`CLAUDE_HOME not found: ${claudeHome}`);
-    process.exit(1);
+    fs.mkdirSync(claudeHome, { recursive: true });
+    warn(`CLAUDE_HOME did not exist — created ${claudeHome}`);
+  }
+  if (!fs.existsSync(settingsPath)) {
+    writeJson(settingsPath, {});
+    info(`       created settings.json`);
   }
 
   // Read version + git SHA once