@delorenj/pjangler 1.1.5 → 1.2.2

package/templates/hermes-agent/docs/fleet-control-plane/architecture.md

@@ -0,0 +1,253 @@
+---
+stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]
+inputDocuments:
+  - docs/fleet-control-plane/prd.md
+  - docs/architecture.md
+  - docs/operations.md
+workflowType: architecture
+project_name: Fleet Control Plane
+date: 2026-06-27
+status: draft-ready
+---
+
+# Fleet Control Plane Architecture
+
+## Executive Summary
+
+The Fleet should stay multi-repo. The fix is not repo fusion. The fix is a
+versioned Fleet contract, a single operational control plane in `pjangler`, and
+an explicit orchestration split:
+
+- `pjangler` is the source of control-plane truth.
+- n8n is the visual workflow/orchestration plane.
+- systemd is the local survival layer.
+- `~/.hermes` remains live runtime state, not a template source.
+
+## System Context
+
+```text
+CommonProject
+  emits base project repo and .project.json
+
+hermes-agent-template
+  emits agents/hermes/<role>, role.yaml, runtime scaffold, fallback units
+
+pjangler
+  owns Fleet contract, schema validation, template status, fleet status,
+  reconciliation, migration, release gates, and n8n workflow generation
+
+~/.hermes
+  owns fleet.env, auth, profiles, agents-registry.yaml, logs, state
+
+n8n
+  runs visual Fleet workflows generated from pjangler and registry state
+
+systemd --user
+  keeps gateway, consumer, and local fallback heartbeat/checkpoint alive
+```
+
+## Architecture Decisions
+
+### ADR-001: Keep Repos Independent, Bind With Fleet Contract
+
+Decision: Keep `CommonProject`, `hermes-agent-template`, `pjangler`, and Hermes
+engine as separate repos.
+
+Rationale:
+
+- Each repo has a valid standalone reason to exist.
+- The coupling problem is contract visibility, not physical repo layout.
+- Independent release cadence matters because templates, runtime state, and
+  orchestration logic change at different speeds.
+
+Consequences:
+
+- Add `fleet-contract.yaml` and schema validation.
+- `pjangler` must report effective sources and versions instead of relying on
+  hidden local assumptions.
+
+### ADR-002: Make pjangler the Fleet Control Plane
+
+Decision: `pjangler` owns Fleet-wide inspection, validation, reconciliation,
+template pinning, migration, and n8n workflow generation.
+
+Rationale:
+
+- `pjangler` already bootstraps projects and Hermes agents.
+- It already vendors templates and owns parity/migration logic.
+- It is the right place for deterministic CLI checks and MCP surfaces.
+
+Consequences:
+
+- `pjangler` must stop being ambiguous about whether vendored templates are
+  release inputs, development overrides, or dirty experiments.
+- Publish and build paths need dirty-template gates.
+
+### ADR-003: n8n Is the Visual Orchestration Plane, Not the Source of Truth
+
+Decision: n8n coordinates Fleet workflows but reads truth from `pjangler`,
+`fleet-contract.yaml`, and `~/.hermes/agents-registry.yaml`.
+
+Rationale:
+
+- n8n gives the desired visual control plane for delegation and health flows.
+- Letting n8n own state would create another drift surface.
+- Generated workflows are easier to review and reproduce than hand-edited
+  workflow state.
+
+Consequences:
+
+- First implementation should use generated n8n workflows with Webhook,
+  Schedule Trigger, HTTP Request, Set/If/Switch/Merge, and minimal Code nodes.
+- Custom n8n nodes can come later if workflow generation proves stable.
+- Workflow code must be validated before creation or update.
+
+### ADR-004: Hybrid Heartbeat Strategy
+
+Decision: Implement heartbeat v2 as n8n-centralized orchestration with systemd
+local fallback.
+
+Rationale:
+
+- n8n-only would make the Fleet fragile when n8n is down.
+- systemd-only hides orchestration and makes delegation hard to visualize.
+- Hybrid gives visual control without sacrificing local survival.
+
+Consequences:
+
+- systemd keeps gateway and consumer services running.
+- systemd fallback performs minimal self-health and checkpoint behavior.
+- n8n performs supervisor flows, agent health fanout, delegation, and
+  reconciliation triggers.
+
+### ADR-005: Treat Managed Exceptions as First-Class Fleet Entries
+
+Decision: Profiles and services outside the standard PM-agent pattern must be
+represented as explicit managed exceptions instead of undocumented drift.
+
+Rationale:
+
+- Voice agents, adversarial-review profiles, and historical profiles can be
+  legitimate without matching the PM template.
+- Drift reports are useful only when they distinguish bugs from exceptions.
+
+Consequences:
+
+- Registry schema gets `managed`, `kind`, `source`, `owner`, and `notes`.
+- `pj fleet status` reports unmanaged/external entries separately from broken
+  managed entries.
+
+## Fleet Contract
+
+Initial contract shape:
+
+```yaml
+schema_version: 1
+fleet_contract_version: 1
+service_model: hybrid-n8n-systemd
+templates:
+  commonproject:
+    source: git@github.com:delorenj/CommonProject.git
+    required_clean: true
+  hermes_agent:
+    source: git@github.com:delorenj/hermes-agent-template.git
+    required_clean: true
+schemas:
+  project_json: 1
+  role_yaml: 1
+  agents_registry: 2
+  profile_yaml: 1
+n8n:
+  mode: generated-workflows
+  source_of_truth: pjangler
+systemd:
+  fallback: true
+  required_units:
+    - gateway
+    - consumer
+    - fallback-heartbeat
+```
+
+## n8n Workflow Model
+
+### Supervisor Workflow
+
+Trigger:
+
+- Schedule Trigger for periodic health.
+- Webhook for manual or external Fleet events.
+
+Flow:
+
+1. Fetch Fleet status from `pjangler`.
+2. Normalize registry/profile/systemd rows.
+3. Split into managed agents and managed exceptions.
+4. Branch by status: healthy, drift, degraded, manual.
+5. Trigger targeted reconcile or notify operator.
+6. Respond with a concise Fleet summary.
+
+Design rules:
+
+- Normalize data before branch convergence.
+- Avoid accidental item-count fanout; use execute-once where independent calls
+  do not need per-agent items.
+- Prefer Set/If/Switch/Merge over Code nodes when possible.
+- Use HTTP Request for internal `pjangler`/Hermes APIs until dedicated nodes are
+  justified.
+
+### Per-Agent Workflow
+
+Trigger:
+
+- Supervisor dispatch.
+- Bloodbank or internal webhook command.
+
+Flow:
+
+1. Load one agent entry.
+2. Check gateway, consumer, fallback heartbeat, profile symlink, runtime repo,
+   and role manifest.
+3. If safe drift exists, call `pj fleet reconcile --agent <id> --apply`.
+4. If unsafe drift exists, emit manual action.
+5. Record result for supervisor.
+
+## Command Surface
+
+```text
+pj templates status [--json]
+pj fleet status [--json] [--agent <id>]
+pj fleet reconcile [--dry-run] [--apply] [--agent <id>]
+pj fleet validate [--json]
+pj fleet n8n export [--workflow supervisor|agent] [--json]
+pj fleet n8n validate
+pj fleet n8n create --name <workflow>
+```
+
+## Data and Schema Ownership
+
+- `.project.json`: owned by CommonProject and pjangler migrations.
+- `role.yaml`: owned by hermes-agent-template, validated by pjangler.
+- `agents-registry.yaml`: owned by Fleet runtime/provisioning, reconciled by
+  pjangler.
+- `profile.yaml`: owned by Hermes runtime, validated for inheritance metadata.
+- `fleet-contract.yaml`: owned by pjangler and committed in the control-plane
+  repo.
+
+## Current Drift Repair Targets
+
+- Dirty vendored `templates/hermes-agent` must be promoted or reverted.
+- Heartbeat v2 must become a deliberate contract, not a dirty submodule state.
+- `runtime_scaffold_dir` must point at an existing fallback path.
+- Registry Hermes paths must be refreshed from `fleet.env`.
+- Invalid generated role model fields such as `model.name: "plane"` must fail
+  schema validation.
+
+## Rollout Strategy
+
+1. Add schemas and read-only status commands.
+2. Add dirty-template gates.
+3. Add safe reconcile for wrapper/profile/registry path drift.
+4. Promote heartbeat v2 contract and systemd fallback behavior.
+5. Generate and validate n8n supervisor workflow.
+6. Enable workflow creation only after exported workflow validation passes.
+

