@delorenj/pjangler 1.2.21 → 1.2.33

package/templates/hermes-agent/README.md

@@ -1,151 +0,0 @@
-# hermes-agent-template
-
-Copier template that provisions a single Hermes agent role into an existing
-repository, complete with its own per-agent runtime repo for git-tracked
-memory/state checkpointing.
-
-## How it relates to CommonProject
-
-| | CommonProject | hermes-agent-template |
-| --- | --- | --- |
-| What it scaffolds | A new top-level project | An agent role inside an existing project |
-| Copier target | `./my-new-project/` | `./agents/hermes/<role>/` |
-| Asks | project name + description | role + purpose + tone |
-| Post-gen artifacts | Plane project, bmad init, mise tasks | Plane project, Telegram bot wiring, agent-hm-* runtime repo, systemd units |
-
-CommonProject runs first to create the umbrella project. hermes-agent-template
-runs second (for each agent role you want) to drop agents into it.
-
-## Roles
-
-The template provisions a single Hermes role per invocation. The `pm` role
-handles project management and triage, and also runs the continuous ticket
-sentinel out-of-band: a provider-agnostic board-reconciliation pass (Linear,
-Plane, or Trello) with an autonomous adversarial review (act, do not wait). The
-sentinel runs as the PM's **heartbeat** — a fused systemd timer tick that does
-the reconciliation pass and then a gated runtime checkpoint. (There is no
-separate `scrum-master` role; its duties folded into the PM heartbeat.)
-
-To work on or extend the heartbeat sentinel, start with the [sentinel handoff
-guide](docs/sentinel/README.md).
-
-## Quickstart
-
-```bash
-# Inside a project (e.g. ~/code/33GOD/bloodbank)
-copier copy gh:delorenj/hermes-agent-template ./agents/hermes/pm \
-  --data role=pm \
-  --data agent_purpose="Triage incoming bloodbank PRs and route work"
-```
-
-The template will:
-
-1. Seed `~/.config/hermes-agent-template/config.toml` from the shipped example (see [Configuration](#configuration))
-2. Ensure `~/.hermes/fleet.env` exists (single source of truth for shared Hermes binary/repo/registry)
-3. Create the hermes profile `<repo>-pm` via `hermes profile create --clone`
-4. Create a new private GitHub repo `<owner>/agent-hm-<repo>-pm` for the runtime
-5. Populate it with the runtime scaffold (config.yaml, SOUL.md, memories, consumer.py)
-6. Add it as a git submodule at `agents/hermes/pm/runtime/` (== HERMES_HOME)
-7. Prompt for a BotFather token, store it in `runtime/.env`
-8. Create a Plane project in your configured workspace
-9. Install systemd `--user` units: gateway, consumer, heartbeat timer (reconcile + checkpoint)
-10. Append the agent to `~/.hermes/agents-registry.yaml`
-
-## Configuration
-
-All environment-specific defaults live in **`~/.config/hermes-agent-template/config.toml`**
-(override the path with `$HERMES_TEMPLATE_CONFIG`). Nothing user-specific is
-hardcoded in the scripts — so the template can be handed to someone else and
-retargeted by editing one file.
-
-On the first provisioning run, `.scripts/01-config.sh` seeds that file from
-[`config.example.toml`](config.example.toml) if it doesn't exist yet, then warns
-you to review it. Keys:
-
-| Section | Key | What it sets |
-| --- | --- | --- |
-| `fleet` | `hermes_bin`, `hermes_repo` | Shared Hermes executable + repo checkout |
-| `fleet` | `fleet_env`, `registry_file` | Fleet source-of-truth + registry locations |
-| `fleet` | `oauth_file`, `codex_home` | Shared Hermes OAuth store + Codex CLI/app-server auth home |
-| `fleet` | `runtime_scaffold_dir` | Fallback scaffold (if agent-local one is missing) |
-| `fleet` | `canonical_skills_dir`, `symlinked_runtime_skills` | Skills mirrored into each profile |
-| `github` | `runtime_repo_owner` | Owner of the `agent-hm-*` runtime repos |
-| `plane` | `base`, `workspace` | Plane URL + workspace slug |
-| `bloodbank` | `nats_host`, `nats_port`, `compose_dir` | NATS endpoint + compose dir hint |
-
-Resolution precedence for every value: **explicit env var → `~/.hermes/fleet.env`
-→ `config.toml` → built-in fallback**. So you can still override any single value
-per-run with an env var or `--data`, and existing setups keep working even without
-the config file present.
-
-## What gets created where
-
-```
-your-project/
-├── agents/hermes/pm/                       ← copier output, tracked in YOUR project
-│   ├── role.yaml                           ← role manifest
-│   ├── SOUL.md                             ← personality (canonical)
-│   ├── hermes                              ← launcher
-│   ├── .scripts/                           ← provisioning scripts (idempotent re-run)
-│   └── runtime/                            ← git submodule → agent-hm-<repo>-pm
-│       (HERMES_HOME for this agent)
-└── ...
-
-github.com/delorenj/agent-hm-<repo>-pm/     ← new private repo, this agent's state
-├── config.yaml                             ← cloned from global ~/.hermes
-├── SOUL.md                                 ← evolves over time
-├── memories/{MEMORY,USER}.md
-├── sessions/sessions.db                    ← LFS-tracked
-├── decisions/                              ← markdown files, one per call
-├── bloodbank-consumer.py
-└── .gitattributes / .gitignore             ← LFS rules + secret guards
-
-~/.hermes/agents-registry.yaml              ← fleet roster
-~/.hermes/fleet.env                          ← shared Hermes binary/repo pointer
-~/.config/systemd/user/                     ← gateway, consumer, heartbeat timer
-```
-
-## Fleet single source-of-truth
-
-All generated launchers read `~/.hermes/fleet.env` for:
-
-- `HERMES_FLEET_BIN`
-- `HERMES_FLEET_REPO`
-- `HERMES_FLEET_REGISTRY_FILE`
-- `HERMES_FLEET_OAUTH_FILE`
-- `HERMES_FLEET_CODEX_HOME`
-
-If you sync/pull your shared Hermes repo and keep the same binary path, every
-agent wrapper picks it up automatically. `HERMES_FLEET_OAUTH_FILE` is the
-shared Hermes provider OAuth store, including `openai-codex`; `HERMES_FLEET_CODEX_HOME`
-is the shared Codex CLI/app-server config/auth home.
-
-To retrofit existing wrappers and user systemd units:
-
-```bash
-cd /home/delorenj/code/hermes-agent-template
-./scripts/backfill-fleet-sot.sh
-```
-
-## Architecture
-
-See `docs/architecture.md`.
-
-## Re-running individual steps
-
-Every `.scripts/<NN>-*.sh` is idempotent. Drop the `.done-<NN>-*` marker file
-to force re-run:
-
-```bash
-cd agents/hermes/pm
-rm .scripts/.done-40-plane
-SKIP_TELEGRAM=1 SKIP_SYSTEMD=1 ./.scripts/40-plane.sh
-```
-
-## Retiring an agent
-
-(TODO: ship `retire.sh` in v1.1)
-
-Manual: stop systemd units, `hermes profile delete`, archive the Plane
-project, `/deletebot` in BotFather, archive the
-`agent-hm-*` runtime repo, remove the registry entry.

package/templates/hermes-agent/config.example.toml

@@ -1 +0,0 @@
-template/.scripts/config.example.toml

package/templates/hermes-agent/docs/architecture.md

@@ -1,111 +0,0 @@
-# Architecture
-
-## Two-artifact split
-
-```
-┌──────────────────────────────────────────────────────────────────────────┐
-│                                                                          │
-│   gh:delorenj/hermes-agent-template       ← Copier template (this repo)  │
-│   ─────────────────────────────────       used once per role            │
-│                                                                          │
-│        copier copy ... ./agents/hermes/<role>                           │
-│                                                                          │
-└──────────────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-                  ┌────────────────────────────────┐
-                  │  your-project/                  │
-                  │   agents/hermes/<role>/         │  ← in YOUR project git
-                  │     ├── role.yaml               │
-                  │     ├── SOUL.md                 │
-                  │     ├── hermes (launcher)       │
-                  │     ├── .scripts/               │
-                  │     └── runtime/    ────────────┼─── git submodule
-                  └────────────────────────────────┘     │
-                                                          ▼
-                  ┌────────────────────────────────────────┐
-                  │  gh:delorenj/agent-hm-<project>-<role> │ ← NEW repo per agent
-                  │  ───────────────────────────────────── │   private
-                  │     ├── config.yaml                    │
-                  │     ├── SOUL.md (evolving)             │
-                  │     ├── memories/                      │   auto-checkpointed
-                  │     ├── sessions/sessions.db  (LFS)    │   by the heartbeat
-                  │     ├── decisions/                     │   + on session end
-                  │     └── bloodbank-consumer.py          │
-                  └────────────────────────────────────────┘
-```
-
-## Why two artifacts, not one
-
-The **template** is the contract / the bootstrap recipe — it doesn't change
-when an agent learns something. The **runtime** is the agent's accumulating
-state — it changes every conversation. Bundling them would mean every memory
-update churns the template's commit log; separating them means:
-
-- The template repo is small, stable, easy to update fleet-wide
-- The runtime repo is per-agent, fast-moving, auditable in isolation
-- You can fork an agent (branch the runtime repo) without touching others
-- You can wipe an agent (delete the runtime repo) without affecting the template
-
-A third file ties the fleet together: `~/.hermes/fleet.env`.
-It is the single source-of-truth pointer for the shared Hermes executable/repo
-that every generated launcher uses.
-
-## Why git-tracked runtime
-
-The runtime is the agent's "subjective experience" — its memory of every
-conversation, the SOUL refinements it has absorbed, the decisions it has
-emitted. Putting it in git gives:
-
-- **Durability**: nothing lost when the host dies. `git clone` restores it.
-- **Auditability**: `git log` is a full trace of how the agent evolved.
-- **Reversibility**: if the agent develops bad habits, `git revert` rolls back.
-- **Forkability**: experiment with a copy on a branch, merge if it works out.
-- **Cross-machine**: same agent state on big-chungus and on the laptop.
-
-## Heartbeat cadence (reconcile + checkpoint)
-
-A systemd `--user` timer runs `.scripts/heartbeat.sh` frequently (about once a
-minute). Each tick fuses two jobs into one:
-
-1. **Board-reconciliation sentinel pass** — the PM's continuous ticket sentinel.
-   The runner's own cooldown/lock logic decides whether a full, LLM-backed
-   reconciliation pass is worth running (it rate-limits the expensive Hermes
-   call); see [the sentinel docs](sentinel/README.md).
-2. **Gated runtime checkpoint** — after the sentinel decision, the runner calls
-   `.scripts/checkpoint.sh`, gated to at most once an hour. The checkpoint:
-   `cd`s into the runtime submodule, `git add -A`, commits only if dirty (exits
-   clean otherwise), and pushes to `origin`.
-
-On session end, a hermes hook (TBD path) checkpoints immediately so nothing
-in-flight is lost between heartbeat ticks.
-
-Sensitive state — `.env`, `auth.json`, OAuth tokens — never enters git.
-They're in `.gitignore` and live only on the host machine.
-
-## One bot per agent (Telegram)
-
-Each agent gets its own BotFather bot and runs its own gateway daemon.
-Hermes' `gateway/status.py:acquire_scoped_lock(scope="telegram", identity=<token>)`
-already enforces "one token per gateway process" — so even if two profiles
-happen to share a token, the second one's startup fails fast. The N×M cost
-(N BotFather sessions per fleet) is the price we accept for zero custom
-routing code.
-
-## One Plane project per agent
-
-A Plane "project" is the natural unit of work isolation. Mixing agents into a
-shared project would conflate decisions and break filters. 1:1 also makes
-archive-on-retire clean.
-
-## Bloodbank wiring
-
-Each consumer subscribes to two lanes:
-- `bloodbank.evt.v1.repo.>` — canonical repo-domain events, filtered by `data.repo`
-- `bloodbank.cmd.v1.agent.>` — canonical agent-domain commands, filtered by `data.target_agent_id`
-
-Each agent emits CloudEvents 1.0 envelopes with `actor.agent_id`,
-`producer = hermes-agent:<id>`, `source = hermes://agent/<id>`. The naming
-contract is owned by Bloodbank (`~/code/33GOD/bloodbank/docs/event-naming.md`).
-Repo and agent identifiers belong in envelope data, actor, or source fields,
-never in type or subject tokens.

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

@@ -1,35 +0,0 @@
----
-workflowType: fleet-control-plane-artifacts
-date: 2026-06-27
-status: draft-ready
-source: adapted-bmad
----
-
-# Fleet Control Plane Implementation Artifacts
-
-This folder captures the implementation plan for tightening the Fleet without
-collapsing its repos into one codebase.
-
-The Fleet remains a set of independently useful parts:
-
-- `CommonProject` owns the base project scaffold.
-- `hermes-agent-template` owns agent-role provisioning.
-- `~/.hermes` owns live runtime state.
-- `~/.hermes/hermes-agent` owns the Hermes engine checkout and binary.
-- `pjangler` becomes the explicit Fleet control plane.
-- n8n becomes the visual orchestration layer, backed by local systemd fallback.
-
-## Artifacts
-
-- [prd.md](./prd.md) - Functional and non-functional requirements.
-- [architecture.md](./architecture.md) - Technical architecture and ADRs.
-- [epics-and-stories.md](./epics-and-stories.md) - Implementation backlog with acceptance criteria.
-- [implementation-readiness-report-2026-06-27.md](./implementation-readiness-report-2026-06-27.md) - Readiness assessment and launch gates.
-
-## Adapted BMAD Note
-
-The formal BMAD workflow expects a project-local `_bmad` runtime, PRD, and
-step-by-step user confirmations. This repo does not currently contain `_bmad`.
-These artifacts preserve the BMAD intent and structure while using the live
-architecture review and advanced elicitation decisions as input.
-

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

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