Harmonist v1.2.3

Patch release: the final native-Windows determinism fix. With v1.2.1 (stdout
glyphs) and v1.2.2 (catalog file reads), this makes the native-Windows CI job
pass end to end for the first time — both the Linux and Windows jobs are green.

Fixed

• Deterministic index.json across operating systems. build_index.py
  wrote each agent's path field with str(Path(...)), producing backslashes
  on Windows, so build_index.py --check flagged the committed (forward-slash)
  index as stale on the Windows runner. It now uses .as_posix(), matching
  build_manifest.py. No change to index.json on POSIX.

Harmonist v1.2.0

Maintenance release: install-UX overhaul plus reliability hardening across
hooks, memory, and the catalog. Headline fix — dropping the pack into a
workspace no longer risks Cursor treating the orchestrator template as a
live rule and demanding enforcement machinery that isn't installed yet.

Install UX

• AGENTS.md (pack root) renamed to AGENTS.template.md with an
  unmissable preamble: it is a TEMPLATE, not an active rule for the pack
  folder; AI agents asked to "install" must follow integration-prompt.md
  instead. The file generated in the USER's project keeps the name
  AGENTS.md. All pack-owned marker blocks preserved verbatim.
• <PACK_DIR> convention. The pack folder may have any name; docs and
  the integration prompt now detect the actual folder name and use
  <PACK_DIR>/ placeholders (examples assume harmonist/). Literal
  harmonist/ paths inside pack-owned blocks are substituted by the merge
  tooling at integration/upgrade time.
• AI entry points. README.md opens with a self-routing block for AI
  agents; integration-prompt.md opens with "you are the installer —
  execute the steps below".
• Integration prompt corrections: strict-install wording fixed (6
  strict agents copied incl. wcag-a11y-gate, plus bg-regression-runner
  seeded in Step 7 → 7 strict files post-install); removed the redundant
  hand-edit instruction for bg-regression-runner commands (raced the
  auto-seeding); .cursor/memory/ file list now includes migrations.py;
  added a warning to delete the pack's CI configs when the pack was copied
  into a project root; added the pentest controlled domain.
• GUIDE_EN.md manual path fixed — the old 4-step manual install
  produced an unenforced setup (no hooks, rules, or .gitignore
  hardening); it now routes through integrate.py + verify_integration.py.

Hooks reliability

• State-file locking around read-modify-write cycles, stop-gate
  handoff fallback hardening, and further HITL dangerous-command
  pattern hardening across both hook runtimes.

Memory robustness

• Pinned UTF-8 on all reads/writes, cross-platform locking, and
  collision-safe rotation ids.

Catalog

• wcag-a11y-gate is now installed by upgrade.py as a pack-owned
  strict reviewer (post-install strict files: repo-scout + 5 reviewers +
  seeded bg-regression-runner = 7).
• Strict-slug unification, the orchestrator entry marked strict, and a new
  controlled domain pentest for the authorized offensive-security
  personas.

Docs & playbooks

• NEXUS tree marked as legacy: standardized banners on QUICKSTART.md,
  nexus-strategy.md, all 7 phase playbooks, all 4 scenario runbooks, and
  both coordination docs — display names are not slugs; dispatch follows
  AGENT: <slug> markers and the project AGENTS.md + agents/index.json.
• Phantom agents replaced with real catalog slugs: Senior Developer →
  engineering-laravel-livewire-specialist, Senior Project Manager →
  project-management-laravel-pm, Finance Tracker → finance-fpa-analyst,
  Data Consolidation Agent → sales-pipeline-analyst.
• playbooks/EXECUTIVE-BRIEF.md: file tree re-rooted at playbooks/
  (was strategy/), "9 Divisions" branding corrected to the actual 16
  categories, invented-looking statistics toned down to qualitative claims.
• MANIFEST.sha256 coverage claim corrected: all runtime-shipped content
  (agents/, hooks/, memory/, playbooks/, root docs) is hashed; CI
  configs and repo metadata are pack-repo-only and excluded. CI configs
  now carry explicit "pack-repo CI — delete in host projects" headers.
• onboard.py (teammate walkthrough) documented in the README key-scripts
  table.

Harmonist v1.1.0

Harmonist v1.1.0 — native Windows, 193 agents, hardened fail-closed enforcement.

Highlights

Cross-platform / native Windows

• Pure-Python hook runtime (hook_runner.py) is the active path on macOS, Linux, WSL and native Windows (no bash required); upgrade.py renders hooks.json with a Python launcher that exists on the host. convert.py / install.py port the shell tooling; CI gains a native-Windows job.

Catalogue (186 → 193 agents)