package/templates/hermes-agent/docs/fleet-control-plane/epics-and-stories.md

@@ -0,0 +1,280 @@
+---
+stepsCompleted: [1, 2, 3, 4]
+inputDocuments:
+  - docs/fleet-control-plane/prd.md
+  - docs/fleet-control-plane/architecture.md
+workflowType: epics-and-stories
+project_name: Fleet Control Plane
+date: 2026-06-27
+status: draft-ready
+---
+
+# Fleet Control Plane - Epic Breakdown
+
+## Requirements Inventory
+
+### Functional Requirements
+
+- FR1: Define a versioned Fleet contract.
+- FR2: Report effective template source, commit, tag, and dirty state.
+- FR3: Report registry/profile/role/systemd/fleet env drift.
+- FR4: Reconcile safe drift through dry-run and explicit apply modes.
+- FR5: Support managed exceptions.
+- FR6: Validate core manifests with schemas.
+- FR7: Block release on dirty vendored templates.
+- FR8: Implement n8n plus systemd hybrid heartbeat.
+- FR9: Keep n8n as orchestration, not source of truth.
+- FR10: Generate and validate n8n workflows.
+- FR11: Repair known current drift.
+- FR12: Keep default commands read-only.
+
+### Non-Functional Requirements
+
+- NFR1: Default to dry-run/read-only.
+- NFR2: Never destroy ambiguous runtime state automatically.
+- NFR3: Keep local fallback alive when n8n is down.
+- NFR4: Produce deterministic, grep-friendly output.
+- NFR5: Support CLI and npm release gates.
+- NFR6: Keep secrets out of committed artifacts.
+- NFR7: Preserve fast solo iteration.
+- NFR8: Validate n8n workflows before creation.
+
+## Epic List
+
+1. Fleet contract and schema foundation.
+2. Template source status and release gates.
+3. Fleet status and reconciliation.
+4. Hybrid heartbeat and n8n workflow generation.
+5. Drift repair and rollout hardening.
+
+## Epic 1: Fleet Contract and Schema Foundation
+
+Goal: Establish the explicit contract that all other implementation work checks
+against.
+
+### Story 1.1: Add Fleet Contract Schema
+
+As the Fleet operator, I want a committed Fleet contract schema so that template
+versions, service model, and manifest versions are explicit.
+
+Acceptance Criteria:
+
+- Given the repo contains no Fleet contract, when `pj fleet validate` runs, then
+  it reports the missing contract clearly.
+- Given a valid `fleet-contract.yaml`, when validation runs, then schema version,
+  service model, template entries, and schema versions pass.
+- Given an unsupported service model, when validation runs, then the command
+  fails with the invalid value and allowed values.
+
+### Story 1.2: Add Manifest Schemas
+
+As an implementer, I want schemas for `.project.json`, `role.yaml`,
+`agents-registry.yaml`, and `profile.yaml` so invalid generated state fails
+early.
+
+Acceptance Criteria:
+
+- Given `role.yaml` has `model.provider: ""` and `model.name: "plane"`, when
+  validation runs, then it reports an invalid model override.
+- Given registry entries lack exception metadata for non-standard profiles, when
+  validation runs, then they are classified as unmanaged drift.
+- Given profile metadata includes `config.inherit_from: default` and
+  `save_mode: delta`, when validation runs, then inheritance contract passes.
+
+### Story 1.3: Add Managed Exception Model
+
+As the Fleet operator, I want explicit managed exceptions so that special
+profiles do not pollute drift reports.
+
+Acceptance Criteria:
+
+- Given a voice-agent profile exists outside the PM scaffold, when it is marked
+  `managed: false` and `kind: voice-agent`, then `pj fleet status` reports it
+  under exceptions.
+- Given an unregistered profile exists without exception metadata, when status
+  runs, then it reports manual classification required.
+- Given an exception has notes, when status runs with `--json`, then notes are
+  included.
+
+## Epic 2: Template Source Status and Release Gates
+
+Goal: Make template bytes and release safety visible.
+
+### Story 2.1: Implement `pj templates status`
+
+As the Fleet operator, I want to see effective template sources so I know which
+bytes provisioning will use.
+
+Acceptance Criteria:
+
+- Given `PJANGLER_HERMES_TEMPLATE` is set, when status runs, then it reports the
+  env override as effective source.
+- Given vendored templates exist, when status runs, then it reports commit,
+  branch, dirty state, and submodule path.
+- Given local template checkout exists but vendored template takes precedence,
+  when status runs, then it shows both and explains precedence.
+
+### Story 2.2: Add Dirty Vendored Template Gate
+
+As a package maintainer, I want publish/build to fail on dirty vendored
+templates so experiments do not ship accidentally.
+
+Acceptance Criteria:
+
+- Given `templates/hermes-agent` has modified files, when `npm run prepublishOnly`
+  runs, then it fails before packaging.
+- Given a submodule pointer changed cleanly and is committed, when the gate runs,
+  then it passes.
+- Given generated runtime submodule changes are present, when the gate runs, then
+  it reports them separately from template dirtiness.
+
+### Story 2.3: Add Template Drift Guidance
+
+As an implementer, I want actionable drift messages so I know whether to promote
+or revert template changes.
+
+Acceptance Criteria:
+
+- Given vendored `templates/hermes-agent` differs from `~/code/hermes-agent-template`,
+  when status runs, then it recommends promote, update pointer, or discard.
+- Given CommonProject vendored commit lags local checkout, when status runs, then
+  it reports pinned-vs-local delta without failing by default.
+- Given `--strict` is passed, when local and vendored template commits differ,
+  then the command exits non-zero.
+
+## Epic 3: Fleet Status and Reconciliation
+
+Goal: Turn implicit Fleet drift into deterministic status and safe repair.
+
+### Story 3.1: Implement `pj fleet status`
+
+As the Fleet operator, I want one command to compare registry, profiles,
+role manifests, fleet env, runtime repos, and systemd units.
+
+Acceptance Criteria:
+
+- Given registry and profile symlink agree, when status runs, then the agent is
+  healthy for that check.
+- Given a registry entry points at a stale Hermes binary path, when status runs,
+  then it reports stale metadata and the effective `fleet.env` path.
+- Given systemd units are checkpoint-era while the contract says heartbeat-era,
+  when status runs, then it reports service model drift.
+
+### Story 3.2: Implement Safe `pj fleet reconcile`
+
+As the Fleet operator, I want safe drift repaired explicitly so routine fixes
+are repeatable.
+
+Acceptance Criteria:
+
+- Given a wrapper differs from the template and no runtime state is at risk, when
+  `--apply` runs, then the wrapper is regenerated.
+- Given a profile path is a real directory where a symlink is expected, when
+  reconcile runs, then it reports manual action and does not delete anything.
+- Given runtime `profile.yaml` is missing inherited config metadata, when
+  `--apply` runs, then metadata is inserted without removing other fields.
+
+### Story 3.3: Add Current Drift Repair Commands
+
+As the Fleet operator, I want known current drift addressed by idempotent repair
+paths.
+
+Acceptance Criteria:
+
+- Given config fallback `runtime_scaffold_dir` points at a missing path, when
+  repair runs, then it updates to an existing template scaffold path.
+- Given registry entries have stale Hermes paths, when repair runs, then they
+  update from `fleet.env`.
+- Given invalid `role.yaml` model override exists, when repair runs, then it
+  removes or corrects the bad override.
+
+## Epic 4: Hybrid Heartbeat and n8n Workflow Generation
+
+Goal: Promote heartbeat v2 deliberately as n8n orchestration plus systemd
+fallback.
+
+### Story 4.1: Define Heartbeat v2 Contract
+
+As the Fleet operator, I want heartbeat v2 specified so checkpoint and heartbeat
+models do not coexist accidentally.
+
+Acceptance Criteria:
+
+- Given `service_model: hybrid-n8n-systemd`, when validation runs, then required
+  gateway, consumer, and fallback heartbeat expectations are checked.
+- Given a checkpoint-only agent exists during migration, when status runs, then
+  it is classified as legacy rather than broken.
+- Given a heartbeat-enabled agent exists, when status runs, then n8n registration
+  and systemd fallback are both checked.
+
+### Story 4.2: Export n8n Supervisor Workflow
+
+As the Fleet operator, I want `pjangler` to generate an n8n supervisor workflow
+so orchestration is reviewable and reproducible.
+
+Acceptance Criteria:
+
+- Given Fleet status JSON, when workflow export runs, then the generated
+  workflow normalizes agent rows before branching.
+- Given n8n workflow validation is available, when `pj fleet n8n validate` runs,
+  then it validates generated code before any workflow is created.
+- Given n8n is unavailable, when export runs, then local workflow code is still
+  generated without creating remote state.
+
+### Story 4.3: Add Per-Agent n8n Workflow Pattern
+
+As the Fleet operator, I want per-agent workflows so health and delegation can
+be visualized without hand-wiring every agent.
+
+Acceptance Criteria:
+
+- Given an agent id, when per-agent workflow export runs, then workflow input is
+  scoped to one registry entry.
+- Given safe drift is found, when the workflow is executed, then it calls the
+  dry-run reconcile path first.
+- Given unsafe drift is found, when the workflow is executed, then it emits a
+  manual action instead of applying changes.
+
+## Epic 5: Rollout Hardening
+
+Goal: Make the migration safe enough to run on the live Fleet.
+
+### Story 5.1: Add Readiness Gates
+
+As the Fleet operator, I want a single readiness command so I know when
+implementation is ready for live Fleet rollout.
+
+Acceptance Criteria:
+
+- Given schemas, status, reconcile dry-run, template gate, and n8n validation
+  pass, when readiness runs, then it reports ready.
+- Given any current drift remains unresolved, when readiness runs, then it lists
+  blockers by agent or file.
+- Given managed exceptions exist, when readiness runs, then it excludes them
+  from blockers and includes them in a separate exception count.
+
+### Story 5.2: Document Operator Runbook
+
+As a future agent/operator, I want a runbook so rollout and rollback are clear.
+
+Acceptance Criteria:
+
+- Given the runbook, a reader can run status, validation, export, dry-run
+  reconcile, apply reconcile, and rollback.
+- Given n8n is down, the runbook explains systemd fallback verification.
+- Given a dirty vendored template blocks release, the runbook explains promote
+  versus revert choices.
+
+### Story 5.3: Smoke Test Against Live Fleet
+
+As the Fleet operator, I want proof against real local state before marking the
+work done.
+
+Acceptance Criteria:
+
+- Given the live registry, when status runs, then it completes and returns JSON.
+- Given a selected low-risk agent, when reconcile dry-run runs, then it reports
+  expected changes without mutation.
+- Given n8n workflow code is generated, when validation runs, then no workflow is
+  created until validation succeeds.
+

