@delorenj/pjangler 1.2.25 → 1.2.33

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

@@ -1,258 +0,0 @@
----
-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 each profile gateway and local fallback heartbeat/checkpoint alive
-
-fleet Bloodbank gateway
-  routes canonical commands to registered target_agent_id values
-```
-
-## 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 each profile gateway and heartbeat fallback running.
-- The fleet-shared Bloodbank gateway owns command-bus ingress for all profiles.
-- 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
-    - fallback-heartbeat
-bloodbank:
-  gateway_scope: fleet
-  routing_key: data.target_agent_id
-```
-
-## 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 profile gateway, fleet Bloodbank registration, 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

@@ -1,280 +0,0 @@
----
-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
-  profile gateway, fleet Bloodbank registration, 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

@@ -1,118 +0,0 @@
----
-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.
-