• Model pinned to claude-opus-4-8 across the pool.
• +6 authorized-security agents (recon, web-app pentest, vuln triage, exploit dev, red-team, pentest reporting) + privacy-engineer — on-demand, scope-guarded.
• Reusable skills library + schema-validated security/privacy hardening checklist.

Enforcement

• Mechanical concurrent-subagent cap + delegation-context gate.
• New beforeShellExecution HITL gate on destructive commands (POSIX + Python parity).
• Git pre-commit guard extends review enforcement to terminal commits.
• Zero-dependency repo map (ast + sqlite) powers repo-scout and an opt-in impact-aware affected-tests gate.

Reliability & security audit (fail-closed)

• stop gate never ends a turn silently (phases wrapped, validator timeout-bounded).
• session.json read-modify-write is locked cross-platform (no lost writes / cap bypass).
• Webhook: http(s)-only scheme allowlist (no file:// SSRF), no redirects, retry/backoff.
• Memory secret scanner: scans every match, the AWS .env form, and all free-text fields.
• verify_integration now actually implements pack-manifest.json drift detection.
• Hardened dangerous-command patterns; run_regression kills the whole process tree on timeout and no longer lets a partial run satisfy the gate.

Coherence & docs

• Six hook phases, accurate counts, a11y review gate wired in, install lists aligned with reality.

All green: check_pack_health 18/18, 550+ test assertions, cross-platform E2E. Full details in CHANGELOG.md.

Install: git clone https://github.com/GammaLabTechnologies/harmonist.git then paste integration-prompt.md into Cursor Agent mode.

Harmonist v1.0.0

Initial public release. Harmonist ships 186 curated agents, a
Schema-v2 frontmatter contract, structured validated memory, and a
hook-driven enforcement layer that cannot be skipped by the LLM.

Catalogue

• 186 agents across 16 categories. Unified pool under
  agents/<category>/<slug>.md, every file conforming to Schema v2.
  Strict agents (orchestration, review) drive the mandatory
  gates; persona agents are free-form specialists with domain depth.
• Data-driven routing. agents/index.json is the single routing
  table the orchestrator consults. Adding or renaming an agent
  requires zero edits to AGENTS.md.
• Disambiguation metadata. Every agent with near-peers carries
  distinguishes_from + a one-line disambiguation note so the
  orchestrator can tie-break between look-alike specialists.
• Domain filter + role filter. The integration prompt asks for
  both the project's domains (blockchain / gamedev / china-market /
  healthcare / etc.) and its working roles (engineering, design,
  product, marketing, sales, support, finance, testing, academic) to
  select a sensible starter set of specialists, not a
  one-size-fits-all dump.

Enforcement

• Cursor hooks drive the stop gate. The stop hook parses
  AGENT: <slug> markers from subagent prompts and refuses to allow
  turn completion if qa-verifier has not run, if any required
  reviewer is missing, or if session-handoff.md was not updated.
  loop_limit: 3 caps retries; on exhaustion, an incident is recorded
  in .cursor/hooks/.state/incidents.json and surfaced in the next
  sessionStart as a PROTOCOL-EXHAUSTED banner.
• Cross-platform runner. hooks/scripts/hook_runner.py is a
  pure-Python implementation of every hook phase, so native Windows
  works out of the box; WSL / macOS / Linux can stay on the POSIX
  .sh variants via hooks/hooks.posix.json.
• Capability scoping. Agents marked readonly: true are blocked
  from writing files; violations are logged.
• PROTOCOL-SKIP abuse guard. The escape hatch for trivial turns
  is tracked in telemetry; excessive use triggers a warning injected
  into the session bootstrap context.

Memory