package/templates/hermes-agent/docs/fleet-control-plane/implementation-readiness-report-2026-06-27.md

@@ -0,0 +1,118 @@
+---
+stepsCompleted: [1, 2, 3, 4, 5, 6]
+inputDocuments:
+  - docs/fleet-control-plane/prd.md
+  - docs/fleet-control-plane/architecture.md
+  - docs/fleet-control-plane/epics-and-stories.md
+workflowType: implementation-readiness
+project_name: Fleet Control Plane
+date: 2026-06-27
+status: ready-with-known-blockers
+---
+
+# Implementation Readiness Assessment Report
+
+**Date:** 2026-06-27
+**Project:** Fleet Control Plane
+
+## Summary
+
+The implementation plan is coherent and ready to begin, with known blockers that
+should be handled in the first implementation epic rather than deferred.
+
+The strongest architecture choice is the hybrid model:
+
+- n8n coordinates Fleet workflows visually.
+- `pjangler` remains the control-plane and validation source.
+- systemd keeps local survival behavior in place.
+
+## Document Inventory
+
+- PRD: `docs/fleet-control-plane/prd.md`
+- Architecture: `docs/fleet-control-plane/architecture.md`
+- Epics and stories: `docs/fleet-control-plane/epics-and-stories.md`
+- Existing operational docs: `docs/architecture.md`, `docs/operations.md`
+
+## Alignment Review
+
+### PRD to Architecture
+
+Pass. Each major requirement maps to an architecture decision:
+
+- Fleet contract maps to ADR-001.
+- `pjangler` control plane maps to ADR-002.
+- n8n orchestration maps to ADR-003.
+- hybrid heartbeat maps to ADR-004.
+- managed exceptions map to ADR-005.
+
+### Architecture to Epics
+
+Pass. The epics cover the required implementation sequence:
+
+1. Define contract and schemas.
+2. Make template sources visible and gated.
+3. Add status and reconcile.
+4. Promote heartbeat v2 and generate n8n workflows.
+5. Harden rollout.
+
+### Risk Coverage
+
+Mostly pass. The plan explicitly covers:
+
+- n8n outage fallback.
+- dirty vendored templates.
+- stale registry paths.
+- ambiguous profile/runtime state.
+- workflow validation before creation.
+- managed exceptions.
+
+Remaining risk: exact n8n workflow node parameters must be validated during
+implementation using the n8n workflow SDK before creating live workflows.
+
+## Known Blockers to Resolve First
+
+1. Dirty vendored `pjangler/templates/hermes-agent` currently contains heartbeat
+   v2 changes that are not cleanly promoted into `hermes-agent-template`.
+2. Current `hermes-agent-template` clean tree still describes checkpoint timers,
+   while pjangler parity expects heartbeat timers.
+3. `~/.config/hermes-agent-template/config.toml` has a missing fallback scaffold
+   path.
+4. `~/.hermes/agents-registry.yaml` contains stale Hermes path metadata.
+5. Some profiles exist outside registry coverage and need managed exception
+   classification.
+6. At least one generated role manifest has invalid model fields.
+
+## Readiness Decision
+
+Status: ready to implement Epic 1.
+
+Do not start live n8n workflow creation until these gates are available:
+
+- Schema validation exists.
+- Template status reports clean/dirty state.
+- Fleet status can run read-only against the live registry.
+- n8n workflow export can be validated without creating remote workflows.
+
+## First Implementation Slice
+
+The first slice should be deliberately boring:
+
+1. Add `fleet-contract.yaml` draft and schema.
+2. Add manifest schemas.
+3. Add `pj templates status --json`.
+4. Add dirty vendored template detection.
+5. Add `pj fleet status --json` with read-only checks only.
+
+This gives immediate visibility and reduces risk before any mutating reconcile
+or n8n creation work begins.
+
+## Implementation Exit Gates
+
+- All schema tests pass.
+- `pj templates status --json` reports no unclassified dirty template state.
+- `pj fleet status --json` reports all managed drift with stable identifiers.
+- Managed exceptions are explicitly recorded.
+- `pj fleet reconcile` defaults to dry-run.
+- n8n workflow code validates before creation.
+- Existing docs are updated to reflect heartbeat v2 or checkpoint legacy mode.
+