hermes-voip 0.1.1__tar.gz

hermes_voip-0.1.1/.claude/hooks/enforce-worktree.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook: blocks Edit/Write/NotebookEdit calls that target the root
+ * checkout. AGENTS.md rule 8: all work happens in worktree lanes under
+ * .worktrees/; the root checkout is a pristine mirror of main.
+ *
+ * Allowed: paths under <root>/.worktrees/** and paths outside the repository
+ * entirely (e.g. ~/.claude memory, /tmp scratch). Blocked: everything else
+ * inside the root checkout's working tree.
+ *
+ * Exit codes per the hooks contract: 0 = allow, 2 = block (stderr is fed back
+ * to the model). Any unexpected failure allows the call — this hook is defence
+ * in depth, not the rule itself.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+let input;
+try {
+  input = JSON.parse(readFileSync(0, "utf8"));
+} catch {
+  process.exit(0);
+}
+
+const toolInput = input.tool_input ?? {};
+const target = toolInput.file_path ?? toolInput.notebook_path;
+if (typeof target !== "string" || target === "") {
+  process.exit(0);
+}
+
+const cwd =
+  typeof input.cwd === "string" && input.cwd !== "" ? input.cwd : process.cwd();
+
+let mainRoot;
+try {
+  // The common git dir is <main-root>/.git for every linked worktree.
+  const commonDir = execFileSync(
+    "git",
+    ["rev-parse", "--path-format=absolute", "--git-common-dir"],
+    { cwd, encoding: "utf8" },
+  ).trim();
+  mainRoot = path.dirname(commonDir);
+} catch {
+  process.exit(0); // not inside a git repository — nothing to enforce
+}
+
+const resolved = path.resolve(cwd, target);
+const rel = path.relative(mainRoot, resolved);
+const insideRoot =
+  rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+const insideLane =
+  rel.startsWith(`.worktrees${path.sep}`) ||
+  rel.startsWith(`.claude${path.sep}worktrees${path.sep}`);
+
+if (insideRoot && !insideLane) {
+  console.error(
+    `Blocked: ${resolved} is in the root checkout. AGENTS.md rule 8: never edit the ` +
+      `root checkout — create a worktree lane (worktree-lane skill) and edit ` +
+      `${mainRoot}/.worktrees/<lane>/... instead.`,
+  );
+  process.exit(2);
+}
+
+process.exit(0);

hermes_voip-0.1.1/.claude/settings.json

@@ -0,0 +1,42 @@
+{
+  "enableAllProjectMcpServers": true,
+  "permissions": {
+    "deny": [
+      "Read(/.env)",
+      "Read(/.env.*)",
+      "Read(/.memory/**)",
+      "Read(/**/.venv/**)",
+      "Read(/**/__pycache__/**)",
+      "Read(/**/.mypy_cache/**)",
+      "Read(/**/.ruff_cache/**)",
+      "Read(/**/.pytest_cache/**)",
+      "Read(/**/*.egg-info/**)",
+      "Read(/**/htmlcov/**)",
+      "Read(/**/dist/**)",
+      "Read(/**/build/**)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Persistent project memory is active: recall prior decisions with qdrant-find before non-trivial work; store new decisions, corrections and gotchas with qdrant-store (conventions: the memory skill). Reminder: repo is PUBLIC — keep the gateway host/extension/password/device-model out of every tracked file.'"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

hermes_voip-0.1.1/.claude/skills/adr/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: adr
+description: Record an architecture decision as an ADR in docs/adr/. Use whenever a non-trivial design or tooling decision is made (technology choice, data model, protocol, security posture) — before or alongside the implementing commit.
+---
+
+# Writing an ADR
+
+Implements AGENTS.md rule 30: non-trivial decisions are recorded, not implied by code.
+
+## Procedure
+
+1. Find the next number: `ls docs/adr/` — files are `NNNN-kebab-title.md`, zero-padded to
+   four digits. `0000-template.md` is reserved for the template.
+2. Copy `docs/adr/0000-template.md` to `docs/adr/NNNN-<kebab-title>.md`.
+3. Fill every section. "Alternatives considered" must name real alternatives and the
+   specific reason each was rejected — "didn't fit" is not a reason.
+4. Status starts at `Accepted` (we record decisions when made, not proposals). If a later
+   ADR reverses it, edit the old one's status to `Superseded by ADR-NNNN` in the same commit
+   that adds the new one.
+5. Commit the ADR with the work it justifies, or as its own `docs(adr):` commit if the
+   decision precedes implementation.
+
+## Quality bar
+
+- Present tense, factual, self-contained — a reader gets the full picture without the chat
+  transcript that produced it.
+- Numbers and names, not vibes: versions, benchmarks, prices, URLs.
+- An ADR that describes behaviour the repo doesn't have yet is aspirational documentation
+  (rule 27) — write it when the decision is real.

hermes_voip-0.1.1/.claude/skills/memory/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: memory
+description: Store and recall persistent project memory via the local qdrant memory MCP (qdrant-store / qdrant-find). Recall at the start of non-trivial tasks; store non-obvious decisions, operator feedback, and hard-won lessons when you learn them.
+---
+
+# Project memory conventions
+
+The `memory` MCP server (mcp-server-qdrant, configured in `.mcp.json`) provides two tools
+backed by a local vector store under `.memory/`:
+
+- `qdrant-find` — semantic search; phrase the query as a natural-language question.
+- `qdrant-store` — persist one memory (`information` + optional `metadata` JSON).
+
+## Recall
+
+At the start of any non-trivial task, run one or two `qdrant-find` queries about the area
+you're touching (e.g. "decisions about the SIP transport", "gotchas registering against the
+SIP gateway"). Do this before re-deriving anything a past session may have settled.
+
+## Store
+
+Store when you (a) make a non-trivial decision not worth a full ADR, (b) receive operator
+feedback or a correction, (c) discover a gotcha that cost real time, or (d) finish a
+milestone whose state a future session needs.
+
+Entry format:
+
+- `information`: 1–3 self-contained sentences, present tense, absolute dates (never
+  "today"/"recently"). A future session sees only this text — include the why.
+- `metadata`: `{"type": "project|feedback|user|reference", "topic": "<kebab-case>"}`.
+
+## Do NOT store
+
+- Secrets, tokens, keys — ever. The gateway host, extension number, device model and SIP
+  password are sensitive; they live in the gitignored `.env` and the per-user agent memory,
+  never in this store.
+- Anything already canonical in the repo (AGENTS.md rules, docs/ figures, ADRs, code). Repo
+  files are the source of truth; memory is for what the repo doesn't record.
+- Conversation-local trivia with no future value.
+
+## Operational notes
+
+- Local after first run: embedded Qdrant DB + ONNX embedding model under `.memory/`
+  (gitignored). The embedding model downloads from the HuggingFace Hub on first use only,
+  then runs fully offline — no further network calls; nothing leaves the machine.
+- Single-process lock: only one session per repo clone can use the store at a time. A
+  second concurrent session's memory server fails to connect — that is the lock, not a
+  corruption.
+- If a memory turns out to be wrong, store a correcting entry stating both the old claim and
+  the correction (the store has no delete tool).

hermes_voip-0.1.1/.claude/skills/orchestrate/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: orchestrate
+description: Autonomous single-orchestrator build loop. ONE Claude session (the orchestrator) fans out agent teams via ultracode Workflows to drive the whole repo toward done — identifying next work, then shipping correctness/robustness/tests/docs/API/auth/observability/UX, gap-reviewing, backlogging the gaps, and shipping those too. Selects the right model per job. Runs for days. Trigger: `/loop /orchestrate`. The ONLY exit is a genuinely dry repo (no work, no UX to improve) — never a "natural break point".
+disable-model-invocation: true
+---
+
+# /orchestrate — the autonomous build loop
+
+You are the **orchestrator**: a single Claude session that drives this repository toward
+*done* by fanning out agent teams, not by doing the work yourself. One `/orchestrate`
+invocation runs **one wave**. `/loop /orchestrate` runs waves back-to-back, forever, until
+the repo is genuinely dry. You hold the agenda; subagents hold the work.
+
+Read the WHY in `docs/adr/0072-autonomous-orchestration-loop.md` and the operational HOW in
+`docs/runbooks/0016-orchestration-loop.md`. This skill is the executable contract.
+
+---
+
+## PRIME DIRECTIVE — never stop
+
+The operator's one hard requirement: **do not stop at natural break points, when a queue
+looks empty, or when you "feel done".** Those feelings are *signals to discover more work*,
+never reasons to halt. Every wave ends by guaranteeing the next wave. Stopping is a defect.
+
+Banned end-states (treat each as a trigger, not a terminus):
+- "The backlog is empty / there's nothing left" → run a **REPLENISH** gap-review (Phase 1).
+- "Awaiting review / CI / operator approval" → you OWN PRs to merge (AGENTS rule 14). Reap
+  them next wave. Never wait on a human.
+- "This is a natural place to pause / hand off / wrap up" → forbidden. End with the next
+  wave's plan + a scheduled wake.
+- "I think we're done" → that is a hypothesis to *disprove* with a full gap-review, not a
+  conclusion. Decisions gate on **observable evidence** (queue counts, gate exit codes,
+  dry-streak), never a vibe.
+
+**Continuation guarantee (do this every wave, last):** The loop runs in one of two modes:
+
+- **Dynamic mode** (`/loop` with no interval): your final action is
+  `ScheduleWakeup(prompt="/loop /orchestrate", delaySeconds=…, reason=…)`. Mandatory even
+  when a wave shipped nothing.
+- **Cron mode** (`/loop /orchestrate` with an interval, e.g. `*/10 * * * *`): the `/loop`
+  skill fires `/orchestrate` on its fixed schedule — that cron IS the continuation. If
+  `ScheduleWakeup` responds with "the /loop dynamic runtime gate is off … the loop has
+  ended; do not re-issue", you are in cron mode. This is NORMAL, not an error. Do NOT
+  delete the cron (doing so breaks the loop), and do NOT re-issue `ScheduleWakeup` after it
+  refuses. A cron-fired `/orchestrate` lands in the same session with preserved context, so
+  a mid-wave tick is recognised as already in-flight and handled — never treated as an
+  overlapping wave.
+
+Either way, the next wave is guaranteed. See **Exit condition** for the only escape, which
+is itself a long idle-poll, not a halt.
+
+---
+
+## Mental model
+
+```
+/loop /orchestrate
+   └─ wave N (this invocation, the orchestrator = you)
+        Phase 0 SENSE   ─ refresh, reap open PRs, sweep, recall memory
+        Phase 1 REPLENISH ─ fan out gap-reviewers → append new backlog items
+        Phase 2 SELECT  ─ batch independent ready items, assign a model each
+        Phase 3 IMPLEMENT ┐ Workflow: pipeline(items, impl, review)
+        Phase 4 REVIEW    ┘  cross-vendor (codex) + cross-tier Claude
+        Phase 5 PR+MERGE ─ open PR, watch CI, squash-merge on green+clean
+        Phase 6 CLEAN   ─ check off backlog, prune lane, refresh root, store memory
+        Phase 7 CONTINUE ─ ScheduleWakeup("/loop /orchestrate")  ← never skip
+```
+
+You **delegate execution**; you **personally own** sensing, selection, PR/merge decisions,
+memory, and the continuation guarantee. Keep your own context lean (AGENTS rule 29): never
+read whole modules yourself — fan reading/implementation into subagents and keep only their
+summaries. State lives on disk, not in this conversation, so a context summary or restart
+loses nothing.
+
+---
+
+## Durable state (resume across days / restarts)
+
+You keep **no long-term state in context**. Every wave reconstructs from disk:
+
+| Source | Role |
+|---|---|
+| `docs/backlog.md` | **Canonical prioritized queue.** Checkbox items, `[high]/[medium]/[low]` + kind tags. Shipped → checked off with the PR #. New gaps → appended. |
+| `gh pr list` / `gh issue list` | In-flight state + secondary queue. |
+| `.orchestrator/state.json` (gitignored) | **Best-effort / optional.** Attempt the write; if the worktree hook blocks it (the `enforce-worktree` PreToolUse hook blocks ALL root-checkout writes, including gitignored paths — this is the current behaviour), run stateless and rebuild from `backlog.md` + `gh`; treat a blocked write as expected, not a failure. See schema below. |
+| memory MCP (qdrant) | Decisions, gotchas, operator feedback. **Orchestrator-only** (single-process lock — subagents must NEVER call qdrant). Degrade gracefully if locked/unavailable. |
+
+`.orchestrator/state.json` schema (all optional; rebuildable):
+`{ "wave": int, "inflight": [{"item": str, "branch": str, "pr": int|null, "retries": int}],
+   "dryStreak": int, "lastGapReviewWave": int, "notes": str }`
+
+---
+
+## One wave — the eight phases
+
+### Phase 0 — SENSE & RESUME
+1. Refresh root: `git -C <root> fetch origin && git -C <root> pull --ff-only origin main`.
+2. **Reap in-flight PRs** (`gh pr list --state open`). For each PR the loop owns:
+   - CI green (`gh pr checks <n>`) **and** review clean → **squash-merge** (Phase 5 rules),
+     then Phase 6 cleanup.
+   - CI red → spawn a fix lane (TDD fix → push); leave PR open.
+   - Not yet reviewed → run Phase 4 review now.
+   - Conflicts → rebase the lane on current HEAD, re-verify, force-push *the lane branch
+     only* (never a shared branch).
+3. Sweep orphaned worktrees/scratch idle > a few hours: `git worktree prune`, then remove
+   stale `.worktrees/*` whose branch is merged and ephemeral `.claude/worktrees/{agent,wf_}*`.
+4. `qdrant-find` the dimensions you'll touch this wave (recall prior decisions/gotchas).
+5. Load `.orchestrator/state.json` if present.
+
+### Phase 1 — REPLENISH (gap-review fan-out — the anti-stop engine)
+Compute `ready = ` unchecked, unblocked backlog items + open issues.
+Run a gap-review **if** `ready < 2 × fleetWidth` **OR** `wave − lastGapReviewWave ≥ 3`
+**OR** the queue is empty (always). Then:
+1. `Workflow({scriptPath: ".claude/skills/orchestrate/wave.workflow.js",
+   args: {phase: "gap-review", dimensions: [...], budget: <tokens>}})` — one agent per
+   **dimension** (see list below), each returning structured candidate items.
+2. **Dedup** the returned items against `backlog.md` + open issues (cheap: a haiku agent or
+   a direct title/file match). Discard anything already tracked.
+3. Genuinely-new items → append to `docs/backlog.md` (and/or `gh issue create` for
+   feature-sized work) **via a docs lane → PR → merge**. New work is now durable.
+4. If the panel returned **zero** genuinely-new items across **all** dimensions, increment
+   `dryStreak`; else reset it to 0.
+
+A near-empty queue is normal and expected — it just means it's time to discover. The panel
+almost always finds something; that is the design.
+
+### Phase 2 — SELECT & PLAN
+1. Batch up to `fleetWidth = min(16, cores − 2)` **ready** items.
+2. Order: `[high] > [medium] > [low]`; correctness/security before polish; **unblockers
+   first** (e.g. a missing test runner that gates other work); respect stated dependencies.
+3. **Independence (AGENTS rule 32):** one non-overlapping file territory per lane. Serialize
+   hot shared files (`src/hermes_voip/adapter.py`, `media/call_loop.py`, `docs/backlog.md`)
+   to **≤1 lane per wave**. Group tiny same-module items into one lane to cut PR overhead.
+4. Assign each item a **model tier** (rubric below) and an effort level.
+
+### Phase 3 + 4 — IMPLEMENT & REVIEW (one Workflow, pipelined)
+`Workflow({scriptPath: ".claude/skills/orchestrate/wave.workflow.js",
+  args: {phase: "implement", items: [<selected, each with model+spec>], budget: <tokens>}})`
+
+The script runs `pipeline(items, implStage, reviewStage)` so each item's review starts the
+moment its implementation goes green — no barrier. Per item:
+- **implStage** (assigned model, `isolation: "worktree"`): TDD — write the failing test, run
+  it, capture the red output, **commit the red test separately**, implement to green
+  **without touching the test**, write an ADR/runbook if the change warrants one (rules
+  30/42), run the **full local gate**, push a conventional branch. Returns
+  `{item, branch, redCommit, greenCommits, gate, adr?, runbook?, files, spec, selfRisk}`
+  or `{item, failed, reason}`.
+- **reviewStage** (cross-vendor + cross-tier, fresh context, **diff+spec+checklist only** —
+  rule 21): `codex` (OpenAI) **and** a different-tier Claude reviewer. Returns
+  `{verdict, mustFix[], noted[]}`. Must-fix → loop a fix agent → re-review (bounded retries).
+  Materiality (rule 16): must-fix = correctness/security/spec/guardrail/blast-radius only.
+  **Unanimous rubber-stamp is a yellow flag** → escalate to an opus deep-review before trust.
+
+The Workflow returns `[{item, branch, verdict, evidence}]`. `.filter(Boolean)` the failures.
+
+### Phase 5 — GATE → PR → MERGE  (you, the orchestrator)
+For each item with a **clean** verdict:
+1. **Integrator re-verify on current HEAD** (rule 11): the lane was cut from an older HEAD;
+   confirm it still rebases cleanly and the gate is green from a clean build. If drifted,
+   have an agent rebase + re-gate before trusting the green.
+2. `gh pr create` — title = Conventional Commit; body = spec, ADR/runbook links, gate
+   evidence (command+exit codes), review summary + the substantive risk statement,
+   blast-radius, `Co-Authored-By` trailer.
+3. Watch CI (`gh pr checks <n> --watch` or poll). CI is the authoritative gate (rule 15).
+   Fix any CI-only failures in the lane.
+4. **Squash-merge on green CI + clean review** (operator-approved auto-merge). Conventional
+   squash title. Slow CI must **not** block the wave — leave the PR open and let Phase 0 of
+   the next wave reap it. PR shepherding is idempotent across waves.
+
+   > **Branch-protection note.** This repo may have NO required-status-check branch
+   > protection, so `gh pr merge --auto` merges immediately without waiting for CI. For any
+   > CODE change, do NOT use `--auto` blindly: poll `gh pr checks <n>` until the CI jobs
+   > you care about are green, then merge explicitly. Docs/config PRs (no Python surface, no
+   > gate-relevant change) may be merged once the fast `gate` + `scan` jobs pass while
+   > slower extras jobs (`hermes-contract`, etc.) are still running — but verify those slower
+   > jobs do not cover the changed surface before proceeding.
+
+### Phase 6 — INTEGRATE & CLEAN
+1. Check off the shipped backlog item(s) with the PR # (batch into the next docs lane).
+2. `git worktree remove --force <lane>` + `git worktree prune`.
+3. Refresh root: `git fetch origin && git pull --ff-only origin main` (rule 9) so the next
+   lane bases on current HEAD.
+4. `qdrant-store` any non-trivial decision/gotcha/operator-feedback learned (orchestrator
+   only; never secrets — see Invariants).
+5. Reconcile drifted docs (stale `IMPLEMENTATION-PLAN.md` / `backlog.md` preamble / README)
+   in a batched docs lane.
+
+### Phase 7 — CONTINUE  (never skip)
+1. Attempt to update `.orchestrator/state.json` (wave++, in-flight, counters, dryStreak).
+   If the `enforce-worktree` hook blocks the write (it currently does — it blocks all
+   root-checkout writes even to gitignored paths), skip it silently and run stateless; the
+   wave-state is rebuilt next wave from `backlog.md` + `gh` + memory.
+2. Emit a tight wave report: shipped+merged, opened, discovered, cleaned, and the **next
+   wave's plan**. Never end on a "good stopping point".
+3. **Guarantee the next wave:**
+   - If in **dynamic mode**: `ScheduleWakeup(prompt="/loop /orchestrate", delaySeconds=…,
+     reason="next orchestration wave")`. Pick the delay by what you're waiting on
+     (CI in flight → ~270s; otherwise 1200–1800s).
+   - If `ScheduleWakeup` reports the dynamic runtime gate is off (cron mode): the fixed
+     cron IS the continuation — do not delete it, do not re-issue `ScheduleWakeup`; the
+     next wave fires automatically. This is the normal operating mode when the loop was
+     started with an interval (e.g. `/loop /orchestrate` via a `*/10 * * * *` cron).
+   Either path guarantees the next wave.
+
+---
+
+## Gap-review dimensions (Phase 1 — "cover everything")
+
+Fan out **one agent per dimension**. Each hunts NEW work only in its lane and returns
+structured items. Cover, at minimum:
+
+1. **correctness** — bugs, contract violations, RFC compliance, off-by-ones.
+2. **robustness / fail-closed** — error handling (rule 37), edge cases, hostile input.
+3. **security & auth** — injection guard, caller groups/modes, SIP digest, SRTP/DTLS,
+   secret hygiene (public repo!), supply-chain advisories (`uv` audit + licences).
+4. **tests & mutation** — coverage gaps, weak/assertion-free tests, missing async tests,
+   surviving mutants (rule 19).
+5. **docs & doc-drift** — rule 27: comments/docs describing behaviour the code lacks;
+   reconcile stale `IMPLEMENTATION-PLAN.md` / `backlog.md` preamble / `README.md`; runbook
+   numbering collisions.
+6. **API & ergonomics** — `__all__`, public exports, typed surfaces, import discoverability.
+7. **performance / efficiency** — hot-path budgets, allocations, rule 22 (record numbers).
+8. **observability / reporting / monitoring** — instrument the runbook-0014 SLOs, RTCP
+   metrics, structured logs. *Local-only emission is in-bounds*; an external sink/dashboard
+   is **propose-only** (see Invariants).
+9. **UX & conversational quality** — greeting, barge-in feel, silence/goodbye handling,
+   error speech, multi-language, voice accessibility. Investigate and improve relentlessly.
+10. **operability** — runbooks current (rule 42), plugin enablement, graceful shutdown,
+    config validation.
+11. **packaging / release** — plugin manifest, entry points, version hygiene, deps.
+12. **product / feature gaps** — implied/designed features (e.g. agent-screened answering
+    [designed in backlog], issue #64 video→vision, call transfer). Infra-needing surfaces →
+    **Proposed ADR only**.
+
+---
+
+## Model-selection rubric ("always the right agent for the job")
+
+Pick for intelligence **and** speed/efficiency. Pass `model` (and `effort`) to every
+`agent()`.
+
+| Tier | Model id (short) | Use for |
+|---|---|---|
+| **opus** | `opus` (`claude-opus-4-8`) | hard correctness/security, new subsystems, ADR design, crypto/SRTP/digest/injection-guard, the barge-in state machine, ambiguous root-cause, final synthesis, escalated/ tie-break reviews. effort `high`/`xhigh`. |
+| **sonnet** | `sonnet` (`claude-sonnet-4-6`) | standard spec'd feat/fix, most implementation lanes, moderate test work, standard reviews. effort `medium`/`high`. |
+| **haiku** | `haiku` (`claude-haiku-4-5`) | mechanical/bounded — `__all__`/`Final`, docstrings, test vectors, backlog dedup/formatting, lint fixes, search/triage. effort `low`. |
+| **fable** | `fable` (`claude-fable-5`) | fast high-capability peer; **primary Claude cross-tier reviewer** for model diversity (rule 21); medium tasks needing speed. |
+
+Defaults by stage: gap-review judgment → opus/sonnet; doc-drift/coverage discovery →
+sonnet/haiku; implementation → per item; **review → a model different from the author**
+(opus-authored → fable or sonnet; sonnet-authored → opus; always also `codex` cross-vendor).
+A haiku triage agent may pre-score each item's complexity to pick the tier.
+
+---
+
+## Invariants (binding — never weaken; see AGENTS.md)
+
+- **Public repo.** Never let the SIP host/extension/password/device-model or any PII reach a
+  tracked file, commit message, PR body, or CI log. Tests use fakes (`pbx.example.test`,
+  ext `1000`). Tell every subagent this.
+- **Worktree lanes only** (rule 8). All edits in `.worktrees/<lane>`; the root checkout is a
+  pristine mirror — the PreToolUse hook blocks root edits. Lanes branch from **current HEAD**.
+- **TDD, real tests** (rules 18/19/25). Red test first, committed separately; green without
+  touching tests; never weaken/skip a test to pass.
+- **Full local gate before every PR** (rule 15): `uv run ruff format --check .` ·
+  `uv run ruff check .` · `uv run mypy` · `uv run pytest` (+ the `--extra hermes/ml/media/
+  webrtc` jobs when deps or those surfaces change). CI is never the first run.
+- **Absolute typing, no escape hatches** (rules 17/39): no `Any`, no unjustified
+  `# type: ignore`, no laundering `cast`; `mypy --strict` clean.
+- **Adversarial cross-vendor review** (rule 21) before merge; ≥1 substantive risk statement
+  (rule 16).
+- **ADRs for non-trivial decisions** (rule 30); **runbooks written as you work** (rule 42).
+- **No new hosting/platform/SaaS/cost without operator approval recorded in an ADR**
+  (rule 40/41). The loop builds **local-only** surfaces freely; anything needing infra or
+  cost (website, HTTP API, S3 call-events/recordings, external metrics sink) gets a
+  **Proposed** ADR + backlog item and waits — it never silently stands up infra.
+- **Errors propagate** (rule 37). **No partial-ship** (rule 6): every item lands wired
+  end-to-end in one push, or it isn't shipped.
+- **Memory MCP is orchestrator-only** (single-process lock); subagents never call qdrant.
+
+---
+
+## Exit condition (deliberately almost-never)
+
+Only *approach* termination when, for **K = 3 consecutive waves**, **all** hold:
+- the full gap-review panel returns **zero** genuinely-new items across **all** dimensions
+  (`dryStreak ≥ 3`), **and**
+- `gh pr list` shows zero open PRs, **and** zero in-flight lanes, **and**
+- the full gate is green on `main`, **and**
+- a dedicated UX / feature-discovery pass this wave yields nothing.
+
+Even then, **do not stop** — **widen**: deeper UX flow-driving, mutation testing, perf
+budget measurement, feature ideation, competitive comparison. Only if the widened pass is
+*also* dry for K more waves do you enter **steady-state**: report it and idle-poll with a
+long `ScheduleWakeup` (≈3600s) so a newly-arrived issue/PR/operator request restarts real
+work. Steady-state is a long sleep, **not** a halt.
+
+---
+
+## Quick reference
+
+```
+# trigger (operator)
+/loop /orchestrate
+
+# one wave's two Workflow calls (you, each wave)
+Workflow({scriptPath:".claude/skills/orchestrate/wave.workflow.js", args:{phase:"gap-review", dimensions:[...]}})
+Workflow({scriptPath:".claude/skills/orchestrate/wave.workflow.js", args:{phase:"implement", items:[...]}})
+
+# the gate (subagents, in-lane, before every PR)
+uv run ruff format --check . && uv run ruff check . && uv run mypy && uv run pytest
+
+# continuation (you, last action every wave)
+# dynamic mode: issue ScheduleWakeup
+ScheduleWakeup(prompt="/loop /orchestrate", delaySeconds=…, reason="next orchestration wave")
+# cron mode: if ScheduleWakeup says dynamic gate is off, the fixed cron IS the heartbeat — do nothing, do NOT delete the cron
+```