• Schema v1 memory contract. .cursor/memory/*.md entries are
  YAML blocks delimited by <!-- memory-entry:start --> /
  <!-- memory-entry:end --> with 7 required frontmatter fields.
  validate.py enforces every rule and is wired into the stop hook.
• Hook-generated correlation IDs. correlation_id has the form
  <session_id>-<task_seq>, generated at session start
  (<unix-seconds><pid4> — collision-safe across parallel sessions)
  and advanced by the stop gate. The LLM cannot invent IDs.
• CLI as the only write path. memory.py append validates before
  writing, scans for ~30 classes of secrets (AWS / GitHub / Stripe /
  GCP / Azure / Slack / Telegram / Discord / SendGrid / DigitalOcean /
  npm / PyPI / DB DSNs / generic high-entropy tokens / vendor-scoped
  UUIDs for Heroku, Postmark, etc.), and rejects placeholder-fenced
  content correctly so ${STRIPE_KEY} still writes cleanly.
• Search + rotate + dedupe. memory.py search filters by tag /
  kind / correlation / summary; rotate archives older entries;
  dedupe refuses identical-summary appends unless --allow-duplicate.

Supply-chain integrity

• MANIFEST.sha256 covers every shipped file.
  check_pack_health.py runs build_manifest.py --verify on every
  preflight; a tampered source is flagged.
• Upgrade guard. upgrade.py --apply sha-verifies every pack
  source BEFORE copying into .cursor/. A tampered
  security-reviewer.md is REFUSED.
• Install-extras guard. install_extras.py inherits the same
  sha-verification for on-demand specialist installs.
• Post-install anchor. .cursor/pack-manifest.json records the
  sha of every installed pack-owned file so verify_integration.py
  can detect someone weakening enforcement after install.
• Snapshot + rollback. upgrade.py --apply takes a pre-apply
  tarball snapshot under .cursor/.integration-snapshots/;
  upgrade.py --rollback restores from the most recent snapshot.

Prompt-injection scanner

• scan_agent_safety.py runs a heuristic regex pass over every agent
  markdown for four classes of hostile content:
  override (jailbreak markers, "ignore previous instructions"),
  exfil (secret leak attempts, .env access),
  remote exec (pastebin / ngrok / webhook.site callbacks,
  curl | bash, base64-decode-exec),
  policy subversion ("skip qa-verifier", "always approve
  silently"). Runs in CI; exit 1 on any error-severity hit.
  False-positive guards for legitimate MITRE ATT&CK threat docs.

Integrations

• 11 IDE targets via converters under agents/integrations/:
  Cursor, Claude Code, GitHub Copilot, Windsurf, OpenCode, Aider,
  Kimi, Qwen, Gemini CLI, Antigravity, OpenClaw.
• Thin-variant mode. convert.sh --thin ships the essentials-only
  body of each persona agent (everything up to ## Deep Reference);
  typical saving ~38% across the pool.

Style + schema

• Schema v2 — agents/SCHEMA.md. Required frontmatter plus
  optional metadata (version, updated_at, deprecated,
  distinguishes_from, disambiguation, domains, color,
  emoji, vibe). Slug (filename stem) is the identity key used
  for routing; name is a human-readable display label.
• Style guide — agents/STYLE.md. Defines the two canonical
  shapes (strict vs persona), anti-patterns to avoid (personality
  theatre, adjective soup, emoji-prefixed headings, aspirational
  sections, cross-agent hand-off lists), a lightweight persona
  template, and a retrofit checklist.
• Deep Reference convention. Every persona agent with ≥ 80
  non-blank body lines carries a ## Deep Reference marker. Thin
  variants cut at the marker; insert_deep_ref_marker.py adds the
  marker to any long persona automatically.

Tooling

• check_pack_health.py — 18 preflight checks (VERSION parses as
  SemVer, every directory + script present + executable, index /
  manifest fresh, lint clean, migrator idempotent, agent catalogue
  free of deprecated tech and prompt-injection patterns,
  README / AGENTS.md category counts match index.json).
• lint_agents.py — Schema v2 validator for every agent.
• build_index.py — deterministic routing-table generation.
• build_manifest.py — sha256 covering every shipped file
  (262 tracked files at 1.0.0).
• integrate.py / upgrade.py / deintegrate.py — full integration
  lifecycle.
• verify_integration.py — objective post-install audit.
• install_extras.py — on-demand specialist installation by slug /
  role / tag with sha-verification and thin-variant support.
• scan_agent_safety.py, scan_agent_freshness.py,
  scan_rules_conflicts.py, scan_memory_leaks.py — four
  complementary scanners for catalogue health and integration hygiene.
• merge_agents_md.py — replaces <!-- pack-owned --> blocks in a
  project's AGENTS.md with the newest pack version, preserving
  project-owned prose between marker pairs.
• insert_deep_ref_marker.py — automated cut-point insertion for
  long persona agents.
• detect_regression_commands.py — infers project test / lint / build
  commands from manifests for bg-regression-runner.
• onboard.py — walkthrough for teammates joining an
  already-integrated project.
• refresh_py_guard.py — keeps the 3.9+ version guard in sync across
  every entry script.

Testing

• ~430 test assertions across hook tests (30 scenarios), memory
  tests (29 scenarios), and 20 shell-based suites under
  agents/scripts/test_*.sh. All passing on first clean integration.
• GitHub Actions CI runs the full regression on every pull request
  and push to main.

Documentation

• Root-level README.md, AGENTS.md, GUIDE_EN.md,
  integration-prompt.md, CHANGELOG.md, LICENSE,
  CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md.
• Agent-level agents/SCHEMA.md, agents/STYLE.md, agents/TAGS.md.
• Memory-level memory/SCHEMA.md, memory/README.md.
• Optional playbooks/ — the NEXUS 7-phase lifecycle with phase
  runbooks, coordination docs, and scenario playbooks for
  startup-MVP, enterprise-feature, incident-response, and
  marketing-campaign workflows.