@lifeaitools/rdc-skills 0.9.37 → 0.10.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.9.37",
+  "version": "0.9.38",
   "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/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## v0.9.38 — Clean-box npm install hardening
+
+### Fixed
+
+- **Fresh Claude home install.** The installer now creates `CLAUDE_HOME` and `settings.json` when they do not exist, so a first-time machine is not blocked before Claude has written config files.
+- **Public package portability.** Removed the most brittle user-machine paths from public skill docs and hooks, replacing them with `{PROJECT_ROOT}`, `{RDC_SKILLS_ROOT}`, or environment-derived paths.
+- **Hook path fallback.** Commit hygiene hooks now use the current OS home directory instead of a user-specific fallback path.
+
+### Added
+
+- **npm binaries.** `rdc-skills-install` and `rdc-skills-self-test` are exposed from the npm package for simpler clean-box installs.
+
+---
+
 ## v0.9.37 — RDC hook loop guard and behavior tests
 
 ### Fixed

package/commands/deploy.md

@@ -55,7 +55,7 @@ rdc:deploy: <slug> → <domain>
 ```
 rdc:deploy new: <slug>
 [ ] Registry entry loaded (or interactive create)
-[ ] DNS path chosen (A: *.dev.place.fund  B: apex  C: other zone)
+[ ] DNS path chosen (A: staging wildcard  B: apex  C: other zone)
 [ ] DNS record verified or wildcard confirmed
 [ ] Cloudflare proxy setting correct for DNS path
 [ ] server_uuid, project_uuid, environment_uuid, github_app_uuid resolved
@@ -103,7 +103,7 @@ rdc:deploy audit: fleet scan
 [ ] Env var drift (registry.env_vars_needed vs Coolify env)
 [ ] Branch mismatches (Coolify git_branch ≠ expected)
 [ ] Disk space on 64.237.54.189
-[ ] CF proxy misconfigs on *.dev.place.fund
+[ ] DNS/proxy misconfigs on configured staging wildcard
 [ ] Duplicate apps (same repo, multiple UUIDs)
 
 Findings:
@@ -127,7 +127,7 @@ There is no Coolify MCP server — do not reference `@masonator/coolify-mcp`.
 
 ```bash
 _COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
-curl -s -H "Authorization: Bearer $_COOLIFY" https://deploy.regendevcorp.com/api/v1/applications
+curl -s -H "Authorization: Bearer $_COOLIFY" "$DEPLOY_API_BASE/api/v1/applications"
 ```
 
 If clauth daemon is not responding:
@@ -143,7 +143,7 @@ BLOCKED: clauth daemon not responding. Run scripts\restart-clauth.bat, unlock at
   ```
   Server UUID:     ih386anenvvvn6fy1umtyow0
   Server IP:       64.237.54.189
-  Dashboard:       https://deploy.regendevcorp.com
+  Dashboard:       <deployment-dashboard-url>
   GitHub App UUID: xdmcy60putp5h9j7k4kwg9c3
   ```
 

package/commands/design.md

@@ -15,7 +15,7 @@ Use `skills/design/SKILL.md` as the source of truth.
 
 - Studio, Palette Library, brand-token, theme, component, or live-editor work
 - Any design task that must understand RDC's real token tables and Studio routes
-- UI critique, audit, polish, colorize, type, layout, or craft work in `regen-root`
+- UI critique, audit, polish, colorize, type, layout, or craft work in `{PROJECT_ROOT}`
 - Agent-side color-system exploration using Rampa CLI
 
 ## Arguments

package/commands/overnight.md

@@ -30,13 +30,13 @@ description: >-
 **First action — set the overnight sentinel** so the `no-stop-open-epics` Stop hook engages (interactive sessions are not gated by it):
 
 ```bash
-mkdir -p C:/Dev/regen-root/.rdc && touch C:/Dev/regen-root/.rdc/overnight.lock
+mkdir -p {PROJECT_ROOT}/.rdc && touch {PROJECT_ROOT}/.rdc/overnight.lock
 ```
 
 **Last action at end of run (success OR failure) — remove the sentinel:**
 
 ```bash
