@delorenj/pjangler 1.2.25 → 1.3.0

package/templates/commonproject/tests/test_sync_skills_topology.py

@@ -1,120 +0,0 @@
-from __future__ import annotations
-
-import importlib.util
-import os
-import tempfile
-import unittest
-from pathlib import Path
-
-
-ROOT = Path(__file__).parents[1]
-SCRIPT = ROOT / "template" / ".mise" / "scripts" / "sync-skills.py"
-PROVISION_SCRIPT = ROOT / "template" / ".mise" / "scripts" / "provision-bmad-skills.py"
-SPEC = importlib.util.spec_from_file_location("sync_skills", SCRIPT)
-assert SPEC is not None and SPEC.loader is not None
-SYNC = importlib.util.module_from_spec(SPEC)
-SPEC.loader.exec_module(SYNC)
-
-
-class SyncSkillsTopologyTests(unittest.TestCase):
-    def setUp(self) -> None:
-        self.temporary = tempfile.TemporaryDirectory(prefix="commonproject-sync-topology-")
-        self.root = Path(self.temporary.name)
-        self.project = self.root / "project"
-        self.source = self.root / "source-skill"
-        self.project.mkdir()
-        self.source.mkdir()
-        (self.source / "SKILL.md").write_text("source\n")
-
-    def tearDown(self) -> None:
-        self.temporary.cleanup()
-
-    def test_shipped_skill_scripts_are_executable(self) -> None:
-        for script in (PROVISION_SCRIPT, SCRIPT):
-            self.assertNotEqual(
-                script.stat().st_mode & 0o111,
-                0,
-                f"fresh template script must be executable: {script}",
-            )
-
-    def test_canonical_claude_alias_is_accepted_without_mutating_managed_projection(self) -> None:
-        managed = self.project / ".agents" / "skills"
-        custom = managed / "custom-real-skill"
-        custom.mkdir(parents=True)
-        (custom / "SKILL.md").write_text("custom\n")
-        claude = self.project / ".claude"
-        claude.mkdir()
-        (claude / "skills").symlink_to("../.agents/skills", target_is_directory=True)
-
-        SYNC.fanout_to_cli(self.project, {"managed-example": self.source})
-
-        self.assertTrue((claude / "skills").is_symlink())
-        self.assertEqual(os.readlink(claude / "skills"), "../.agents/skills")
-        self.assertEqual((custom / "SKILL.md").read_text(), "custom\n")
-        self.assertFalse(
-            (managed / "managed-example").exists(),
-            "the canonical alias must not make sync-skills mutate the provisioner-owned projection",
-        )
-
-    def test_external_cli_symlink_fails_before_any_destination_mutation(self) -> None:
-        codex = self.project / ".codex"
-        codex.mkdir()
-        claude = self.project / ".claude"
-        claude.mkdir()
-        outside = self.root / "outside"
-        outside.mkdir()
-        (outside / "sentinel").write_text("do-not-touch\n")
-        (claude / "skills").symlink_to(outside, target_is_directory=True)
-
-        with self.assertRaisesRegex(ValueError, "Refusing symlinked CLI skills directory"):
-            SYNC.fanout_to_cli(self.project, {"managed-example": self.source})
-
-        self.assertFalse((codex / "skills").exists())
-        self.assertEqual(list(outside.iterdir()), [outside / "sentinel"])
-        self.assertEqual((outside / "sentinel").read_text(), "do-not-touch\n")
-
-    def test_broken_canonical_alias_fails_before_mutation(self) -> None:
-        codex = self.project / ".codex"
-        codex.mkdir()
-        claude = self.project / ".claude"
-        claude.mkdir()
-        (claude / "skills").symlink_to("../.agents/skills", target_is_directory=True)
-
-        with self.assertRaisesRegex(ValueError, "alias target is not a real directory"):
-            SYNC.fanout_to_cli(self.project, {"managed-example": self.source})
-
-        self.assertFalse((codex / "skills").exists())
-        self.assertTrue((claude / "skills").is_symlink())
-
-    def test_parent_swap_after_preflight_cannot_mutate_outside_project(self) -> None:
-        codex = self.project / ".codex"
-        codex.mkdir()
-        outside = self.root / "outside"
-        outside_skill = outside / "skills" / "managed-example"
-        outside_skill.mkdir(parents=True)
-        (outside / "sentinel").write_text("outside must survive\n")
-        (outside_skill / "user-data").write_text("do not delete\n")
-        active = SYNC.preflight_cli_dirs(self.project, ["managed-example"])
-        original_codex = self.project / ".codex-original"
-
-        def swap_parent() -> None:
-            codex.rename(original_codex)
-            codex.symlink_to(outside, target_is_directory=True)
-
-        with self.assertRaisesRegex(ValueError, "symlinked destination directory"):
-            SYNC.fanout_to_cli(
-                self.project,
-                {"managed-example": self.source},
-                active_cli_dirs=active,
-                before_mutation=swap_parent,
-            )
-
-        self.assertTrue(codex.is_symlink())
-        self.assertFalse((original_codex / "skills").exists())
-        self.assertEqual((outside / "sentinel").read_text(), "outside must survive\n")
-        self.assertEqual((outside_skill / "user-data").read_text(), "do not delete\n")
-        self.assertTrue(outside_skill.is_dir())
-
-
-if __name__ == "__main__":
-    unittest.main()

