Ndo (#65)

* refactor: split ResourceState into LifecycleStage and OperationalState

- Updated the ResourceState enum to clarify the distinction between the maturity/evolutionary phase of a resource (LifecycleStage) and the current process acting on a resource instance (OperationalState).
- Introduced detailed documentation on the new enums, outlining their values and the implications for resource management within the Nondominium framework.
- Adjusted related documentation to reflect the changes in state management, ensuring clarity on how lifecycle transitions and operational conditions are governed.
- This refactor aims to enhance the accuracy of resource state tracking and improve the governance model by separating concerns.

* feat(happ): add hrea role to happ.yaml dual-DNA config (#49)

* feat(build): integrate hREA DNA into build and CI pipeline (#50)

* ci(build): fix nix flake reproducibility, add rust caching, split test:only script

- Replace nix_path channel override with github_access_token to preserve
  flake.nix pinned nixpkgs (holonix) and avoid non-reproducible unstable builds
- Add Swatinem/rust-cache@v2 for both nondominium and hREA target/ dirs to
  avoid 30-50min cold WASM compilation on every CI run
- Add test:only script to package.json so CI can build once then test once,
  eliminating redundant double-compilation from calling 'tests' script in CI
- Update Run tests step to use test:only instead of tests

* ci(build): add bun install step before build

vitest and other test deps were not installed on the runner,
causing 'vitest: command not found' (exit code 127)

* ci(build): set continue-on-error on test step during suite stabilization

* ci(build): skip tests until suite is stabilized

* docs(claude): add submodule init step to dev setup

* chore(github): add issue and PR templates

Adds bug report, feature/task issue templates, and PR template following
the project's PR_GUIDELINES.md structure with conventional commit prefixes,
acceptance criteria, and architectural notes sections.

* feat(role): implement role promotion request structure and validation

- Added a detailed TODO for implementing a `RolePromotionRequest` entry type to facilitate queryable promotion requests in the DHT, addressing the current limitation of out-of-band communication for pending requests.
- Updated `role.rs` to outline necessary changes for storing promotion requests and querying them by authorized approvers.
- Enhanced `lib.rs` with plans for an `agent_entity_type` field to distinguish various agent types and their capabilities, supporting future extensibility.
- Documented the need for a configurable role taxonomy to allow communities to define their own roles, moving beyond the current hardcoded enum.
- Adjusted related documentation to reflect these enhancements and their implications for governance and resource management.

Author: TiberiusB

.github/pull_request_template.md

@@ -23,8 +23,9 @@
 
 ## Related
 
-Closes #[issue]
-Closes #[issue]
+Related issues:
+- Closes #[issue]
+- Closes #[issue]
 
 - Depends on: #
 - Follow-up: #

dnas/nondominium/zomes/coordinator/zome_person/src/role.rs

@@ -333,6 +333,39 @@ pub fn promote_agent_with_validation(input: PromoteAgentInput) -> ExternResult<R
   assign_person_role(role_input)
 }
 
+// TODO (G13 — Queryable Promotion Requests): This function currently validates the request and
+// then returns a placeholder hash (the hash of the ValidationReceipt). The actual
+// `RolePromotionRequest` is never written to the DHT as a queryable entry, which means
+// authorised approvers have no way to discover pending requests without out-of-band
+// communication.
+//
+// Required changes (see `documentation/archives/implementation_plan.md` Phase 2.4):
+//
+// 1. Define a `RolePromotionRequest` entry type in `zome_person_integrity/src/lib.rs`:
+//    ```rust
+//    pub struct RolePromotionRequest {
+//        pub requesting_agent: AgentPubKey,
+//        pub target_role: String,
+//        pub justification: String,
+//        pub created_at: Timestamp,
+//        pub status: PromotionRequestStatus, // Pending, Approved, Rejected
+//    }
+//    pub enum PromotionRequestStatus { Pending, Approved, Rejected }
+//    ```
+//
+// 2. Store the request as a real DHT entry with these links:
+//    - `AllPendingPromotions` anchor → `request_hash` (so approvers can discover all requests)
+//    - `agent_pubkey` → `request_hash` (so the requesting agent can track their request)
+//    - `request_hash` → `agent_pubkey` (reverse lookup)
+//
+// 3. Implement `get_pending_promotion_requests() -> ExternResult<Vec<RolePromotionRequest>>`
+//    for authorised approvers to query (filtered by their capability level).
+//
+// 4. Update `approve_role_promotion` to change the `PromotionRequestStatus` to `Approved` via
+//    an `update_entry` call, rather than acting on an out-of-band hash.
+//
+// See `REQ-AGENT-16` in `documentation/requirements/requirements.md` and
+// `agent.md` §2.6 (Known Gaps, G13).
 /// Request promotion to a higher role
 /// This creates a request that can be approved by authorized agents
 #[hdk_extern]

dnas/nondominium/zomes/integrity/zome_person/src/lib.rs

@@ -1,6 +1,38 @@
 use hdi::prelude::*;
 use std::{fmt::Display, str::FromStr};
 
+// TODO (G1 — AgentEntityType): Add an `agent_entity_type` field (or a companion `AgentContext`
+// entry) to distinguish Individual, Collective, Project, Network, Bot, and ExternalOrganisation
+// agents. Currently all agents are implicitly modelled as individual humans. The post-MVP
+// design proposes:
+//
+//   pub enum AgentEntityType {
+//       Individual,
+//       Collective(String),
+//       Project(ActionHash),    // references an organisational NondominiumIdentity hash
+//       Network(ActionHash),    // references a network NondominiumIdentity hash
+//       Bot { capabilities: Vec<String>, operator: AgentPubKey },
+//       ExternalOrganisation(String),
+//   }
+//
+//   pub struct AgentContext {
+//       pub agent_type: AgentEntityType,
+//       pub person_hash: Option<ActionHash>, // None for bots / external orgs
+//       pub created_at: Timestamp,
+//       pub network_seed: String,
+//   }
+//
+// See `documentation/archives/agent.md` §6.1, `REQ-AGENT-01` in requirements.md, and
+// `documentation/requirements/ndo_prima_materia.md` §8.7.
+//
+// TODO (G15 — CapabilitySlot on Agent): The `Person` entry hash should serve as a stigmergic
+// attachment surface for external capabilities — analogous to the NondominiumIdentity
+// CapabilitySlot in ndo_prima_materia.md §6. Add a `PersonCapabilitySlot` link type:
+//   PersonCapabilitySlot: Person hash → capability target (DID document, credential wallet,
+//                                                           reputation oracle, external registry)
+// Implement `attach_agent_capability_slot` and `get_agent_capability_slots` coordinator
+// functions. See `REQ-AGENT-11` and `ndo_prima_materia.md` §6.5.
+
 /// Represents a person's public profile with basic information
 #[hdk_entry_helper]
 #[derive(Clone, PartialEq)]
@@ -54,7 +86,31 @@ pub struct PersonRole {
   pub assigned_at: Timestamp,
 }
 
+// TODO (G14 — Configurable Role Taxonomy): This enum is closed — communities cannot define
+// their own role types. The OVN model requires roles to emerge from community needs, not
+// from infrastructure decisions. Post-MVP, this should become a configurable role registry:
+//
+//   // In integrity: remove `RoleType` enum entirely, or keep as default-role constants.
+//   // Add a `RoleDefinition` entry type:
+//   pub struct RoleDefinition {
+//       pub role_name: String,
+//       pub capability_level: String, // "member" | "stewardship" | "coordination" | "governance"
+//       pub description: Option<String>,
+//       pub validation_requirements: Option<String>,
+//       pub network_id: String,       // Which network defined this role
+//       pub created_at: Timestamp,
+//   }
+//
+//   // In coordinator: `assign_person_role` accepts any role name present in the network's
+//   // RoleDefinition registry. The six predefined roles below become genesis entries.
+//   // The validate_person_role function must stop hard-rejecting unknown role names and
+//   // instead look up the RoleDefinition registry.
+//
+// See `documentation/archives/agent.md` §5.3 (G14), `REQ-AGENT-06` in requirements.md, and
+// `documentation/zomes/person_zome.md` Future Enhancements.
+
 /// Allowed role types in the system
+// NOTE: These are the MVP defaults. Post-MVP they become configurable registry entries.
 #[derive(Debug, Clone, PartialEq)]
 pub enum RoleType {
   SimpleAgent,             // Simple Agent capabilities

dnas/nondominium/zomes/integrity/zome_resource/src/lib.rs

@@ -1,6 +1,37 @@
 use hdi::prelude::*;
 
-// TODO: Add transport state
+// TODO: Split ResourceState into two orthogonal enums:
+//
+// 1. LifecycleStage — the maturity/evolutionary phase of the resource (advances rarely, usually
+//    irreversibly). Maps to NondominiumIdentity.lifecycle_stage in the NDO three-layer model.
+//    Values: Ideation, Specification, Development, Prototype, Stable, Distributed,
+//            Active, Hibernating, Deprecated, EndOfLife
+//
+// 2. OperationalState — the current process acting on this specific resource instance (cycles
+//    frequently as processes begin and end). Governance-zome controlled.
+//    Values: Available, Reserved, InTransit, InStorage, InMaintenance, InUse, PendingValidation
+//
+// The current enum CONFLATES both dimensions:
+//   PendingValidation  → OperationalState::PendingValidation (pre-activation gate)
+//   Active             → LifecycleStage::Active + OperationalState::Available
+//   Maintenance        → OperationalState::InMaintenance (repair process active; LifecycleStage
+//                        remains whatever it was before, typically Active)
+//   Retired            → LifecycleStage::Deprecated or EndOfLife
+//   Reserved           → OperationalState::Reserved (pre-allocation; LifecycleStage unchanged)
+//
+// Transport, Storage, and Maintenance are PROCESSES that act on a resource at any lifecycle stage.
+// A Prototype can be InTransit (moved between labs). An Active resource can be InStorage.
+// These are NOT lifecycle stages.
+//
+// See: documentation/requirements/ndo_prima_materia.md — Section 5 (LifecycleStage + OperationalState)
+// See: documentation/archives/resources.md — Section 2.4 (known gaps)
+//
+// TODO: Implement PropertyRegime enum when NondominiumIdentity (Layer 0) is introduced.
+// Canonical 6-variant enum: Private, Commons, Collective, Pool, CommonPool, Nondominium.
+// Each variant implies default governance templates via GovernanceDefaultsEngine.
+// See: documentation/requirements/ndo_prima_materia.md — Section 8.2
+// See: documentation/archives/resources.md — Section 6.3 (canonical definition)
+// See: documentation/archives/resources.md — Section 6.6 (PropertyRegime → governance defaults)
 #[derive(Clone, PartialEq, Debug, Serialize, Deserialize, Default)]
 pub enum ResourceState {
   #[default]
@@ -83,6 +114,10 @@ pub enum LinkTypes {
   SpecsByCategory,     // Category -> ResourceSpecs
   ResourcesByLocation, // Location -> EconomicResources
   ResourcesByState,    // ResourceState -> EconomicResources
+  // TODO (REQ-NDO-OS-06): Split ResourcesByState into two independent link types:
+  //   ResourcesByLifecycleStage  — NondominiumIdentity lifecycle facet queries
+  //   ResourcesByOperationalState — EconomicResource operational facet queries
+  // See: documentation/requirements/ndo_prima_materia.md — Section 9.4 (REQ-NDO-OS-06)
 
   // Governance patterns
   RulesByType,          // RuleType -> GovernanceRules

documentation/ARCHITECTURE_COMPONENTS.md

@@ -210,7 +210,7 @@ graph TB
 
         subgraph "Economic Resource"
             EconRes[EconomicResource<br/>Resource Instance]
-            ResState[ResourceState<br/>State Tracking]
+            ResState[LifecycleStage + OperationalState<br/>State Tracking (TODO: split ResourceState)]
             ResHistory[ResourceHistory<br/>Audit Trail]
             ResCustody[ResourceCustody<br/>Custody Tracking]
         end
@@ -258,7 +258,8 @@ graph TB
 │                                                             │
 │ 2.2 ECONOMIC RESOURCE                                       │
 │ ├── EconomicResource Entry (resource instance)              │
-│ ├── ResourceState Entry (current state tracking)            │
+│ ├── LifecycleStage (on NondominiumIdentity) + OperationalState (on EconomicResource) │
+│ │   TODO: split current ResourceState into these two enums  │
 │ ├── ResourceHistory Entry (audit trail)                     │
 │ └── ResourceCustody Entry (custody tracking)                │
 │                                                             │
@@ -630,7 +631,7 @@ graph TD
         P2[Hold Custody]
         P3[Validate Specialized Roles]
         P4[Initiate All Processes]
-        P5[All 14 PPR Categories<br/>Including Custodianship]
+        P5[All 16 PPR Categories<br/>Including Custodianship]
     end
 
     subgraph "Advanced Agent Capabilities"
@@ -665,7 +666,7 @@ Accountable Agent (stewardship)
 Primary Accountable Agent (coordination/governance)
 ├── Full Capability Token (comprehensive access)
 ├── Can: Hold custody, validate specialized roles, initiate all processes
-├── PPR Eligibility: All 14 categories including custodianship
+├── PPR Eligibility: All 16 categories including custodianship
 └── Advanced: Dispute resolution, end-of-life validation
 ```
 

documentation/DOCUMENTATION_INDEX.md

@@ -354,7 +354,7 @@ Accountable Agent (stewardship)
 Primary Accountable Agent (coordination/governance)
 ├── Full capability token
 ├── Can hold custody & validate specialized roles
-├── PPR eligibility: All 14 categories
+├── PPR eligibility: All 16 categories
 └── Advanced: Dispute resolution & end-of-life validation
 ```
 

documentation/archives/agent.md

@@ -216,6 +216,8 @@ An individual agent can hold a `PersonRole` in both their own profile and in an
 
 This means the generic NDO's agent model does not need a separate "organisation agent" type — it needs organisational NDOs and a clear mapping between individual agents and the NDOs they participate in.
 
+Agent-NDOs use the same three-layer structure as resource-NDOs (see `resources.md §3.1`) but may use a subset of `LifecycleStage` values — a working group does not go through `Prototype` or `Distributed`, for example. The `PropertyRegime` and `ResourceNature` fields on `NondominiumIdentity` remain applicable: a working group's shared knowledge base is a `Commons`/`Digital` NDO; a collectively owned workshop is a `Collective`/`Physical` NDO.
+
 ### 3.2 CapabilitySlot on Agent Identity
 
 The NDO CapabilitySlot surface (from `nondominium-prima-materia.md`) can be extended to agent identities: an agent's `Person` entry hash becomes a stigmergic attachment point for external applications — credential wallets, reputation oracles, DID documents, professional networks — without modifying the core Person entry. This is the agent-level equivalent of the resource-level CapabilitySlot.
@@ -429,8 +431,8 @@ affiliation_state(agent) = f(
     governance_claims_count(agent)          // From PPRs
 )
 
-→ Unaffiliated | CloseAffiliate | ActiveAffiliate(contribution_count) | 
-  CoreAffiliate(governance_weight) | InactiveAffiliate
+→ UnaffiliatedStranger | CloseAffiliate | ActiveAffiliate | 
+  CoreAffiliate | InactiveAffiliate
 ```
 
 `CoreAffiliate` is algorithmically determined: an active affiliate whose PPR contribution rate in the past N days exceeds a configurable threshold becomes a core affiliate. This implements the OVN governance equation: governance access as benefit derived from contribution activity.