-rm -f C:/Dev/regen-root/.rdc/overnight.lock
+rm -f {PROJECT_ROOT}/.rdc/overnight.lock
 ```
 
 If the sentinel file does not exist, the Stop hook will NOT block — which means interactive sessions stop freely and only `rdc:overnight` is held to the "drain the queue" contract.

package/commands/release.md

@@ -1,159 +1,49 @@
 ---
-name: rdc:release
 description: >-
-  Atomic release. Usage `rdc:release <repo> [version]` or `rdc:release <repo> --patch|--minor|--major` or `rdc:release <repo> --dry-run` — bump, commit, tag, push, wait CI, install, verify, restart. Known repos: clauth, rdc-skills, regen-media, gws. No user handoff.
+  Atomic release. Usage `rdc:release <repo> [version]` or `rdc:release <repo> --patch|--minor|--major|--dry-run` — bump, commit, tag, push, wait CI/publish, install, and verify. Uses repo-local release metadata.
 ---
 
+# rdc:release — Generic Release
+
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw git/npm/CI dumps.
+> Checklist-only output. 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 (git tag push, CI poll, npm publish verification, global install, daemon restart) short-circuit under the flag — the checklist still runs, but each destructive step echoes `[RDC_TEST] skipping <step>` instead of mutating external state.
-
-# rdc:release — Atomic LIFEAI Package Release
-
-## Purpose
-
-Dave has Bash access. Therefore Dave should never be asked to run install
-commands. This skill handles the complete release loop for any LIFEAI-published
-package so the user sees one checklist and one verdict, not a series of "now run
-this" handoffs.
-
-## Arguments
-
-- `rdc:release <repo>` — patch bump (default), full loop
-- `rdc:release <repo> <version>` — explicit version (e.g. `1.6.0`)
-- `rdc:release <repo> --minor` | `--major` | `--patch` — semver bump
-- `rdc:release <repo> --dry-run` — show checklist and planned version, do nothing
-- `rdc:release` (no args) — list known repos, ask which
-
-## Known repos
-
-Resolve `<repo>` to source path + install mechanism:
-
-| Repo | Source path | Publish | Install | Post-install |
-|------|-------------|---------|---------|--------------|
-| `clauth` | `C:/Dev/clauth` | npm via tag → GitHub Actions | `npm install -g @lifeaitools/clauth@latest` | `curl -s -X POST http://127.0.0.1:52437/restart` |
-| `rdc-skills` | `C:/Dev/rdc-skills` | local (no npm) | `bash C:/Dev/rdc-skills/scripts/install.sh` + cp fallback | none |
-| `regen-media` | `C:/Dev/regen-root/mcp-servers/regen-media` | local | restart MCP server | none |
-| `gws` | `C:/Dev/regen-root/mcp-servers/gws` | local | restart MCP server | none |
-
-Add new repos to this table as they emerge. If user specifies an unknown repo,
-ask for the source path and install command.
-
-## Checklist (run every mode)
+## Checklist
 
 ```
-rdc:release: <repo> vX.Y.Z → vA.B.C
+rdc:release: <repo> vX.Y.Z -> vA.B.C
 [ ] Source path resolved
-[ ] Working tree clean (git status)
-[ ] Current version detected (package.json)
+[ ] Release metadata read
+[ ] Working tree clean or user-approved dirty scope identified
+[ ] Current version detected
 [ ] New version computed
-[ ] Dry-run gate (if --dry-run, stop here)
-[ ] package.json bumped (all version fields)
+[ ] Dry-run gate handled
+[ ] Version files updated
+[ ] Tests/self-test passed
 [ ] Commit created
-[ ] Tag vA.B.C created
-[ ] Push to origin
-[ ] Push --tags to origin
-[ ] CI run located (gh run list, if applicable)
-[ ] CI completed successfully (poll every 20s, 10min timeout)
-[ ] npm registry shows vA.B.C (if npm package, poll every 15s, 3min timeout)
-[ ] Local install executed
-[ ] Installed version verified matches vA.B.C
-[ ] Post-install action (daemon restart, etc., if applicable)
-[ ] Smoke test (ping health endpoint or binary --version)
-✅ rdc:release <repo>: vA.B.C live and installed
+[ ] 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
 ```
 