package/templates/hermes-agent/README.md

@@ -1,192 +0,0 @@
-# hermes-agent-template
-
-Copier template that provisions a single Hermes agent role into an existing
-repository, complete with its own ignored per-agent runtime directory for
-memory and session state.
-
-## 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, optional Slack wiring, pure-local runtime, 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** systemd timer. Under the current
-pure-local runtime contract, that tick performs board reconciliation only.
-(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 ignored local state at `agents/hermes/pm/runtime/` (== HERMES_HOME)
-5. Populate missing files from the runtime scaffold (config.yaml, SOUL.md, memories)
-6. Refuse any stale project gitlink or `.gitmodules` mapping for that runtime
-7. Verify a profile-dedicated BotFather token and store it only in `runtime/.env`
-8. Defer Slack by default, or verify and store an explicitly supplied dedicated Slack app+bot pair in `runtime/.env`
-9. Create a Plane project in your configured workspace
-10. Mark Bloodbank ingress as fleet-scoped, with no per-profile consumer
-11. Install systemd `--user` units: profile gateway and board-reconciliation heartbeat timer
-12. Append the agent and its Bloodbank `target_agent_id` 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` | `hermes_git_url`, `hermes_git_ref`, `hermes_git_sha` | Reviewed Hermes fork publication used by clean installs and fleet audit metadata |
-| `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 |
-| `plane` | `base`, `workspace` | Plane URL + workspace slug |
-
-The example configuration retains an inert `[github].runtime_repo_owner` value
-only so older manifests can still be parsed. Current provisioning never reads
-it to create, attach, synchronize, restore, or retire runtime storage.
-
-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/                            ← ignored local HERMES_HOME
-│       (HERMES_HOME for this agent)
-│       └── .env                            ← profile-local channel credentials, mode 0600, gitignored
-└── ...
-
-~/.hermes/agents-registry.yaml              ← fleet roster
-~/.hermes/fleet.env                          ← shared Hermes binary/repo pointer
-~/.config/systemd/user/                     ← per-profile gateway + heartbeat timer
-```
-
-Bloodbank command ingress is not a per-profile daemon. One fleet-shared Hermes
-gateway reads the registry and routes canonical commands by
-`data.target_agent_id`; local runtime directories contain no NATS consumer or
-inbox bridge.
-Provisioning and `fleet-sync.sh --apply` also retire the old
-`hermes-<agent>-consumer.service`, even when an older `.done-70-systemd` marker
-exists. Retirement fails closed: a user-manager/query error, failed disable, or
-anything short of explicit `inactive` plus `disabled` leaves the unit file and
-registry metadata intact and reports unhealthy drift.
-
-Telegram and Slack ownership checks, identity claims, runtime credential
-writes, and registry upserts serialize on `${registry_file}.lock`. The lock is
-held by `flock`, so a crashed process cannot leave a stale logical lock; registry
-writes use an atomic replace, sync the containing directory where supported, and
-keep both registry and lock at mode `0600`. Profile credential replacements use
-the same file-plus-parent durability boundary and remain safe to retry when a
-durability sync reports an error.
-
-## Reviewed Hermes runtime publication
-
-Clean installs use only the reviewed fleet fork publication below. The local
-installer verifies the commit belongs to the named ref and refuses an existing
-checkout whose `origin` points elsewhere:
-
-```bash
-git clone --branch feature/PJAN-19-routing-publication --single-branch \
-  https://github.com/delorenj/hermes-agent.git ~/.hermes/hermes-agent
-git -C ~/.hermes/hermes-agent rev-parse HEAD
-# 113e1b182b6d72a7dd02a191f134a41668ceaf0e
-```
-
-Do not install this fleet path from `NousResearch/hermes-agent` or mutate its
-`main` branch. Promotion happens on the fork publication ref and is pinned by
-full commit SHA in `config.example.toml` and each registry entry.
-
-## 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.
-
-Telegram bot tokens and Slack bot/app tokens are deliberately excluded from
-this shared layer. They belong only in the enabled agent's `runtime/.env` and
-are checked for local profile ownership during provisioning; fleet config may
-carry the non-secret `TELEGRAM_ALLOWED_USERS` and `SLACK_ALLOWED_USERS`
-policies as a convenience.
-
-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 retirement is deliberately non-destructive: stop the systemd units,
-detach the profile symlink, archive the Plane project, retire messaging bots,
-and remove the registry entry while preserving the ignored runtime directory.
-The verified-backup and no-automated-purge retention policy is in
-[Operations](docs/operations.md#retire-an-agent-preserves-runtime-by-default).

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

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

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

@@ -1,135 +0,0 @@
-# Architecture
-
-## Tracked role and local runtime 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/                        │ ← ignored local HERMES_HOME
-                  │          ├── config.yaml                │
-                  │          ├── memories/                  │
-                  │          ├── sessions/                  │
-                  │          └── .env                       │
-                  └─────────────────────────────────────────┘
-```
-
-## Why tracked role and local state are separate
-
-The **template** is the contract / the bootstrap recipe — it doesn't change
-when an agent learns something. The ignored **runtime directory** is the
-agent's accumulating local state — it changes every conversation. Separating
-them means:
-
-- The template repo is small, stable, easy to update fleet-wide
-- Project commits cannot accidentally publish runtime credentials or sessions
-- Each profile has an isolated HERMES_HOME without project-index churn
-- Provisioning can refresh tracked launchers and scaffolds without overwriting
-  existing local state
-
-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.
-
-## Durability boundary
-
-Ignored local state is not automatically durable. The operator must configure
-an encrypted filesystem backup or snapshot for each exact runtime path. A
-project clone restores only tracked role files and the empty scaffold.
-Hindsight retains only memories/events explicitly written to its bank, while a
-secret manager retains only credentials explicitly stored there; neither is a
-complete runtime backup. See [Operations](operations.md#back-up-and-restore-an-agent).
-
-## Heartbeat cadence
-
-A systemd `--user` timer runs `.scripts/heartbeat.sh` frequently (about once a
-minute). For a pure-local runtime, each tick performs one job:
-
-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).
-Sensitive state — `.env`, `auth.json`, OAuth tokens — never enters project Git.
-It lives only in ignored local storage unless the operator separately places a
-credential in the secret manager or includes the runtime in an encrypted
-filesystem backup.
-
-## One bot per agent (Telegram)
-
-Each agent gets its own BotFather bot and runs its own gateway daemon.
-The BotFather token is an invocation-only provisioning input: shared
-`fleet.env` may carry the non-secret allow-list policy but is never allowed to
-supply `TELEGRAM_BOT_TOKEN`. Provisioning verifies `getMe`, rejects a token or
-bot identity already owned anywhere in the local fleet, atomically writes the
-credential only to the profile's mode-`0600` `runtime/.env`, and records only
-safe identity metadata in `role.yaml` and the registry. Hermes' scoped runtime
-lock remains a second line of defense against duplicate pollers.
-
-## One app and bot per Slack-enabled agent
-
-Slack is opt-in and remains deferred for newly provisioned agents unless the
-operator explicitly enables it or supplies both required tokens. An enabled
-agent owns one dedicated `xapp-` Socket Mode token and one dedicated `xoxb-`
-bot token; provisioning rejects token reuse and a verified bot identity already
-owned by another registry entry.
-
-The bot token is verified through Slack's read-only `auth.test` endpoint.
-Credentials live only in the agent's mode-`0600`, gitignored `runtime/.env`.
-The shared `~/.hermes/.env`, `fleet.env`, `role.yaml`, and fleet registry never
-contain Slack tokens: manifests and registry entries retain only provisioning
-status, workspace identity, and bot identity. The non-secret allowed-user
-policy may be inherited from fleet config.
-
-## 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
-
-Bloodbank command ingress is owned by one fleet-shared official Hermes gateway,
-not by a consumer in every runtime. Each registry entry advertises:
-
-```yaml
-bloodbank:
-  gateway_scope: fleet
-  target_agent_id: <agent-id>
-```
-
-The shared gateway subscribes once, resolves `data.target_agent_id` through the
-fleet registry, and routes the turn into that Hermes profile. Per-profile
-messaging gateways and heartbeat timers remain independent; there is no
-per-profile NATS process, systemd consumer unit, or filesystem inbox bridge.
-
-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.
-
-The gateway uses the canonical lifecycle already defined by those schemas:
-
-- `bloodbank.v1.conversation.turn.started`
-- `bloodbank.v1.agent.invocation.started`
-- one terminal invocation event: `bloodbank.v1.agent.invocation.completed` or
-  `bloodbank.v1.agent.invocation.failed`
-- `bloodbank.v1.conversation.turn.completed`
-
-There are no separate `received` or `accepted` lifecycle events. A JetStream
-command is acknowledged only after Hermes processing completion and terminal
-event publication.

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.
-