@delorenj/pjangler 1.2.21 → 1.2.33

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

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

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

@@ -1,141 +0,0 @@
----
-stepsCompleted: [1]
-inputDocuments:
-  - docs/architecture.md
-  - docs/operations.md
-  - README.md
-  - /home/delorenj/code/pjangler/src/commands/hermes/RunCopierTemplate.ts
-  - /home/delorenj/code/pjangler/src/parity/index.ts
-  - /home/delorenj/.hermes/agents-registry.yaml
-workflowType: prd
-project_name: Fleet Control Plane
-date: 2026-06-27
-status: draft-ready
----
-
-# Fleet Control Plane PRD
-
-## Problem
-
-The Fleet is composed of valuable independent repos and runtime surfaces, but
-the binding contract between them is implicit and drifting.
-
-Current symptoms include:
-
-- `pjangler` is already the de facto control plane, but its role is not stated
-  as an architectural contract.
-- `pjangler/templates/hermes-agent` can carry dirty vendored template changes
-  that differ from `~/code/hermes-agent-template`.
-- The live fleet uses checkpoint timers while newer dirty template work points
-  toward heartbeat timers.
-- The registry, profiles, fleet env, systemd units, and role manifests can
-  disagree without one authoritative reconciliation path.
-- n8n is a promising visual orchestration layer, but should not become another
-  competing source of truth.
-
-## Product Goal
-
-Make `pjangler` the explicit Fleet control plane and introduce a versioned Fleet
-contract that lets the independent parts stay independent while making their
-runtime coupling visible, validated, and repairable.
-
-## Users
-
-- Primary operator: Deloren, managing a personal but production-like fleet.
-- Agent implementers: Codex, Hermes PM agents, and future worker agents acting
-  from explicit contracts.
-- Visual orchestrator: n8n workflows that coordinate Fleet health, delegation,
-  and reconciliation.
-
-## Functional Requirements
-
-FR1: The system shall define a versioned Fleet contract that records template
-source versions, service model, schema versions, and supported runtime modes.
-
-FR2: `pjangler` shall expose `pj templates status` to report each vendored
-template source, commit, tag, dirty state, and effective provisioning source.
-
-FR3: `pjangler` shall expose `pj fleet status` to compare the Fleet contract
-against `~/.hermes/fleet.env`, `~/.hermes/agents-registry.yaml`, profiles,
-role manifests, runtime repos, and systemd units.
-
-FR4: `pjangler` shall expose `pj fleet reconcile` with dry-run by default and
-explicit `--apply` mutation mode.
-
-FR5: The Fleet registry shall support managed exceptions through fields such as
-`managed`, `kind`, `owner`, `source`, and `notes`.
-
-FR6: The implementation shall validate `.project.json`, `role.yaml`,
-`agents-registry.yaml`, `profile.yaml`, and `fleet-contract.yaml` with explicit
-schemas.
-
-FR7: `pjangler` publishing shall fail when vendored template submodules are
-dirty, mismatched, or missing required files.
-
-FR8: The heartbeat v2 strategy shall use n8n as the visual orchestration plane
-and systemd as the local survival fallback.
-
-FR9: n8n workflows shall read Fleet state from `pjangler`/Fleet registry rather
-than storing independent Fleet truth.
-
-FR10: n8n workflow generation shall be reproducible from `pjangler` and must be
-validatable before creation or update.
-
-FR11: The implementation shall repair known current drift, including stale
-runtime scaffold fallback paths, heartbeat/checkpoint mismatch, stale registry
-Hermes paths, and invalid generated role model fields.
-
-FR12: The operator shall be able to inspect and run all checks locally without
-network side effects unless an apply or create flag is explicitly provided.
-
-## Non-Functional Requirements
-
-NFR1: Default commands must be read-only or dry-run.
-
-NFR2: Reconciliation must never destroy or merge runtime state automatically
-when profiles or runtime repos contain ambiguous data.
-
-NFR3: n8n outage must not prevent baseline agent health, gateway operation,
-consumer operation, or runtime checkpoint fallback.
-
-NFR4: Validation output must be deterministic and grep-friendly.
-
-NFR5: Release gates must be suitable for local CLI use and npm `prepublishOnly`.
-
-NFR6: Secrets must remain outside committed artifacts and generated workflow
-definitions.
-
-NFR7: The architecture must support fast solo iteration without requiring a
-large platform migration before useful checks land.
-
-NFR8: Generated n8n workflow code must follow n8n workflow SDK design guidance:
-normalize data early, avoid accidental per-item fanout, and validate workflow
-code before creation.
-
-## Scope
-
-In scope:
-
-- Fleet contract design.
-- `pjangler` status, reconcile, validation, and release gates.
-- n8n workflow generation artifacts and first supervisor workflow path.
-- Systemd fallback heartbeat/checkpoint strategy.
-- Current drift repair stories.
-
-Out of scope for the first implementation:
-
-- Rewriting Hermes internals beyond the minimal profile/config validation needed.
-- Migrating every agent to custom n8n nodes.
-- Removing systemd.
-- Making n8n the Fleet source of truth.
-
-## Success Criteria
-
-- `pj templates status` clearly explains which template bytes will be used.
-- `pj fleet status` reports registry/profile/systemd/schema drift without
-  destructive changes.
-- `pj fleet reconcile --apply` fixes safe drift and labels unsafe drift manual.
-- `npm run prepublishOnly` fails if vendored templates are dirty.
-- A generated n8n Fleet supervisor workflow can be validated before creation.
-- Agents continue local fallback behavior when n8n is unavailable.
-