@delorenj/pjangler 1.4.2 → 1.4.4

package/contracts/fleet-contract.yaml

@@ -0,0 +1,513 @@
+# 33GOD fleet authority and managed-state contract.
+#
+# DECLARATION ONLY. This file records versions, authority owners,
+# one-directional projections, lifecycle classes, the canonical service model,
+# the activation gate, and retired modes. It carries no runtime observation, no
+# credential, no host secret, and no absolute host path: stores are named by
+# the environment keys that resolve them and every variable segment of a field
+# path is a {placeholder}.
+#
+# Field paths are dotted key paths that exist in the live stores today. Roots:
+#   projects.*    PJangler project registry
+#   agents.*      Hermes agent registry, per-agent rows
+#   gateways.*    Hermes agent registry, fleet-shared gateway block
+#   profiles.*    generated Hermes profile tree
+#   scaffold.*    tracked per-agent role scaffold
+#   units.*       systemd user units
+#   processes.*   observed Hermes processes (read-only)
+#
+# Namespaced `x-` keys at any depth round-trip verbatim and are never
+# interpreted as policy.
+#
+# `service_model` and `activation` accept keys beyond the required ones on
+# purpose: an unknown healthy-mode declaration must reach the retired-mode scan
+# rather than be rejected as an unknown key, because rejecting it would hide the
+# very drift this contract exists to name.
+
+schema_version: 2
+contract_version: 1.1.0
+
+compatibility:
+  min_schema_version: 1
+  max_schema_version: 2
+
+x-delonet/provenance:
+  assessment: fleet-convergence-live-assessment-2026-08-31
+  epic: registry-wide-fleet-convergence-control-plane
+
+authorities:
+  project_identity:
+    owner: project-registry
+    store: pjangler-project-registry
+    store_env:
+      - PJ_PROJECT_REGISTRY
+    notes:
+      - Project identity and project-to-board binding.
+      - Board provenance fields exist only here, never in the agent registry.
+    writable_fields:
+      - projects.{slug}.name
+      - projects.{slug}.slug
+      - projects.{slug}.repo_path
+      - projects.{slug}.description
+      - projects.{slug}.status
+      - projects.{slug}.source_artifacts
+      - projects.{slug}.template
+      - projects.{slug}.ticket_provider.type
+      - projects.{slug}.ticket_provider.workspace
+      - projects.{slug}.ticket_provider.identifier
+      - projects.{slug}.ticket_provider.identifier_source
+      - projects.{slug}.ticket_provider.identifier_fetched_at
+      - projects.{slug}.ticket_provider.board_id
+      - projects.{slug}.ticket_provider.board_confirmed_at
+      - projects.{slug}.ticket_provider.board_url
+      - projects.{slug}.ticket_provider.state
+      - projects.{slug}.agents.{role}.role
+      - projects.{slug}.agents.{role}.provisioning_state
+      - projects.{slug}.agents.{role}.role_dir
+      - projects.{slug}.automation
+      - projects.{slug}.notebook
+      - projects.{slug}.created_at
+      - projects.{slug}.updated_at
+
+  agent_operational_records:
+    owner: hermes-agent-registry
+    store: hermes-agent-registry
+    store_env:
+      - HERMES_AGENTS_REGISTRY
+      - HERMES_FLEET_REGISTRY_FILE
+    notes:
+      - Operational agent, profile, and routing records.
+      - The two store_env keys disagree today. The TypeScript reader honours
+        HERMES_AGENTS_REGISTRY, the shell provisioner honours
+        HERMES_FLEET_REGISTRY_FILE. Both are recorded so convergence is a
+        declared task, not a silent surprise.
+      - Bloodbank routing metadata is discovery, not execution authority. The
+        single activation flag lives under the bloodbank_activation authority.
+    writable_fields:
+      - agents.{agent_id}.repo
+      - agents.{agent_id}.role
+      - agents.{agent_id}.display_name
+      - agents.{agent_id}.project_path
+      - agents.{agent_id}.role_dir
+      - agents.{agent_id}.profile_name
+      - agents.{agent_id}.provisioned_at
+      - agents.{agent_id}.runtime_repo
+      - agents.{agent_id}.telegram.provisioning_status
+      - agents.{agent_id}.slack.provisioning_status
+      - agents.{agent_id}.bloodbank.gateway_scope
+      - agents.{agent_id}.bloodbank.target_agent_id
+      - agents.{agent_id}.hermes.bin
+      - agents.{agent_id}.hermes.repo
+      - agents.{agent_id}.hermes.git_url
+      - agents.{agent_id}.hermes.git_ref
+      - agents.{agent_id}.hermes.git_sha
+      - agents.{agent_id}.hermes.fleet_env
+      - gateways.bloodbank.scope
+      - gateways.bloodbank.profile_name
+      - gateways.bloodbank.command_subject
+      - gateways.bloodbank.target_field
+      - gateways.bloodbank.systemd_unit
+
+  board_identity_projection:
+    owner: project-registry
+    store: hermes-agent-registry
+    store_env:
+      - HERMES_AGENTS_REGISTRY
+      - HERMES_FLEET_REGISTRY_FILE
+    notes:
+      - The one cross-store write that actually happens today. `pj project
+        identity --apply` copies confirmed board identity from the project
+        registry into the agent registry.
+      - Held as its own block so the agent registry's own writers cannot claim
+        these fields, and so the projections that target them have something
+        real to point at.
+    writable_fields:
+      - agents.{agent_id}.plane.workspace
+      - agents.{agent_id}.plane.project_id
+      - agents.{agent_id}.plane.identifier
+
+  generated_profile_inputs:
+    owner: hermes-profile-renderer
+    store: hermes-profile-tree
+    store_env:
+      - HERMES_FLEET_HOME
+    notes:
+      - config.yaml is generated by deep-merging the shared base with the
+        per-profile config.delta.yaml. It is never hand-edited.
+      - The rest of config.delta.yaml is the operator-owned override SSOT. Only
+        the three fleet-owned dotted paths listed here are rewritten by the
+        renderer.
+    writable_fields:
+      - profiles.{profile_name}.config.yaml
+      - profiles.{profile_name}.config.delta.memory.provider
+      - profiles.{profile_name}.config.delta.memory.memory_enabled
+      - profiles.{profile_name}.config.delta.memory.user_profile_enabled
+
+  tracked_role_scaffold:
+    owner: hermes-agent-template
+    store: hermes-agent-role-scaffold
+    store_env:
+      - HERMES_TEMPLATE_RUNTIME_SCAFFOLD
+      - RUNTIME_SCAFFOLD_DIR
+    notes:
+      - The committed template at its pinned gitlink owns every tracked asset in
+        a per-agent role directory. Role-local runtime bytes are ignored and are
+        owned by nobody.
+    writable_fields:
+      - scaffold.role.yaml
+      - scaffold.SOUL.md
+      - scaffold.hermes
+      - scaffold.momo
+      - scaffold.sentinel.prompt.md
+      - scaffold.gitignore
+      - scaffold.scripts
+      - scaffold.runtime-scaffold
+
+  systemd_lifecycle:
+    owner: hermes-fleet-provisioner
+    store: systemd-user-manager
+    store_env:
+      - XDG_CONFIG_HOME
+    notes:
+      - Unit files and the registry rows that name them are written by the
+        provisioner, not by registry editing paths.
+    writable_fields:
+      - units.hermes-{agent_id}-gateway.service
+      - units.hermes-{agent_id}-heartbeat.service
+      - units.hermes-{agent_id}-heartbeat.timer
+      - units.hermes-fleet-bloodbank-gateway.service
+      - agents.{agent_id}.systemd.gateway_unit
+      - agents.{agent_id}.systemd.heartbeat_timer
+
+  live_process_observations:
+    owner: fleet-observer
+    store: process-table
+    store_env: []
+    read_only: true
+    notes:
+      - Observation only. A process is attributed and classified; it is never
+        written to, and a drain is a separately authorized effect owned by a
+        later story.
+    writable_fields: []
+
+  bloodbank_activation:
+    owner: hermes-agent-registry
+    store: hermes-agent-registry
+    store_env:
+      - HERMES_AGENTS_REGISTRY
+      - HERMES_FLEET_REGISTRY_FILE
+    notes:
+      - The single field that can grant execution authority. Held apart from the
+        operational records so discovery can never widen into dispatch.
+    writable_fields:
+      - agents.{agent_id}.bloodbank.enabled
+
+projections:
+  - field: project_repository_path
+    source: projects.{slug}.repo_path
+    target: agents.{agent_id}.project_path
+    direction: pjangler_project_registry_to_hermes_agent_registry
+    writable_by: hermes-agent-registry
+
+  - field: project_slug
+    source: projects.{slug}.slug
+    target: agents.{agent_id}.repo
+    direction: pjangler_project_registry_to_hermes_agent_registry
+    writable_by: hermes-agent-registry
+
+  - field: board_identifier
+    source: projects.{slug}.ticket_provider.identifier
+    target: agents.{agent_id}.plane.identifier
+    direction: pjangler_project_registry_to_hermes_agent_registry
+    writable_by: project-registry
+
+  - field: board_id
+    source: projects.{slug}.ticket_provider.board_id
+    target: agents.{agent_id}.plane.project_id
+    direction: pjangler_project_registry_to_hermes_agent_registry
+    writable_by: project-registry
+
+  - field: board_workspace
+    source: projects.{slug}.ticket_provider.workspace
+    target: agents.{agent_id}.plane.workspace
+    direction: pjangler_project_registry_to_hermes_agent_registry
+    writable_by: project-registry
+
+  - field: agent_role_directory
+    source: agents.{agent_id}.role_dir
+    target: projects.{slug}.agents.{role}.role_dir
+    direction: hermes_agent_registry_to_pjangler_project_registry
+    writable_by: project-registry
+
+classifications:
+  managed_agent:
+    notes:
+      - A registered agent row. Instances are registry rows, not contract
+        entries, so this class declares its required shape and carries none.
+    required_fields:
+      - id
+      - kind
+      - owner
+      - source
+      - lifecycle_state
+    entries: []
+
+  managed_shared_service:
+    notes:
+      - Shared or specialist fleet state that is deliberately managed but is not
+        a per-agent row.
+    required_fields:
+      - id
+      - kind
+      - owner
+      - source
+      - lifecycle_state
+      - rationale
+      - policy_domains
+    entries:
+      - id: fleet-bloodbank-gateway
+        kind: shared-service
+        owner: hermes-fleet-provisioner
+        source: gateways.bloodbank
+        lifecycle_state: managed
+        rationale: One shared gateway owns Bloodbank command ingress fleet-wide.
+        policy_domains:
+          - systemd
+          - bloodbank
+          - profile
+      - id: fleet-shared-profile-base
+        kind: shared-config
+        owner: hermes-profile-renderer
+        source: profiles.base.config.yaml
+        lifecycle_state: managed
+        rationale: Every generated profile config is a merge of this base.
+        policy_domains:
+          - profile
+
+  intentionally_unmanaged:
+    notes:
+      - State an operator has decided the control plane must observe, report,
+        and leave alone. Instances are recorded when an observation is
+        classified; nothing is declared up front.
+    required_fields:
+      - id
+      - kind
+      - owner
+      - source
+      - lifecycle_state
+      - rationale
+      - policy_domains
+    entries: []
+
+  retired:
+    notes:
+      - Drift that used to be a supported mode. The retired block below is the
+        authoritative list; entries here are per-instance sightings.
+    required_fields:
+      - id
+      - kind
+      - owner
+      - source
+      - lifecycle_state
+      - rationale
+      - policy_domains
+    entries: []
+
+  unclassified:
+    notes:
+      - The default for anything observed that no rule above claims. It is a
+        finding for an operator, never a licence to delete.
+    required_fields:
+      - id
+      - kind
+      - owner
+      - source
+      - lifecycle_state
+      - rationale
+      - policy_domains
+    entries: []
+
+service_model:
+  per_agent:
+    gateway_unit: hermes-{agent_id}-gateway.service
+    heartbeat_service: hermes-{agent_id}-heartbeat.service
+    heartbeat_timer: hermes-{agent_id}-heartbeat.timer
+  fleet_shared:
+    bloodbank_gateway_unit: hermes-fleet-bloodbank-gateway.service
+    bloodbank_gateway_profile: fleet-bloodbank-gateway
+    command_subject: bloodbank.cmd.agent.invocation.start
+    target_field: data.target_agent_id
+  profile_layout:
+    root: "{HERMES_FLEET_HOME}/profiles/{profile_name}"
+    symlink_allowed: false
+    identity_file: profile.yaml
+    override_file: config.delta.yaml
+    generated_file: config.yaml
+    generated_marker: GENERATED FILE -- DO NOT EDIT
+
+# Which gaps are AUTHORIZED, and nothing else.
+#
+# Optional, and schema 1 contracts that omit it still load. What it changes is
+# what an aggregate may CLAIM: a skip, a warning, a deferred capability, or a
+# managed exception is "justified" only if it is named here, and anything
+# unjustified keeps the fleet from claiming proof. Nothing in this block grants
+# a capability, relaxes the activation gate, or turns an observation into a
+# pass -- an authorized gap is still reported with its own state.
+health_policy:
+  # Domains an aggregate must have observed before it may claim proof. All nine
+  # are required; the deferred_capabilities below are what carve out the halves
+  # no adapter exists for in this release.
+  required_domains:
+    - registry
+    - project_binding
+    - template_scaffold
+    - profile
+    - runtime
+    - systemd
+    - live_process
+    - bloodbank
+    - release_provenance
+
+  # A capability no observer in this release can answer, and the story that owns
+  # it. Each entry authorizes ONE unsupported answer; it never authorizes
+  # inferring the answer from something else.
+  deferred_capabilities:
+    - domain: systemd
+      capability: unit_topology
+      reason: >-
+        No systemd observer exists in this release. The unit names reported for
+        an agent are the patterns service_model.per_agent derives, carried as
+        expectations and never as observations of the user manager.
+      owner_story: "1.8"
+    - domain: live_process
+      capability: process_attribution
+      reason: >-
+        No process observer exists in this release: nothing in the build reads
+        the process table, so no running Hermes process can be attributed to a
+        registry row or classified as sprawl.
+      owner_story: "1.9"
+    - domain: bloodbank
+      capability: routing_liveness
+      reason: >-
+        The stored routing record is observed; whether the fleet-shared gateway
+        can dispatch to it is not. Routing readiness is a separate authority
+        from the record and must never be inferred from it.
+      owner_story: "1.10"
+    - domain: template_scaffold
+      capability: scaffold.template_ref
+      reason: >-
+        A deployed role scaffold records no template ref, so there is no
+        recorded value on this host to compare against the pinned gitlink and
+        none may be invented.
+      owner_story: "1.6"
+    - domain: release_provenance
+      capability: profile.render_generation
+      reason: >-
+        A generated profile config carries only the generated-file marker. The
+        renderer records no generation identity, so nothing comparable exists
+        until generated profile health is proven.
+      owner_story: "1.7"
+    - domain: release_provenance
+      capability: fleet.registry_file
+      reason: >-
+        The host config names the agent registry through an unexpanded shell
+        variable and this control plane must not resolve one. It is the same
+        declared divergence the agent_operational_records authority records in
+        its two store_env keys.
+      owner_story: "1.1"
+
+  # A rule whose warn is upstream cadence rather than fleet drift.
+  allowed_warnings:
+    - rule_id: bmad.version
+      reason: >-
+        A currency check against the published BMAD release, cached for an hour
+        and degraded to a skip offline. A newer upstream release is upstream
+        cadence, not drift in this fleet.
+      owner: bmad-method
+
+  # A rule or domain whose skip is a deliberate property of a read-only default
+  # run rather than an observation nobody got round to.
+  allowed_skips:
+    - rule_id: notebook.remote-notebook
+      reason: >-
+        A default audit makes no network request, so remote notebook state is
+        not applicable to it.
+    - rule_id: notebook.overview-note
+      reason: >-
+        A default audit makes no network request, so the remote Overview note is
+        not applicable to it.
+    - rule_id: notebook.skill-installed
+      reason: >-
+        A default audit reads no global path, so the host skill projection is
+        not applicable to it.
+    - rule_id: notebook.hooks-projected
+      reason: >-
+        A default audit reads no global settings file, so the host hook
+        projection is not applicable to it.
+
+  # How long a recorded timestamp may go unrefreshed before the value it stamps
+  # stops counting as current evidence. Reported as a BUCKET and never as an
+  # age: an age in seconds would make two runs over unchanged state differ.
+  freshness:
+    - field: projects.{slug}.ticket_provider.board_confirmed_at
+      max_age_days: 180
+      applies_to: project_binding
+    - field: projects.{slug}.ticket_provider.identifier_fetched_at
+      max_age_days: 180
+      applies_to: project_binding
+    - field: agents.{agent_id}.provisioned_at
+      max_age_days: 365
+      applies_to: registry
+
+activation:
+  states:
+    - discovered
+    - installed
+    - healthy
+    - routing_ready
+    - activated
+  execution_authority:
+    field: agents.{agent_id}.bloodbank.enabled
+    owner: hermes-agent-registry
+    strict: true
+    default: deny
+  routing_prerequisites:
+    - field: agents.{agent_id}.bloodbank.gateway_scope
+      constraint: equals-fleet
+    - field: agents.{agent_id}.bloodbank.target_agent_id
+      constraint: equals-agent-id
+    - field: agents.{agent_id}.profile_name
+      constraint: nonblank
+
+retired:
+  - id: per-agent-bloodbank-consumer
+    reason: A per-agent consumer races the shared gateway and duplicates work.
+    superseded_by: service_model.fleet_shared.bloodbank_gateway_unit
+    detect:
+      - '-consumer\.service'
+      - 'consumer_unit'
+  - id: per-agent-checkpoint-timer
+    reason: Checkpoint-only ticks proved liveness without proving health.
+    superseded_by: service_model.per_agent.heartbeat_timer
+    detect:
+      - '-checkpoint\.timer'
+      - 'checkpoint_timer'
+  - id: n8n-owned-truth
+    reason: Orchestration may consume fleet APIs but may not own fleet truth.
+    superseded_by: authorities.agent_operational_records
+    detect:
+      - 'n8n'
+  - id: activation-by-discovery
+    reason: A resolvable target is not permission to dispatch to it.
+    superseded_by: activation.execution_authority
+    detect:
+      - 'activation_by_discovery'
+      - 'auto_activate'
+      - 'activate_on_discovery'
+  - id: hard-coded-hermes-checkout-path
+    reason: Pinned releases are resolved from the registry, never from a path.
+    superseded_by: authorities.agent_operational_records
+    detect:
+      - '\$HOME/[^\s]*hermes'
+      - '~/[^\s]*hermes'
+      - '(?:^|/)code/hermes-agent'