-## Execution details (silent to user — don't narrate)
+## Rules
 
-### 1. Version bump
-- Read `package.json`, parse version
-- Apply bump: patch (default), minor, major, or explicit
-- Rewrite all `version` fields (some packages have version in `claude.version` too)
+- Do not release without explicit user authorization.
+- Prefer repo-local release instructions in `.rdc/release.json`, README, package scripts, or CI workflows.
+- Never force push or bypass hooks.
+- Never declare success without verifying the installed or deployed version.
 
-### 2. Commit + tag + push
-```bash
-cd <source_path>
-git add package.json
-git commit -m "chore(release): vA.B.C"
-if [ "$RDC_TEST" != "1" ]; then
-  git tag vA.B.C
-  git push && git push --tags
-else
-  echo "[RDC_TEST] skipping git tag + git push --tags"
-fi
-```
-Never `--no-verify`. Never `--force`. If pre-commit hook fails, fix root cause, don't skip.
+## RDC Skills Package
 
-*Under `$RDC_TEST=1`, sections 3 (CI poll), 4 (npm registry poll), 5 (install), 6 (verify install), 7 (post-install), and 8 (smoke test) are also skipped — echo `[RDC_TEST] skipping <section>` for each and mark the checklist line as `[~]`.*
+After publishing this package to npm, a clean-box install should use:
 
-### 3. CI poll (for repos with GH Actions publish)
 ```bash
-# Locate the run triggered by the tag push
-gh run list --repo LIFEAI/<repo> --limit 5 --json status,conclusion,headBranch,databaseId
-# Poll its status field every 20s until conclusion ∈ {success, failure, cancelled}
-# Max 10 minutes — if timeout, fail with [!] and report run URL
+npm install -g @lifeaitools/rdc-skills@latest
+rdc-skills-install --profile core
 ```
-
-### 4. npm registry poll (only if published to npm)
-```bash
-npm view @lifeaitools/<repo> version
-# Poll every 15s until matches new version
-# Max 3 minutes — usually lands within 30-60s after CI success
-```
-
-### 5. Install
-- **clauth:** `npm install -g @lifeaitools/clauth@latest`
-- **rdc-skills:** `bash C:/Dev/rdc-skills/scripts/install.sh` — if output shows only one file copied (known bug), fall back to `cp C:/Dev/rdc-skills/skills/*.md ~/.claude/skills/user/ && cp C:/Dev/rdc-skills/skills/*.md C:/Dev/regen-root/.claude/skills/user/`
-- **MCP servers:** restart the server process (find its PID, kill, respawn — or document how)
-
-### 6. Verify install
-- **clauth:** `curl -s http://127.0.0.1:52437/ping | jq -r .app_version` — must equal new version
-- **rdc-skills:** `ls ~/.claude/skills/user/rdc-release.md` (or whichever file is new in this release) — must exist
-- **Global npm:** `npm list -g --depth=0 @lifeaitools/<repo>` — version matches
-
-### 7. Post-install
-- **clauth:** `curl -s -X POST http://127.0.0.1:52437/restart` — wait 3s — ping again
-- Others: N/A
-
-### 8. Smoke test
-- **clauth:** new tool roundtrip (e.g., `curl -s http://127.0.0.1:52437/get/openai | head -c 10` succeeds without error)
-- **rdc-skills:** load one new skill file and check frontmatter parses
-- **MCP:** server responds to `tools/list`
-
-## Failure modes → checklist outcome
-
-| Failure | Marker | Next |
-|---------|--------|------|
-| Dirty working tree | `[!]` line 2 | Abort with one-sentence diff summary; ask user to commit or stash |
-| Pre-commit hook fails | `[!]` line 7 | Fix root cause, re-stage, retry (NEVER --no-verify) |
-| CI fails | `[!]` line 11 | Print run URL, tail 20 lines of failing job, ask user |
-| npm doesn't register | `[!]` line 12 | Print npm error, check if CI actually published (not a silent skip) |
-| Install script broken | `[!]` line 13 | Fall back to manual cp; note the installer bug as a task |
-| Version mismatch after install | `[!]` line 14 | Uninstall + clean install; if still wrong, likely cache issue |
-| Post-install restart fails | `[!]` line 15 | Print ping error; instruct user to run `scripts\restart-clauth.bat` manually |
-
-Even on failure, show the full checklist with `[!]` markers so user sees exactly
-where it stopped.
-
-## Dry-run mode
-
-Prints the checklist + resolved version bump + every command that WOULD run, but
-executes nothing beyond reads. Use when user says "what would you do" or before
-risky major bumps.
-
-## Never
-
-- Never release on behalf of the user without an explicit `rdc:release` invocation
-- Never skip CI verification ("it'll probably work" is how stale installs happen)
-- Never `--force` push, never `--no-verify`, never `--no-gpg-sign`
-- Never touch `main` — release tags go on the default branch the repo uses (`master` for clauth, rdc-skills)
-- Never declare success without verifying the installed version matches
-
-## Related
-
-- `.claude/rules/clauth.md` — clauth release workflow source of truth
-- `feedback_version_bump_must_tag.md` (memory) — never bump without tagging
-- `feedback_clauth_ci.md` (memory) — CI publish pattern
-- `feedback_just_do_it.md` (memory) — don't hand commands to Dave; run them

