@lifeaitools/rdc-skills 0.24.41 → 0.25.0

package/guides/history-md-spec.md

@@ -1,297 +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 |
+---
+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 |