package/commands/self-test.md

@@ -29,7 +29,7 @@ description: >-
 
 1. **Run the linter:**
    ```bash
-   node C:/Dev/rdc-skills/scripts/self-test.mjs
+   node {RDC_SKILLS_ROOT}/scripts/self-test.mjs
    ```
 
 2. **Interpret exit codes:**

package/commands/watch.md

@@ -24,7 +24,7 @@ description: >-
    ```bash
    node ${CLAUDE_PLUGIN_ROOT}/scripts/watch-init.mjs
    ```
-   (If `CLAUDE_PLUGIN_ROOT` is not set, resolve the plugin path from your invocation context. On Windows it's typically `C:/Dev/rdc-skills`.)
+   (If `CLAUDE_PLUGIN_ROOT` is not set, resolve the plugin path from your invocation context or the installed plugin cache.)
 
 2. **Parse the output.** The script prints `run_id`, `log_path`, `current`, `viewer`, and `open_hint`. Capture `log_path` and `viewer` for the rest of the session.
 

package/guides/agent-bootstrap.md

@@ -137,7 +137,7 @@ When `RDC_TEST=1` is set, the skill is running inside the Tier 2 sandbox harness
 **Bash pattern:**
 ```bash
 if [ "$RDC_TEST" != "1" ]; then
-  curl -X POST "https://deploy.regendevcorp.com/api/v1/applications/$UUID/deploy" ...
+  curl -X POST "$DEPLOY_API_BASE/api/v1/applications/$UUID/deploy" ...
 else
   echo "[RDC_TEST] skipping Coolify deploy"
 fi
@@ -156,7 +156,7 @@ if (process.env.RDC_TEST !== '1') {
 
 **New-skill contract:** every new `rdc:*` skill MUST honor `RDC_TEST` before shipping. Tier 2 manifests will fail any skill that writes to external state under the flag.
 
-**Known blocker:** The `check-cwd.js` SessionStart hook hard-blocks Claude sessions launched from `C:/Dev/rdc-skills`. The hook must check `process.env.RDC_TEST === '1'` and call `process.exit(0)` early to allow Tier 2 sandbox runs. Without this bypass, all Tier 2 headless invocations fail with `exit_code: -1`. File: `~/.claude/hooks/check-cwd.js`.
+**Known blocker:** Project-specific cwd hooks must check `process.env.RDC_TEST === '1'` and call `process.exit(0)` early to allow Tier 2 sandbox runs. Without this bypass, headless self-test invocations can fail before the skill loads. File: `~/.claude/hooks/check-cwd.js`.
 
 ---
 

package/guides/history-md-spec.md

@@ -0,0 +1,297 @@
+---
+type: spec
+role: history-md
+systems: [place-fund, prt, plan]
+schema_version: "1.0"
+tags: [history-md, spec, rdc-skills, place-fund]
+---
+# HISTORY.md — Authoritative Specification
+> Version: 1.0 | Effective: 2026-05-22
+
+Every land-based project in the Place Fund ecosystem that satisfies the trigger predicate below
+MUST carry a `places/<prt_slug>/HISTORY.md` file in the regen-root monorepo.
+Skills that plan, scaffold, and validate real-estate PRT projects read this file to verify
+research provenance, lineage completeness, and research lifecycle status.
+
+---
+
+## Purpose
+
+`HISTORY.md` is the **land lineage record** for a Place Fund project — the authoritative
+document linking a `prt_projects` row to its physical, ecological, cultural, and regulatory
+history. It is NOT a marketing document. It is a research-grade provenance record that:
+
+- Provides due-diligence depth for regenerative land stewardship decisions
+- Anchors the project's data to verifiable primary sources (county records, PLSS, BLM, state archives)
+- Tracks research lifecycle from `draft` through `peer-reviewed` so consumers know what to trust
+- Enables the Place Fund's ecological and conservation underwriting to be audited independently
+
+A missing or stub `HISTORY.md` signals that research is pending. A `published` one signals
+that the record has been reviewed and is fit for external use.
+
+---
+
+## Trigger Predicate
+
+A `prt_projects` row **requires** a `places/<slug>/HISTORY.md` when ALL of:
+
+1. `project_type IN ('ranch','eco-hospitality','mixed','conservation','regenerative-agriculture','real-estate','development')`
+2. `name IS NOT NULL` (always true for active rows)
+3. AT LEAST ONE OF:
+   - `location_state IS NOT NULL`
+   - `location_city IS NOT NULL`
+   - `country IS NOT NULL`
+   - `total_acres IS NOT NULL`
+   - `lat IS NOT NULL`
+   - `EXISTS (SELECT 1 FROM geo_parcels WHERE project_id = prt_projects.id)`
+   - `EXISTS (SELECT 1 FROM geo_projects WHERE prt_project_id = prt_projects.id)` — a geo_projects join indicates real GIS data exists for this place, even if lat/lng on prt_projects is unset
+
+**Excluded by default:** `project_type IN ('credit','water','tech','regenerative-model')` — these
+are credit instruments or abstract models, not physical land parcels. Individual rows may be
+opted in manually by a supervisor if a composite history is warranted.
+
+As a SQL check (used by the validator):
+
+```sql
+SELECT slug, name, project_type, location_state, location_city, country, total_acres, lat
+FROM prt_projects
+WHERE is_template IS NOT TRUE
+  AND project_type IN ('ranch','eco-hospitality','mixed','conservation',
+                       'regenerative-agriculture','real-estate','development')
+  AND (
+    location_state IS NOT NULL
+    OR location_city IS NOT NULL
+    OR country IS NOT NULL
+    OR total_acres IS NOT NULL
+    OR lat IS NOT NULL
+    OR EXISTS (SELECT 1 FROM geo_parcels WHERE project_id = prt_projects.id)
+    OR EXISTS (SELECT 1 FROM geo_projects WHERE prt_project_id = prt_projects.id)
+  )
+ORDER BY slug;
+```
+
+---
+
+## Schema
+
+### Frontmatter Fields
+
+Every `HISTORY.md` begins with YAML frontmatter bounded by `---` delimiters.
+
+```yaml
+---
+schema_version: "1.0"
+prt_slug: SLUG
+project_type: ranch
+location:
+  county: COUNTY
+  state: STATE
+  country: COUNTRY
+  parcel_apn: APN
+  area_acres: ACRES
+  centroid: [LAT, LNG]
+acquired: "YYYY-MM-DD"
+steward: STEWARD_NAME
+research_status: draft
+last_reviewed: "YYYY-MM-DD"
+contributors: []
+---
+```
+
+### Field Reference
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `schema_version` | string | yes | Always `"1.0"` for this revision |
+| `prt_slug` | string | yes | Must match `prt_projects.slug` exactly (case-sensitive) |
+| `project_type` | string | yes | Echo from `prt_projects.project_type` |
+| `location` | object | yes | Nested block — see sub-fields below |
+| `location.county` | string | no | County or district name |
+| `location.state` | string | no | State or province name or abbreviation |
+| `location.country` | string | no | Country name; omit if USA |
+| `location.parcel_apn` | string | no | Assessor's Parcel Number (APN) or equivalent |
+| `location.area_acres` | number | no | Total acreage from authoritative source |
+| `location.centroid` | [lat, lng] | no | Decimal-degree centroid coordinates |
+| `acquired` | ISO date | no | Acquisition date (`YYYY-MM-DD`); omit if unknown |
+| `steward` | string | yes | Current stewarding entity or person |
+| `research_status` | enum | yes | One of: `draft` · `in-research` · `peer-reviewed` · `published` |
+| `last_reviewed` | ISO date | yes | Date this file was last substantively reviewed |
+| `contributors` | string[] | yes | Array of contributor identifiers (may be empty `[]`) |
+
+#### `research_status` semantics
+
+| Value | Meaning |
+|-------|---------|
+| `draft` | Stub created; no primary-source research yet |
+| `in-research` | Active research underway; primary sources being identified |
+| `peer-reviewed` | Research complete; reviewed by at least one secondary reviewer |
+| `published` | Record approved for external publication and citation |
+
+The validator will warn (not fail) on `draft` rows — they are expected during initial rollout.
+The validator will fail if `research_status` is not one of the four allowed values.
+
+---
+
+## Required Body Sections
+
+The body of `HISTORY.md` must contain all five section headings in order. Each section may
+contain a TODO marker during draft status; it must contain substantive prose at `published`.
+
+### `## Land lineage`
+
+Deep time through present ownership. Cover:
+- Pre-contact landscape and ecological baseline
+- Indigenous stewardship, use patterns, and territorial context
+- Spanish/Mexican land grants (if applicable)
+- US government survey and PLSS reference (township, range, section)
+- Homestead entry, patent, and early title chain
+- Major ownership transitions to present
+
+### `## Stewardship transitions`
+
+Timeline of stewardship changes. Cover:
+- Each major ownership or management transfer with approximate dates
+- Conservation easements, deed restrictions, and encumbrances
+- Use-change inflection points (e.g. dryland → irrigated, grazing → timber)
+- Current stewardship entity and tenure
+
+### `## Ecological context`
+
+Physical and biological baseline. Cover:
+- Ecoregion and watershed affiliation
+- Soil classifications (NRCS Web Soil Survey references)
+- Vegetation communities and cover types
+- Water resources (streams, springs, riparian areas, aquifer)
+- Wildlife corridors and listed species presence/absence
+- Fire history and disturbance regime
+
+### `## Cultural significance`
+
+Human geography and intangible values. Cover:
+- Indigenous place names and cultural associations (cite tribal consultation if any)
+- Historic structures, archaeological sites, or cultural landscapes (Section 106 if applicable)
+- Community significance — grazing allotments, water rights, access traditions
+- Scenic and recreational values
+
+### `## Regulatory record`
+
+Legal, regulatory, and administrative context. Cover:
+- Zoning and land use designations
+- Conservation easements held by land trusts (ACE, TNC, CLT, etc.)
+- Water rights adjudications
+- Federal and state permits (grazing permits, NEPA actions, ESA consultations)
+- Tax status (agricultural classification, conservation land designation)
+- Open title or lien issues of record
+
+---
+
+## File Location Convention
+
+```
+C:/Dev/regen-root/places/<prt_slug>/HISTORY.md
+```
+
+The directory is named using the **sanitized slug** — lowercase, no special characters,
+hyphens for separators. If `prt_projects.slug` contains uppercase letters (e.g. `Diamond`),
+the filesystem path uses `diamond/HISTORY.md` while `prt_slug` in frontmatter preserves
+the exact DB value (`Diamond`).
+
+---
+
+## Enforcement Layers
+
+### Layer 1 — Workflow scaffold (`rdc:plan`)
+
+When `rdc:plan` creates a new `prt_projects` row with a qualifying `project_type`, it reads
+this spec and produces a stub `places/<slug>/HISTORY.md` from `scaffold/templates/HISTORY.md.template`.
+The stub is committed alongside the epic creation commit so the file is never absent from day one.
+
+### Layer 2 — Validator script
+
+`C:/Dev/rdc-skills/scripts/validate-place-histories.js` runs in two modes:
+
+| Mode | Behavior | Exit code |
+|------|----------|-----------|
+| `--mode warn` (default) | Missing or malformed HISTORY.md emits WARN; exits 0 | 0 |
+| `--mode fail` | Missing or malformed HISTORY.md emits FAIL; exits 1 | 1 |
+
+The validator is wired into the `rdc-skills` `prepack` step (warn mode) so it runs on every
+package publish and surfaces gaps without blocking.
+
+### Layer 3 — Optional DB gate (future)
+
+A `history_md_status` column on `prt_projects` can mirror `research_status` from frontmatter
+via a sync script. This enables Supabase-side filtering of projects by research completeness.
+Not implemented in v1 — planned for a future epic.
+
+---
+
+## Consumer Integration
+
+### `rdc:plan`
+
+When scaffolding a new real-estate PRT project:
+1. Check if `project_type` satisfies the trigger predicate.
+2. If yes: hydrate `HISTORY.md.template` with DB row metadata and write `places/<slug>/HISTORY.md`.
+3. Commit the stub alongside the epic creation commit.
+
+### `rdc:review` / `rdc:build`
+
+When the build scope touches `apps/prt/`:
+1. Run `node C:/Dev/rdc-skills/scripts/validate-place-histories.js --mode warn`.
+2. Surface any WARN lines in the review output.
+3. Do not block on warn — block only on FAIL (malformed frontmatter).
+
+---
+
+## Example — Dos Pueblos Ranch (dp-phased-model)
+
+```markdown
+---
+schema_version: "1.0"
+prt_slug: dp-phased-model
+project_type: ranch
+location:
+  county: Santa Barbara
+  state: California
+  country:
+  parcel_apn:
+  area_acres:
+  centroid:
+acquired:
+steward: Dos Pueblos Ranch LLC
+research_status: draft
+last_reviewed: "2026-05-22"
+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 Dos Pueblos Ranch. Cover Chumash territory, Spanish rancho land grant (Rancho Dos Pueblos, c. 1842), Mexican land commission adjudication, US patent, and ownership chain to present.
+
+## Stewardship transitions
+
+TODO: Document major ownership and use transitions for Dos Pueblos Ranch from rancho era through current orchid and agricultural operations.
+
+## Ecological context
+
+TODO: Document ecoregion (Southern California Coast Ranges), chaparral and oak woodland communities, seasonal streams, and proximity to coastal wetlands.
+
+## Cultural significance
+
+TODO: Research Chumash place names and village associations. Note proximity to historic Chumash settlements along the Santa Barbara coast.
+
+## Regulatory record
+
+TODO: Document zoning (Santa Barbara County agricultural/rural zones), any conservation easements, and water rights in Goleta Water District service area.
+```
+
+---
+
+## Changelog
+
+| Version | Date | Change |
+|---------|------|--------|
+| 1.0 | 2026-05-22 | Initial spec — trigger predicate, schema, 5 required sections, 3-layer enforcement |