[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F2BF96Z2T1620XBXG792JG":3,"skill-same:01M7F2BF96Z2T1620XBXG792JG":73},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":37,"commitSha":38,"skillDirectory":39,"forksCount":40,"repositoryHtmlUrl":41,"repositoryHomepageUrl":6,"ownerHtmlUrl":42,"ownerBlogUrl":6,"ownerDescription":43,"updatedAt":44,"install":45,"resources":58},"01M7F2BF96Z2T1620XBXG792JG","omh-ralph-driver",null,"Drive an omh-ralph run: dispatch, evidence, commit hygiene.","lza6\u002FArmor-piercing-system-prompts","lza6","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F128880206?v=4","01M7EB3K7WPX5T28EJ2NVHE6EG","Chinese-tingfeng","01M7EB3K97E1KQ16QWKJMFNGX8",11,"MIT","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F05-技能与代理开发\u002Fomh-ralph-driver\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: omh-ralph-driver\ndescription: \"Drive an omh-ralph run: dispatch, evidence, commit hygiene.\"\nversion: 1.0.0\nmetadata:\n  hermes:\n    tags: [execution, ralph, orchestration, multi-agent, parallel, verification]\n    category: omh\n    requires_toolsets: [terminal, omh]\n---\n\n# OMH Ralph Driver — orchestrator's playbook for verified execution\n\nLoad this skill alongside `omh-ralph` when you are the orchestrator\ndispatching the loop. `omh-ralph` is loaded by the role-tagged\n*workers* (executor \u002F verifier \u002F architect) — it covers the iron-law\ndiscipline inside each task's `delegate_task` call. This skill covers\nwhat *you* do as the dispatcher: plan-shape, iteration cadence,\nparallel batching, evidence gathering, verifier dispatch, strike\nhandling, commit hygiene, and the final architect gate.\n\nThe two skills have different readers and different jobs. Don't merge\nthem — worker context is precious; the dispatcher's playbook should\nnot ride into every subagent.\n\nThis skill is the ralph-side counterpart to `omh-ralplan-driver`\n(which is the dispatcher playbook for ralplan, the design loop). The\nrelationship is consistent: each method has a worker-side skill (used\ninside delegate_task) and a driver-side skill (used by the orchestrator\nbetween dispatches).\n\n## When to use ralph vs just write the code\n\nUse ralph when:\n\n- You have a plan with 5+ independently-acceptable tasks (from\n  `omh-ralplan` or hand-authored).\n- Quality-via-verification matters more than wall-clock — each task's\n  output must be evidence-graded before the next builds on it.\n- You want clean checkpoints across many work units (no context bloat).\n- Some tasks are independent and can run in parallel batches.\n\nDon't use ralph when:\n\n- The work is single-step or trivially obvious to write directly.\n- No plan exists yet — run `omh-ralplan` (or for an obvious goal,\n  `omh-deep-interview` first) before invoking ralph.\n- The user wants to skip verification (unusual; usually means the\n  work is small enough to do directly).\n\n## The arc of a ralph run\n\n```\niter 1: pick eligible tasks → dispatch executors (parallel where safe)\n        → gather evidence → dispatch verifiers (parallel) → mark passes\u002Ffails\n        → update state → release lock → exit\n\niter 2: re-invoke. Read state. Pick next batch. Same cycle.\n\n...\n\niter N: all tasks pass → Step 7 final architect review → mark complete.\n```\n\nThe orchestrator's job between iterations: pick the right batch, write\nthe right context for each executor, gather the right evidence, parse\nthe verifier verdicts, and decide whether to retry or move on.\n\n## The five-step playbook\n\n### 1. Read the plan; verify it is ralph-shaped\n\nA ralph plan is a list of numbered tasks, each with:\n\n- A clear title.\n- A description tight enough that an executor with no prior context\n  can implement it.\n- **Acceptance criteria that are testable.** Generic criteria like\n  \"implementation is complete\" are rejected by ralph's planning gate.\n- Dependencies (which other tasks must be done first).\n- Files-touched (for parallel-batch planning — see step 3).\n\nIf the plan came from `omh-ralplan`, it is design-shaped, not ralph-shaped. The stance's \"MV slice\" section is your starting point; you may need to translate it to ralph's task format. Author `.omh\u002Fplans\u002Fralph-plan.md` (or `.omh\u002Fplans\u002Fralplan-\u003Cslug>.md` if it derives from a specific ralplan instance) with proper task structure.\n\nThe plan does not need every task pre-authored to the same depth — it can grow. Ralph's planning gate parses what's there at first invocation; new tasks discovered during execution land via the `discovered: true` flag in state.\n\n### 2. Pick the right batch for each iteration\n\nEach ralph iteration does ONE unit of work. A \"unit\" can be:\n\n- One task (when the next eligible task is alone, or has shared file\n  footprint with other eligibles)\n- A batch of 2-4 tasks (when independents are eligible and have\n  disjoint touch sets)\n\n**Eligibility** = `passes: false` AND all dependencies met.\n\n**Disjoint touch sets** = the tasks do not modify the same files. Read\nthe plan's \"Files to modify\u002Fcreate\" lists. If two eligible tasks both\ntouch `bin\u002Fjanus-new-being`, they are NOT parallel-safe — one owns\nthe modification. If one touches `migrations\u002Flib.py` and another\ntouches `bin\u002F_lineage.py`, they are parallel-safe.\n\n**Edge case — shared imports.** Even if files are disjoint, if Task A\nauthors a helper that Task B imports, you may need Task A to land first.\nSurface this in dependency declarations during plan-authoring; if you\nmiss it, the executor for B will surface the dependency mid-task.\n\n**Right batch size.** 2-4 tasks. Five+ in one batch overloads\norchestrator parsing of executor reports + verifier dispatch in your\nown context window.\n\n### 3. Dispatch executors with rich context\n\nEach executor gets a fresh subagent. Subagents have NO memory of\nprior iterations, prior conversations, prior tasks. Encode everything\nthey need in the dispatch context.\n\nThe executor dispatch context must contain:\n\n- **Project root + branch.** Paths absolute, not relative.\n- **Prior state.** What tasks completed in earlier iterations, what\n  files now exist, what helpers\u002Flibraries are available to import.\n- **Learnings from prior tasks** that are relevant to this one. Pull\n  forward gotchas, naming conventions, architectural choices that\n  the executor needs to honor.\n- **The task itself.** Full title, description, acceptance criteria.\n- **Required reading.** Absolute paths to the canonical design,\n  prior tasks' outputs, similar siblings to pattern-match against.\n- **TDD instruction.** Failing test first, watch it fail, implement,\n  watch it pass, run full suite, commit. Make this explicit in\n  EVERY executor dispatch.\n- **Commit metadata.** Author identity, commit message shape, branch.\n- **DO NOT modify \u003Clist>.** Critically important under parallel\n  batches. See P3 below.\n\nUse the `[omh-role:executor]` marker in the goal — the OMH plugin\nauto-injects the executor role prompt via its `pre_llm_call` hook.\nDon't inline role text manually.\n\nA full template for the executor `goal` field — including TDD\ninstructions, sibling-aware DO-NOT-modify discipline, commit metadata,\nand retry variations for each strike category — is at\n`references\u002Fexecutor-goal-template.md`. Adapt the variables; keep the\nstructure.\n\n### 4. Gather evidence with `omh_gather_evidence` BEFORE dispatching verifiers\n\nAfter all executors complete, run the project's actual test\u002Fbuild\u002Flint\ncommands via `omh_gather_evidence`. This produces a structured\n`{results, all_pass, summary}` object the verifier can grade against.\n\n**Critical:** the verifier does NOT run evidence themselves. Gathering\nhappens at the orchestrator level so you can verify executor claims\nmatch reality before the verifier reads them.\n\n**Allowlist gotcha.** `omh_gather_evidence` enforces a token-prefix\nallowlist (`~\u002F.hermes\u002Fplugins\u002Fomh\u002Fconfig.yaml` →\n`evidence_tool.allowlist_prefixes`). Common project test commands like\n`uv run --with pytest --with pyyaml -m pytest` do NOT match\n`uv run pytest` because `--with` breaks the prefix. Either:\n\n- Use the matching prefix: `uv run pytest \u003Cargs>` (preferred — keep\n  pytest as a project dev dep so `--with pytest` is unnecessary).\n- Add a custom prefix to the OMH config.\n- Wrap with a project-local script.\n\nIf gather_evidence rejects your command, the symptom is `exit_code: -1,\noutput: \"Command not in allowlist\"`. Re-form the command before\ndispatching the verifier.\n\n### 5. Dispatch verifiers in parallel (batched per task)\n\nFor each completed task, dispatch a verifier subagent with:\n\n- `[omh-role:verifier]` marker (auto-injects the verifier role prompt).\n- The task's acceptance criteria (so they grade against the spec, not\n  the executor's interpretation of it).\n- The full evidence output (the verifier MUST see real test results,\n  not paraphrased success claims).\n- File paths to inspect.\n- Specific load-bearing checks that go beyond \"tests pass\" (e.g.,\n  \"verify the mismatched-flag check happens BEFORE any filesystem\n  writes — if not, partial-flag invocations corrupt state\").\n\nVerifiers run in parallel via batched `delegate_task(tasks=[...])` —\nsame wall-clock savings as Round 2 ralplan reviewers.\n\nThe verifier returns one of:\n\n- **APPROVE** \u002F PASS — task's `passes` flag becomes `true`.\n- **REQUEST_CHANGES** \u002F FAIL — record verdict, retry executor with the\n  feedback. Track strikes (see P5 below).\n\nA full template for the verifier `goal` field — including the\nacceptance-criteria-verbatim discipline, evidence-paste shape, sibling\nboundary checks, strike categorization, and worked verdict examples —\nis at `references\u002Fverifier-goal-template.md`.\n\n## Pitfalls (P1–P10)\n\nThese are the failure modes that ralph dispatchers stumble into.\nNumbered for cross-reference; gaps reserved for future additions.\n\n### P1 — Plan must be ralph-shaped, not design-shaped\n\n`omh-ralplan` produces a `stance.md` — a design document. Ralph\nneeds a task list with testable acceptance criteria.\n\nIf you point ralph at a stance directly, the planning gate either\nparses it weakly (extracting whatever numbered sections look\ntask-shaped) or refuses outright. Translate the stance's MV slice\ninto a proper ralph plan first.\n\nThe translation is mechanical:\n\n- Stance MV-slice items → ralph tasks (one item per task).\n- Stance test affordances → task acceptance criteria (verbatim where\n  the stance named them).\n- Stance \"depends on\" prose → task `dependencies:` field.\n- Stance file paths → task `files:` list (for parallel-batch\n  planning).\n\nAuthor the ralph plan as `.omh\u002Fplans\u002Fralph-plan.md` or\n`.omh\u002Fplans\u002Fralplan-\u003Cslug>.md`. Ralph's planning gate finds either.\n\n**Worked translation example (from the 2026-04-27 janus run).** The\nstance's \"MV slice plan\" section listed 13 work items spread across\nNOW (~3.5h, lineage capture before next provision) \u002F NEXT (+72h, the\nupdate tool) \u002F DEFERRED (later releases). The ralph plan landed each\nitem as a task with this shape:\n\n```markdown\n### Task 4 — bin\u002Fjanus-new-being: version stamp + seed-history snapshot\n\n**Files to modify:**\n- `bin\u002Fjanus-new-being`\n\n**Files to create:**\n- `bin\u002Ftests\u002Ftest_janus_new_being_lineage.py`\n\n**Description:**\nPatch `bin\u002Fjanus-new-being` provisioning logic to write lineage data\nper the stance's NOW slice item 2. After successful provisioning,\nwrite `\u003Cprofile>\u002F.janus\u002Fversion`, snapshot rendered template + plugin\ntree to `\u003Cprofile>\u002F.janus\u002Fseed-history\u002Fv1\u002F` via post-write disk-read,\ncompute MANIFEST with content hashes per file...\n\n**Acceptance criteria (verbatim from stance test affordance):**\n\n    def test_provision_writes_v1_lineage(tmp_path):\n        profile = tmp_path \u002F \"alice-janus\"\n        # ... provision invocation ...\n        assert (profile \u002F \".janus\" \u002F \"version\").read_text().strip() == \"v1\"\n        seed = profile \u002F \".janus\" \u002F \"seed-history\" \u002F \"v1\"\n        assert (seed \u002F \"SOUL.md\").exists()\n        ...\n\n**Dependencies:** none (Task 5 extends, but doesn't conflict)\n```\n\nThe translation discipline that made this work:\n\n1. **Verbatim acceptance criteria from the stance.** Where the stance\n   said `test_provision_writes_v1_lineage_and_gh_config` passes, the\n   ralph plan used that exact test name. This makes the executor\n   write the test the stance specified, and the verifier grade\n   against the stance's own contract — no drift through paraphrase.\n\n2. **Files-touched are explicit.** Each task's `files:` lists exactly\n   what gets created and modified. This is what enables parallel-\n   batch planning later (P2): the orchestrator can read the lists\n   and check disjoint touch sets without re-deriving them from the\n   description prose.\n\n3. **Dependencies are inferred from shared concrete artifacts, not\n   just prose.** The stance said the MANIFEST shape was authored in\n   Task 4; Task 8 (lib.py with `hash_equals_ancestor`) needs to read\n   that format. So Task 8's `dependencies: [task-4]` was inferred from\n   the shared file format, not from a \"Task 8 must come after Task 4\"\n   sentence.\n\n4. **NOW\u002FNEXT\u002FDEFERRED gets folded into priority ordering.** All\n   NOW-slice tasks get `priority: 1` or `priority: 2` (with\n   priority-2 reserved for ones that gate later parallel batches).\n   NEXT gets 3-5. DEFERRED items don't appear as ralph tasks at all\n   — they're not part of this run's work envelope.\n\n5. **Test affordance section per task gets expanded to full pytest\n   function signatures.** The stance often listed test names with\n   brief shape; the ralph task gives the executor the exact function\n   names + behavior so they don't have to re-derive them.\n\n**The translation is its own load-bearing step.** Doing it sloppy\nproduces a sloppy run no matter how disciplined the orchestration is\nafterward. The ralph plan IS the contract executors implement and\nverifiers grade against; if it's vague, the loop produces vague work.\n\nBudget 30-60 minutes for the translation on a 10+ task plan. The\noutput is the file ralph's planning gate parses; you'll never look at\nthe stance directly again during the run.\n\n### P2 — Identify parallel-safe batches before dispatching, not during\n\nWalk all eligible tasks (`passes: false` + deps met) at the start of\neach iteration. For each pair, check disjoint-touch-set. Mark the\nparallel-safe set; dispatch them in one batched `delegate_task`.\n\nIf you wait until after dispatching one task to consider whether\nothers could have run in parallel, you've forfeited the wall-clock\nsavings for that iteration. The right-time-to-decide is at the start\nof the iteration, when you're already reading state.\n\nRight batch size is 2-4. Two if dependencies are tight; four if\nmultiple independents stack. Five-plus overloads the orchestrator's\nown context with executor reports + parallel verifier dispatches.\n\n### P3 — \"DO NOT modify \u003Cshared file>\" must be explicit in parallel dispatch contexts\n\nWhen dispatching parallel executors, only ONE task owns each shared\nfile. The other executors must import (read-only) but not modify it.\n\nEncode this explicitly in each executor's dispatch context:\n\n> DO NOT modify migrations\u002Flib.py during this task — Task X owns that\n> change. Import what you need; if a function isn't there yet, fall\n> back to inline implementation that matches Task X's expected\n> signature so they converge cleanly when both commits land.\n\nWithout this instruction, parallel executors race on the shared file\nand produce conflicting commits. With it, they respect the boundary\nand commit only their own work.\n\nThe instruction should also tell each executor to **unstage sibling\ntasks' files before commit**. Otherwise `git add -A` sweeps in\nneighbors' uncommitted work — see P9.\n\n### P4 — Encode forward-learnings in each executor dispatch\n\nEach iteration produces learnings (gotchas, naming conventions,\npatterns that worked, patterns that failed). The next iteration's\nexecutors do NOT see these unless you encode them.\n\nMaintain a per-iteration learnings list in the ralph state's\n`completed_task_learnings` field, and include the relevant subset in\neach subsequent executor's dispatch context.\n\nExamples worth encoding forward:\n\n- \"TEST-INFRA: never use `hash(content) & 0xffff` for tmpdir naming\n  — randomized + small modulus = collision risk.\"\n- \"Use `git rm -r` (not `rm -rf`) to preserve git history when\n  removing tracked files.\"\n- \"bin\u002Fjanus-new-being uses uv shebang, no .py suffix; new bin\u002F*\n  scripts should follow the same pattern.\"\n- \"The classify() function in bin\u002F_lineage.py ships the criterion\n  (path-prefix patterns + Class-B exact set), not enumeration. Reuse\n  it; don't duplicate the taxonomy.\"\n\nThese compress and ride forward via the dispatch context. The\nomh-ralph state's `completed_task_learnings` is the canonical store.\n\n### P5 — Distinguish executor strikes by category\n\nWhen the verifier returns REQUEST_CHANGES, the cause is one of:\n\n1. **Test-infra** — the test itself is buggy (e.g., a `hash() & 0xffff`\n   path collision, a fixture race, a test runner config issue). The\n   implementation may be correct; only the test needs fixing.\n\n2. **Spec-misread** — the executor implemented something different\n   from what the acceptance criteria asked for. Implementation needs\n   correction.\n\n3. **Implementation bug** — the executor implemented the right thing\n   but it has a real defect (logic error, edge case missed, security\n   issue).\n\nThese three categories take different fixes. Test-infra retries\nshould touch only the test file. Spec-misread retries need fresh\ncontext emphasizing what the spec actually requires. Implementation-\nbug retries need the failing case named explicitly.\n\nTag the strike category in the error fingerprint when updating state:\n\n```python\n\"error_fingerprints\": [\n    {\"category\": \"test-infra\", \"error_key\": \"hash-collision-in-tmpdir-naming\", \"round\": 1},\n    ...\n]\n```\n\nThe 3-strike circuit breaker (per `omh-ralph` Step 6) fires when the\nsame `(category, error_key)` repeats three times. Tagging by category\nprevents test-infra strikes from masking real bugs (or vice versa).\n\n### P6 — Verifiers must read real evidence, not executor claims\n\nAlways run `omh_gather_evidence` before dispatching verifiers.\nInclude the evidence output in the verifier's dispatch context.\n\nIf you skip evidence-gathering, the verifier reads only the executor's\nreport (\"Status: COMPLETE; 5 tests pass; commit X\") and has no\nground truth to grade against. Executor reports are sometimes wrong\n— either the executor genuinely missed something, or a test passed\nfor the wrong reason (e.g., a path-collision crashing before the\nload-bearing assertion ran — see this skill's worked example).\n\nThe orchestrator-runs-evidence pattern is what makes ralph\nverification trustworthy.\n\n### P7 — Final architect review (Step 7) is the merge gate\n\nWhen all tasks pass, ralph's Step 7 dispatches an architect to review\nthe full implementation against the original plan\u002Fstance.\n\nThe architect reviews HOLISTICALLY:\n\n- Architectural fidelity (did the implementation honor the design?)\n- Principle alignment (do load-bearing principles fire in mechanics,\n  not just appear in prose?)\n- MV slice readiness (can the user actually run this tonight?)\n- Architectural seams (anything rough vs explicitly deferred?)\n- Commit hygiene (is the git history clean enough to merge?)\n- Test affordance gaps\n\nThis is the orchestrator's final gate before handing the user a\nPR-ready branch. The architect can return:\n\n- **APPROVE** — seal-of-merge.\n- **APPROVE_WITH_PROVISO** — small foldable additions before merge\n  (typically 1-3 named items).\n- **REQUEST_CHANGES** — something cannot ship; new tasks added with\n  `discovered: true`.\n\nAuthor the architect's review as `\u003Corchestrator>-architect-review.md`\nin the design directory (the orchestrator's own iteration-level review\nis `\u003Corchestrator>-review.md`; the architect-review is a separate\nartifact).\n\nA full template for the architect-final-review `goal` field — including\nthe diff-range walk, end-to-end MV-slice trace, principle-firing audit,\ncommit-hygiene check, verdict calibration guidance, and worked review\nexamples (APPROVE_WITH_PROVISO and REQUEST_CHANGES) — is at\n`references\u002Farchitect-final-review-template.md`.\n\n### P8 — Update state at every action; release lock at every exit\n\nPer `omh-ralph` Step 0\u002FStep 8: state files at\n`.omh\u002Fstate\u002Fralph--\u003Cinstance_id>.json` and\n`.omh\u002Fstate\u002Fralph-tasks--\u003Cinstance_id>.json` track the run. Lock at\n`.omh\u002Fstate\u002Fralph--\u003Cinstance_id>.lock` prevents concurrent sessions\nracing on the same plan.\n\nDiscipline:\n\n- Acquire the lock at iteration start (Step 0).\n- Update state after every executor completion, every verifier\n  verdict, every task transition.\n- Release the lock at every exit point — success, blocked, cancel,\n  max-iterations, exception. Wrap the iteration body so unlock fires\n  even on error.\n\nDo NOT leave stale locks. If a lock is held by a dead process, the\nnext ralph invocation will surface it via `held_by` — offer to cancel\n+ retry, don't silently steal.\n\n### P9 — Commit hygiene under parallel writes\n\nThree executors writing to the same branch in one orchestrator turn\nwill see *partial* state from each other (whatever has been committed)\nbut NOT each other's uncommitted work. If one executor uses\n`git add -A` to stage their commit, they may sweep in sibling\nexecutors' files that are still in-flight.\n\nDiscipline for parallel-executor dispatch:\n\n1. **Tell each executor to `git add` their specific files explicitly**,\n   not `git add -A`. Names match the task's `files:` field.\n\n2. **Tell each executor to check `git status` before commit**: if\n   sibling tasks' files are present and unstaged, do NOT include them.\n   Common sibling files: untracked __init__.py stubs, untracked test\n   files, RELEASES.yaml mid-edit.\n\n3. **Accept that absorption sometimes happens anyway.** When it does,\n   the failure is recoverable: an interactive rebase squashes the\n   over-broad commit with the missing one, OR a follow-up history-note\n   commit explains the boundary.\n\n4. **Surface the absorption in iteration logs.** If you notice an\n   executor reported \"swept in pre-existing untracked files,\" flag it\n   for the architect's commit-hygiene check at Step 7.\n\nThis pattern was learned the hard way: in one run, task-11's commit\nabsorbed ~60% of task-12's intended-commit content via `git add -A`.\nTests stayed green; deliverables were correct; commit boundaries were\nfuzzy. Architect flagged it as a foldable proviso.\n\n### P10 — Resume vs restart matters for plugin\u002Ftool changes\n\nIf the user makes plugin or toolset changes between iterations\n(adding a tool, enabling a plugin, modifying config.yaml), tools do\nNOT register live in the current session. They register at agent\n**boot**.\n\nIf the user says \"I changed the config, can you use the new tool now?\":\n\n- The session needs a full restart, not just a Resume button click\n  (some chat UIs reuse the same agent process across \"Resume\").\n- Verify by checking your function schema — if the new tool isn't\n  there, the boot didn't happen.\n- The fastest way to know is `omh_state(action=\"check\", ...)` if\n  it's an OMH-related plugin — if the tool errors with\n  \"function not found,\" the plugin isn't loaded.\n\nSee sibling skill `enabling-hermes-plugin-in-profile` for the full\nplugin-install diagnostic ladder if tools genuinely don't surface\nafter restart.\n\n## State management cheat sheet\n\n```python\n# Step 0: check + lock\nomh_state(action=\"cancel_check\", mode=\"ralph\", instance_id=instance_id)\nlock = omh_state(action=\"lock\", mode=\"ralph\", lock_key=instance_id,\n                  session_id=session_id, holder_note=\"...\")\n\n# Step 1: read state (or trigger planning gate)\nstate = omh_state(action=\"read\", mode=\"ralph\", instance_id=instance_id)\ntasks = omh_state(action=\"read\", mode=\"ralph-tasks\", instance_id=instance_id)\n\n# Step 2: planning gate (only on first invocation)\nomh_state(action=\"write\", mode=\"ralph-tasks\", instance_id=instance_id, data={\n    \"tasks\": [{\"id\": \"task-1\", \"title\": \"...\", \"description\": \"...\",\n               \"acceptance_criteria\": \"...\", \"priority\": 1,\n               \"dependencies\": [], \"passes\": False, \"files\": [...]}, ...]\n})\n\n# Step 3-5: per-iteration execution\n# (delegate_task for executors, omh_gather_evidence, delegate_task for verifiers)\n\n# Step 8: update state, exit\nomh_state(action=\"write\", mode=\"ralph\", instance_id=instance_id, data={\n    \"active\": True, \"phase\": \"execute\", \"iteration\": N, ...,\n    \"completed_task_learnings\": [...]\n})\nomh_state(action=\"unlock\", mode=\"ralph\", lock_key=instance_id, session_id=session_id)\n```\n\n## What \"done\" looks like for the orchestrator\n\n- All tasks have `passes: true` in ralph-tasks state.\n- Step 7 final architect review: APPROVE or APPROVE_WITH_PROVISO with\n  provisos folded.\n- `\u003Corchestrator>-architect-review.md` written.\n- `.omh\u002Flogs\u002Fralph-progress.md` (or domain-equivalent) names the\n  iteration arc, strikes encountered, and key learnings.\n- State marked `phase: complete`, `active: false`.\n- Lock released.\n- The user can open a PR from the branch.\n\n## Worked example (2026-04-27, janus migration)\n\n13-task plan, 5 iterations, 1 strike total, final APPROVE_WITH_PROVISO.\n\n- **iter 1**: 3 independents (RELEASES.yaml, AGENT.md patch, retire\n  janus-migration skill) in parallel. All APPROVE.\n- **iter 2**: task-4 solo (lineage capture, gates 5\u002F6\u002F8). Strike 1\n  was test-infra hash collision. APPROVE on retry.\n- **iter 3**: 3 parallel (gh-config, backfill-lineage, lib.py). Each\n  task's dispatch said \"DO NOT modify bin\u002F_lineage.py — Task X owns\n  it.\" Strike-zero round.\n- **iter 4**: 3 parallel (janus-migrate skill, janus-update CLI,\n  pytest harness). Strike-zero.\n- **iter 5**: 3 parallel (boot-context surface, janus-contribute stub,\n  v2 migrations). Strike-zero. **One commit-hygiene issue:** task-11\n  absorbed task-12 files via `git add -A`. Tests green; flagged for\n  architect review.\n- **Step 7**: architect APPROVE_WITH_PROVISO, two foldable items\n  (commit-hygiene rebase + missing migrations\u002FREADME.md).\n\nTotal: 0 → 132 tests across 14 implementation commits. The discipline\nthat made this strike-zero across 4\u002F5 parallel iterations was P3\n(\"DO NOT modify \u003Cshared file>\") + P4 (forward-learnings encoding) +\nP6 (orchestrator-runs-evidence). The one strike was P5 test-infra,\nrecovered cleanly.\n\n## Maintaining your own run log\n\nEach ralph run that produces new pitfalls or surprising patterns is\nworth logging. Keep a short table:\n\n| Date | Domain | Iters | Strikes | Surprises | Patches to this skill |\n|------|--------|-------|---------|-----------|------------------------|\n\nDon't let this skill turn into a session log. Log somewhere else\n(your substrate, project notes, a wiki). Patch this skill only when\na pitfall is general enough to teach a future orchestrator.\n\n## Related skills\n\n- `omh-ralph` — the worker-side discipline, loaded inside each\n  delegate_task. Required reading for the orchestrator (one-off, to\n  understand what the workers are doing) but not loaded into worker\n  context (they auto-inject role prompts via the plugin).\n- `omh-ralplan-driver` — the dispatcher playbook for the\n  design loop. Use BEFORE ralph if no plan exists yet. Same shape\n  (driver-side skill) for a different method (consensus design vs\n  verified execution).\n- `omh-ralplan` — the worker-side design discipline. Use only inside\n  delegate_task with `[omh-role:planner|architect|critic]` markers.\n- `enabling-hermes-plugin-in-profile` — sibling skill for the\n  plugin-install diagnostic ladder. Cite if a ralph run is blocked\n  because OMH tools aren't in the function schema.\n- `subagent-driven-development` — the simpler shape for plans without\n  the OMH plugin available. Same architectural pattern but without\n  state machinery, role injection, or evidence tooling.\n\n## Do-not-lose content\n\nThe single most load-bearing insight: **the orchestrator runs evidence,\nnot the verifier.** Always `omh_gather_evidence` BEFORE dispatching\nthe verifier. Include real test output in the verifier's context.\nThis is what makes ralph's verdicts trustworthy; without it, you have\ntwo layers of executor-self-reporting.\n\nSecond: **\"DO NOT modify \u003Cshared file>\" is the discipline that makes\nparallel batches of 3 work.** Every parallel-executor dispatch must\nname what files belong to siblings. Without this, parallel batches\nrace on shared files and one task's commit absorbs another's work.\n\nThird: **strikes have categories.** Test-infra ≠ spec-misread ≠\nimplementation-bug. Tag the category; the 3-strike circuit breaker\nshould fire on the *same* category, not just the same task. Mixing\ncategories produces false-positive halts (or worse, false-negatives\nwhere a real bug masquerades as test-infra).\n\nFourth: **the orchestrator's altitude is \"between iterations,\"**\nnot inside any one task. The iron-law of one-task-per-invocation\nexists so you can stay at altitude — picking batches, encoding\nlearnings forward, gathering evidence, dispatching verifiers,\ndeciding retry vs advance. Drop into the work and you become an\nexecutor; the loop's whole value collapses.\n","# OMH Ralph Driver — orchestrator's playbook for verified execution\n\nLoad this skill alongside `omh-ralph` when you are the orchestrator\ndispatching the loop. `omh-ralph` is loaded by the role-tagged\n*workers* (executor \u002F verifier \u002F architect) — it covers the iron-law\ndiscipline inside each task's `delegate_task` call. This skill covers\nwhat *you* do as the dispatcher: plan-shape, iteration cadence,\nparallel batching, evidence gathering, verifier dispatch, strike\nhandling, commit hygiene, and the final architect gate.\n\nThe two skills have different readers and different jobs. Don't merge\nthem — worker context is precious; the dispatcher's playbook should\nnot ride into every subagent.\n\nThis skill is the ralph-side counterpart to `omh-ralplan-driver`\n(which is the dispatcher playbook for ralplan, the design loop). The\nrelationship is consistent: each method has a worker-side skill (used\ninside delegate_task) and a driver-side skill (used by the orchestrator\nbetween dispatches).\n\n## When to use ralph vs just write the code\n\nUse ralph when:\n\n- You have a plan with 5+ independently-acceptable tasks (from\n  `omh-ralplan` or hand-authored).\n- Quality-via-verification matters more than wall-clock — each task's\n  output must be evidence-graded before the next builds on it.\n- You want clean checkpoints across many work units (no context bloat).\n- Some tasks are independent and can run in parallel batches.\n\nDon't use ralph when:\n\n- The work is single-step or trivially obvious to write directly.\n- No plan exists yet — run `omh-ralplan` (or for an obvious goal,\n  `omh-deep-interview` first) before invoking ralph.\n- The user wants to skip verification (unusual; usually means the\n  work is small enough to do directly).\n\n## The arc of a ralph run\n\n```\niter 1: pick eligible tasks → dispatch executors (parallel where safe)\n        → gather evidence → dispatch verifiers (parallel) → mark passes\u002Ffails\n        → update state → release lock → exit\n\niter 2: re-invoke. Read state. Pick next batch. Same cycle.\n\n...\n\niter N: all tasks pass → Step 7 final architect review → mark complete.\n```\n\nThe orchestrator's job between iterations: pick the right batch, write\nthe right context for each executor, gather the right evidence, parse\nthe verifier verdicts, and decide whether to retry or move on.\n\n## The five-step playbook\n\n### 1. Read the plan; verify it is ralph-shaped\n\nA ralph plan is a list of numbered tasks, each with:\n\n- A clear title.\n- A description tight enough that an executor with no prior context\n  can implement it.\n- **Acceptance criteria that are testable.** Generic criteria like\n  \"implementation is complete\" are rejected by ralph's planning gate.\n- Dependencies (which other tasks must be done first).\n- Files-touched (for parallel-batch planning — see step 3).\n\nIf the plan came from `omh-ralplan`, it is design-shaped, not ralph-shaped. The stance's \"MV slice\" section is your starting point; you may need to translate it to ralph's task format. Author `.omh\u002Fplans\u002Fralph-plan.md` (or `.omh\u002Fplans\u002Fralplan-\u003Cslug>.md` if it derives from a specific ralplan instance) with proper task structure.\n\nThe plan does not need every task pre-authored to the same depth — it can grow. Ralph's planning gate parses what's there at first invocation; new tasks discovered during execution land via the `discovered: true` flag in state.\n\n### 2. Pick the right batch for each iteration\n\nEach ralph iteration does ONE unit of work. A \"unit\" can be:\n\n- One task (when the next eligible task is alone, or has shared file\n  footprint with other eligibles)\n- A batch of 2-4 tasks (when independents are eligible and have\n  disjoint touch sets)\n\n**Eligibility** = `passes: false` AND all dependencies met.\n\n**Disjoint touch sets** = the tasks do not modify the same files. Read\nthe plan's \"Files to modify\u002Fcreate\" lists. If two eligible tasks both\ntouch `bin\u002Fjanus-new-being`, they are NOT parallel-safe — one owns\nthe modification. If one touches `migrations\u002Flib.py` and another\ntouches `bin\u002F_lineage.py`, they are parallel-safe.\n\n**Edge case — shared imports.** Even if files are disjoint, if Task A\nauthors a helper that Task B imports, you may need Task A to land first.\nSurface this in dependency declarations during plan-authoring; if you\nmiss it, the executor for B will surface the dependency mid-task.\n\n**Right batch size.** 2-4 tasks. Five+ in one batch overloads\norchestrator parsing of executor reports + verifier dispatch in your\nown context window.\n\n### 3. Dispatch executors with rich context\n\nEach executor gets a fresh subagent. Subagents have NO memory of\nprior iterations, prior conversations, prior tasks. Encode everything\nthey need in the dispatch context.\n\nThe executor dispatch context must contain:\n\n- **Project root + branch.** Paths absolute, not relative.\n- **Prior state.** What tasks completed in earlier iterations, what\n  files now exist, what helpers\u002Flibraries are available to import.\n- **Learnings from prior tasks** that are relevant to this one. Pull\n  forward gotchas, naming conventions, architectural choices that\n  the executor needs to honor.\n- **The task itself.** Full title, description, acceptance criteria.\n- **Required reading.** Absolute paths to the canonical design,\n  prior tasks' outputs, similar siblings to pattern-match against.\n- **TDD instruction.** Failing test first, watch it fail, implement,\n  watch it pass, run full suite, commit. Make this explicit in\n  EVERY executor dispatch.\n- **Commit metadata.** Author identity, commit message shape, branch.\n- **DO NOT modify \u003Clist>.** Critically important under parallel\n  batches. See P3 below.\n\nUse the `[omh-role:executor]` marker in the goal — the OMH plugin\nauto-injects the executor role prompt via its `pre_llm_call` hook.\nDon't inline role text manually.\n\nA full template for the executor `goal` field — including TDD\ninstructions, sibling-aware DO-NOT-modify discipline, commit metadata,\nand retry variations for each strike category — is at\n`references\u002Fexecutor-goal-template.md`. Adapt the variables; keep the\nstructure.\n\n### 4. Gather evidence with `omh_gather_evidence` BEFORE dispatching verifiers\n\nAfter all executors complete, run the project's actual test\u002Fbuild\u002Flint\ncommands via `omh_gather_evidence`. This produces a structured\n`{results, all_pass, summary}` object the verifier can grade against.\n\n**Critical:** the verifier does NOT run evidence themselves. Gathering\nhappens at the orchestrator level so you can verify executor claims\nmatch reality before the verifier reads them.\n\n**Allowlist gotcha.** `omh_gather_evidence` enforces a token-prefix\nallowlist (`~\u002F.hermes\u002Fplugins\u002Fomh\u002Fconfig.yaml` →\n`evidence_tool.allowlist_prefixes`). Common project test commands like\n`uv run --with pytest --with pyyaml -m pytest` do NOT match\n`uv run pytest` because `--with` breaks the prefix. Either:\n\n- Use the matching prefix: `uv run pytest \u003Cargs>` (preferred — keep\n  pytest as a project dev dep so `--with pytest` is unnecessary).\n- Add a custom prefix to the OMH config.\n- Wrap with a project-local script.\n\nIf gather_evidence rejects your command, the symptom is `exit_code: -1,\noutput: \"Command not in allowlist\"`. Re-form the command before\ndispatching the verifier.\n\n### 5. Dispatch verifiers in parallel (batched per task)\n\nFor each completed task, dispatch a verifier subagent with:\n\n- `[omh-role:verifier]` marker (auto-injects the verifier role prompt).\n- The task's acceptance criteria (so they grade against the spec, not\n  the executor's interpretation of it).\n- The full evidence output (the verifier MUST see real test results,\n  not paraphrased success claims).\n- File paths to inspect.\n- Specific load-bearing checks that go beyond \"tests pass\" (e.g.,\n  \"verify the mismatched-flag check happens BEFORE any filesystem\n  writes — if not, partial-flag invocations corrupt state\").\n\nVerifiers run in parallel via batched `delegate_task(tasks=[...])` —\nsame wall-clock savings as Round 2 ralplan reviewers.\n\nThe verifier returns one of:\n\n- **APPROVE** \u002F PASS — task's `passes` flag becomes `true`.\n- **REQUEST_CHANGES** \u002F FAIL — record verdict, retry executor with the\n  feedback. Track strikes (see P5 below).\n\nA full template for the verifier `goal` field — including the\nacceptance-criteria-verbatim discipline, evidence-paste shape, sibling\nboundary checks, strike categorization, and worked verdict examples —\nis at `references\u002Fverifier-goal-template.md`.\n\n## Pitfalls (P1–P10)\n\nThese are the failure modes that ralph dispatchers stumble into.\nNumbered for cross-reference; gaps reserved for future additions.\n\n### P1 — Plan must be ralph-shaped, not design-shaped\n\n`omh-ralplan` produces a `stance.md` — a design document. Ralph\nneeds a task list with testable acceptance criteria.\n\nIf you point ralph at a stance directly, the planning gate either\nparses it weakly (extracting whatever numbered sections look\ntask-shaped) or refuses outright. Translate the stance's MV slice\ninto a proper ralph plan first.\n\nThe translation is mechanical:\n\n- Stance MV-slice items → ralph tasks (one item per task).\n- Stance test affordances → task acceptance criteria (verbatim where\n  the stance named them).\n- Stance \"depends on\" prose → task `dependencies:` field.\n- Stance file paths → task `files:` list (for parallel-batch\n  planning).\n\nAuthor the ralph plan as `.omh\u002Fplans\u002Fralph-plan.md` or\n`.omh\u002Fplans\u002Fralplan-\u003Cslug>.md`. Ralph's planning gate finds either.\n\n**Worked translation example (from the 2026-04-27 janus run).** The\nstance's \"MV slice plan\" section listed 13 work items spread across\nNOW (~3.5h, lineage capture before next provision) \u002F NEXT (+72h, the\nupdate tool) \u002F DEFERRED (later releases). The ralph plan landed each\nitem as a task with this shape:\n\n```markdown\n### Task 4 — bin\u002Fjanus-new-being: version stamp + seed-history snapshot\n\n**Files to modify:**\n- `bin\u002Fjanus-new-being`\n\n**Files to create:**\n- `bin\u002Ftests\u002Ftest_janus_new_being_lineage.py`\n\n**Description:**\nPatch `bin\u002Fjanus-new-being` provisioning logic to write lineage data\nper the stance's NOW slice item 2. After successful provisioning,\nwrite `\u003Cprofile>\u002F.janus\u002Fversion`, snapshot rendered template + plugin\ntree to `\u003Cprofile>\u002F.janus\u002Fseed-history\u002Fv1\u002F` via post-write disk-read,\ncompute MANIFEST with content hashes per file...\n\n**Acceptance criteria (verbatim from stance test affordance):**\n\n    def test_provision_writes_v1_lineage(tmp_path):\n        profile = tmp_path \u002F \"alice-janus\"\n        # ... provision invocation ...\n        assert (profile \u002F \".janus\" \u002F \"version\").read_text().strip() == \"v1\"\n        seed = profile \u002F \".janus\" \u002F \"seed-history\" \u002F \"v1\"\n        assert (seed \u002F \"SOUL.md\").exists()\n        ...\n\n**Dependencies:** none (Task 5 extends, but doesn't conflict)\n```\n\nThe translation discipline that made this work:\n\n1. **Verbatim acceptance criteria from the stance.** Where the stance\n   said `test_provision_writes_v1_lineage_and_gh_config` passes, the\n   ralph plan used that exact test name. This makes the executor\n   write the test the stance specified, and the verifier grade\n   against the stance's own contract — no drift through paraphrase.\n\n2. **Files-touched are explicit.** Each task's `files:` lists exactly\n   what gets created and modified. This is what enables parallel-\n   batch planning later (P2): the orchestrator can read the lists\n   and check disjoint touch sets without re-deriving them from the\n   description prose.\n\n3. **Dependencies are inferred from shared concrete artifacts, not\n   just prose.** The stance said the MANIFEST shape was authored in\n   Task 4; Task 8 (lib.py with `hash_equals_ancestor`) needs to read\n   that format. So Task 8's `dependencies: [task-4]` was inferred from\n   the shared file format, not from a \"Task 8 must come after Task 4\"\n   sentence.\n\n4. **NOW\u002FNEXT\u002FDEFERRED gets folded into priority ordering.** All\n   NOW-slice tasks get `priority: 1` or `priority: 2` (with\n   priority-2 reserved for ones that gate later parallel batches).\n   NEXT gets 3-5. DEFERRED items don't appear as ralph tasks at all\n   — they're not part of this run's work envelope.\n\n5. **Test affordance section per task gets expanded to full pytest\n   function signatures.** The stance often listed test names with\n   brief shape; the ralph task gives the executor the exact function\n   names + behavior so they don't have to re-derive them.\n\n**The translation is its own load-bearing step.** Doing it sloppy\nproduces a sloppy run no matter how disciplined the orchestration is\nafterward. The ralph plan IS the contract executors implement and\nverifiers grade against; if it's vague, the loop produces vague work.\n\nBudget 30-60 minutes for the translation on a 10+ task plan. The\noutput is the file ralph's planning gate parses; you'll never look at\nthe stance directly again during the run.\n\n### P2 — Identify parallel-safe batches before dispatching, not during\n\nWalk all eligible tasks (`passes: false` + deps met) at the start of\neach iteration. For each pair, check disjoint-touch-set. Mark the\nparallel-safe set; dispatch them in one batched `delegate_task`.\n\nIf you wait until after dispatching one task to consider whether\nothers could have run in parallel, you've forfeited the wall-clock\nsavings for that iteration. The right-time-to-decide is at the start\nof the iteration, when you're already reading state.\n\nRight batch size is 2-4. Two if dependencies are tight; four if\nmultiple independents stack. Five-plus overloads the orchestrator's\nown context with executor reports + parallel verifier dispatches.\n\n### P3 — \"DO NOT modify \u003Cshared file>\" must be explicit in parallel dispatch contexts\n\nWhen dispatching parallel executors, only ONE task owns each shared\nfile. The other executors must import (read-only) but not modify it.\n\nEncode this explicitly in each executor's dispatch context:\n\n> DO NOT modify migrations\u002Flib.py during this task — Task X owns that\n> change. Import what you need; if a function isn't there yet, fall\n> back to inline implementation that matches Task X's expected\n> signature so they converge cleanly when both commits land.\n\nWithout this instruction, parallel executors race on the shared file\nand produce conflicting commits. With it, they respect the boundary\nand commit only their own work.\n\nThe instruction should also tell each executor to **unstage sibling\ntasks' files before commit**. Otherwise `git add -A` sweeps in\nneighbors' uncommitted work — see P9.\n\n### P4 — Encode forward-learnings in each executor dispatch\n\nEach iteration produces learnings (gotchas, naming conventions,\npatterns that worked, patterns that failed). The next iteration's\nexecutors do NOT see these unless you encode them.\n\nMaintain a per-iteration learnings list in the ralph state's\n`completed_task_learnings` field, and include the relevant subset in\neach subsequent executor's dispatch context.\n\nExamples worth encoding forward:\n\n- \"TEST-INFRA: never use `hash(content) & 0xffff` for tmpdir naming\n  — randomized + small modulus = collision risk.\"\n- \"Use `git rm -r` (not `rm -rf`) to preserve git history when\n  removing tracked files.\"\n- \"bin\u002Fjanus-new-being uses uv shebang, no .py suffix; new bin\u002F*\n  scripts should follow the same pattern.\"\n- \"The classify() function in bin\u002F_lineage.py ships the criterion\n  (path-prefix patterns + Class-B exact set), not enumeration. Reuse\n  it; don't duplicate the taxonomy.\"\n\nThese compress and ride forward via the dispatch context. The\nomh-ralph state's `completed_task_learnings` is the canonical store.\n\n### P5 — Distinguish executor strikes by category\n\nWhen the verifier returns REQUEST_CHANGES, the cause is one of:\n\n1. **Test-infra** — the test itself is buggy (e.g., a `hash() & 0xffff`\n   path collision, a fixture race, a test runner config issue). The\n   implementation may be correct; only the test needs fixing.\n\n2. **Spec-misread** — the executor implemented something different\n   from what the acceptance criteria asked for. Implementation needs\n   correction.\n\n3. **Implementation bug** — the executor implemented the right thing\n   but it has a real defect (logic error, edge case missed, security\n   issue).\n\nThese three categories take different fixes. Test-infra retries\nshould touch only the test file. Spec-misread retries need fresh\ncontext emphasizing what the spec actually requires. Implementation-\nbug retries need the failing case named explicitly.\n\nTag the strike category in the error fingerprint when updating state:\n\n```python\n\"error_fingerprints\": [\n    {\"category\": \"test-infra\", \"error_key\": \"hash-collision-in-tmpdir-naming\", \"round\": 1},\n    ...\n]\n```\n\nThe 3-strike circuit breaker (per `omh-ralph` Step 6) fires when the\nsame `(category, error_key)` repeats three times. Tagging by category\nprevents test-infra strikes from masking real bugs (or vice versa).\n\n### P6 — Verifiers must read real evidence, not executor claims\n\nAlways run `omh_gather_evidence` before dispatching verifiers.\nInclude the evidence output in the verifier's dispatch context.\n\nIf you skip evidence-gathering, the verifier reads only the executor's\nreport (\"Status: COMPLETE; 5 tests pass; commit X\") and has no\nground truth to grade against. Executor reports are sometimes wrong\n— either the executor genuinely missed something, or a test passed\nfor the wrong reason (e.g., a path-collision crashing before the\nload-bearing assertion ran — see this skill's worked example).\n\nThe orchestrator-runs-evidence pattern is what makes ralph\nverification trustworthy.\n\n### P7 — Final architect review (Step 7) is the merge gate\n\nWhen all tasks pass, ralph's Step 7 dispatches an architect to review\nthe full implementation against the original plan\u002Fstance.\n\nThe architect reviews HOLISTICALLY:\n\n- Architectural fidelity (did the implementation honor the design?)\n- Principle alignment (do load-bearing principles fire in mechanics,\n  not just appear in prose?)\n- MV slice readiness (can the user actually run this tonight?)\n- Architectural seams (anything rough vs explicitly deferred?)\n- Commit hygiene (is the git history clean enough to merge?)\n- Test affordance gaps\n\nThis is the orchestrator's final gate before handing the user a\nPR-ready branch. The architect can return:\n\n- **APPROVE** — seal-of-merge.\n- **APPROVE_WITH_PROVISO** — small foldable additions before merge\n  (typically 1-3 named items).\n- **REQUEST_CHANGES** — something cannot ship; new tasks added with\n  `discovered: true`.\n\nAuthor the architect's review as `\u003Corchestrator>-architect-review.md`\nin the design directory (the orchestrator's own iteration-level review\nis `\u003Corchestrator>-review.md`; the architect-review is a separate\nartifact).\n\nA full template for the architect-final-review `goal` field — including\nthe diff-range walk, end-to-end MV-slice trace, principle-firing audit,\ncommit-hygiene check, verdict calibration guidance, and worked review\nexamples (APPROVE_WITH_PROVISO and REQUEST_CHANGES) — is at\n`references\u002Farchitect-final-review-template.md`.\n\n### P8 — Update state at every action; release lock at every exit\n\nPer `omh-ralph` Step 0\u002FStep 8: state files at\n`.omh\u002Fstate\u002Fralph--\u003Cinstance_id>.json` and\n`.omh\u002Fstate\u002Fralph-tasks--\u003Cinstance_id>.json` track the run. Lock at\n`.omh\u002Fstate\u002Fralph--\u003Cinstance_id>.lock` prevents concurrent sessions\nracing on the same plan.\n\nDiscipline:\n\n- Acquire the lock at iteration start (Step 0).\n- Update state after every executor completion, every verifier\n  verdict, every task transition.\n- Release the lock at every exit point — success, blocked, cancel,\n  max-iterations, exception. Wrap the iteration body so unlock fires\n  even on error.\n\nDo NOT leave stale locks. If a lock is held by a dead process, the\nnext ralph invocation will surface it via `held_by` — offer to cancel\n+ retry, don't silently steal.\n\n### P9 — Commit hygiene under parallel writes\n\nThree executors writing to the same branch in one orchestrator turn\nwill see *partial* state from each other (whatever has been committed)\nbut NOT each other's uncommitted work. If one executor uses\n`git add -A` to stage their commit, they may sweep in sibling\nexecutors' files that are still in-flight.\n\nDiscipline for parallel-executor dispatch:\n\n1. **Tell each executor to `git add` their specific files explicitly**,\n   not `git add -A`. Names match the task's `files:` field.\n\n2. **Tell each executor to check `git status` before commit**: if\n   sibling tasks' files are present and unstaged, do NOT include them.\n   Common sibling files: untracked __init__.py stubs, untracked test\n   files, RELEASES.yaml mid-edit.\n\n3. **Accept that absorption sometimes happens anyway.** When it does,\n   the failure is recoverable: an interactive rebase squashes the\n   over-broad commit with the missing one, OR a follow-up history-note\n   commit explains the boundary.\n\n4. **Surface the absorption in iteration logs.** If you notice an\n   executor reported \"swept in pre-existing untracked files,\" flag it\n   for the architect's commit-hygiene check at Step 7.\n\nThis pattern was learned the hard way: in one run, task-11's commit\nabsorbed ~60% of task-12's intended-commit content via `git add -A`.\nTests stayed green; deliverables were correct; commit boundaries were\nfuzzy. Architect flagged it as a foldable proviso.\n\n### P10 — Resume vs restart matters for plugin\u002Ftool changes\n\nIf the user makes plugin or toolset changes between iterations\n(adding a tool, enabling a plugin, modifying config.yaml), tools do\nNOT register live in the current session. They register at agent\n**boot**.\n\nIf the user says \"I changed the config, can you use the new tool now?\":\n\n- The session needs a full restart, not just a Resume button click\n  (some chat UIs reuse the same agent process across \"Resume\").\n- Verify by checking your function schema — if the new tool isn't\n  there, the boot didn't happen.\n- The fastest way to know is `omh_state(action=\"check\", ...)` if\n  it's an OMH-related plugin — if the tool errors with\n  \"function not found,\" the plugin isn't loaded.\n\nSee sibling skill `enabling-hermes-plugin-in-profile` for the full\nplugin-install diagnostic ladder if tools genuinely don't surface\nafter restart.\n\n## State management cheat sheet\n\n```python\n# Step 0: check + lock\nomh_state(action=\"cancel_check\", mode=\"ralph\", instance_id=instance_id)\nlock = omh_state(action=\"lock\", mode=\"ralph\", lock_key=instance_id,\n                  session_id=session_id, holder_note=\"...\")\n\n# Step 1: read state (or trigger planning gate)\nstate = omh_state(action=\"read\", mode=\"ralph\", instance_id=instance_id)\ntasks = omh_state(action=\"read\", mode=\"ralph-tasks\", instance_id=instance_id)\n\n# Step 2: planning gate (only on first invocation)\nomh_state(action=\"write\", mode=\"ralph-tasks\", instance_id=instance_id, data={\n    \"tasks\": [{\"id\": \"task-1\", \"title\": \"...\", \"description\": \"...\",\n               \"acceptance_criteria\": \"...\", \"priority\": 1,\n               \"dependencies\": [], \"passes\": False, \"files\": [...]}, ...]\n})\n\n# Step 3-5: per-iteration execution\n# (delegate_task for executors, omh_gather_evidence, delegate_task for verifiers)\n\n# Step 8: update state, exit\nomh_state(action=\"write\", mode=\"ralph\", instance_id=instance_id, data={\n    \"active\": True, \"phase\": \"execute\", \"iteration\": N, ...,\n    \"completed_task_learnings\": [...]\n})\nomh_state(action=\"unlock\", mode=\"ralph\", lock_key=instance_id, session_id=session_id)\n```\n\n## What \"done\" looks like for the orchestrator\n\n- All tasks have `passes: true` in ralph-tasks state.\n- Step 7 final architect review: APPROVE or APPROVE_WITH_PROVISO with\n  provisos folded.\n- `\u003Corchestrator>-architect-review.md` written.\n- `.omh\u002Flogs\u002Fralph-progress.md` (or domain-equivalent) names the\n  iteration arc, strikes encountered, and key learnings.\n- State marked `phase: complete`, `active: false`.\n- Lock released.\n- The user can open a PR from the branch.\n\n## Worked example (2026-04-27, janus migration)\n\n13-task plan, 5 iterations, 1 strike total, final APPROVE_WITH_PROVISO.\n\n- **iter 1**: 3 independents (RELEASES.yaml, AGENT.md patch, retire\n  janus-migration skill) in parallel. All APPROVE.\n- **iter 2**: task-4 solo (lineage capture, gates 5\u002F6\u002F8). Strike 1\n  was test-infra hash collision. APPROVE on retry.\n- **iter 3**: 3 parallel (gh-config, backfill-lineage, lib.py). Each\n  task's dispatch said \"DO NOT modify bin\u002F_lineage.py — Task X owns\n  it.\" Strike-zero round.\n- **iter 4**: 3 parallel (janus-migrate skill, janus-update CLI,\n  pytest harness). Strike-zero.\n- **iter 5**: 3 parallel (boot-context surface, janus-contribute stub,\n  v2 migrations). Strike-zero. **One commit-hygiene issue:** task-11\n  absorbed task-12 files via `git add -A`. Tests green; flagged for\n  architect review.\n- **Step 7**: architect APPROVE_WITH_PROVISO, two foldable items\n  (commit-hygiene rebase + missing migrations\u002FREADME.md).\n\nTotal: 0 → 132 tests across 14 implementation commits. The discipline\nthat made this strike-zero across 4\u002F5 parallel iterations was P3\n(\"DO NOT modify \u003Cshared file>\") + P4 (forward-learnings encoding) +\nP6 (orchestrator-runs-evidence). The one strike was P5 test-infra,\nrecovered cleanly.\n\n## Maintaining your own run log\n\nEach ralph run that produces new pitfalls or surprising patterns is\nworth logging. Keep a short table:\n\n| Date | Domain | Iters | Strikes | Surprises | Patches to this skill |\n|------|--------|-------|---------|-----------|------------------------|\n\nDon't let this skill turn into a session log. Log somewhere else\n(your substrate, project notes, a wiki). Patch this skill only when\na pitfall is general enough to teach a future orchestrator.\n\n## Related skills\n\n- `omh-ralph` — the worker-side discipline, loaded inside each\n  delegate_task. Required reading for the orchestrator (one-off, to\n  understand what the workers are doing) but not loaded into worker\n  context (they auto-inject role prompts via the plugin).\n- `omh-ralplan-driver` — the dispatcher playbook for the\n  design loop. Use BEFORE ralph if no plan exists yet. Same shape\n  (driver-side skill) for a different method (consensus design vs\n  verified execution).\n- `omh-ralplan` — the worker-side design discipline. Use only inside\n  delegate_task with `[omh-role:planner|architect|critic]` markers.\n- `enabling-hermes-plugin-in-profile` — sibling skill for the\n  plugin-install diagnostic ladder. Cite if a ralph run is blocked\n  because OMH tools aren't in the function schema.\n- `subagent-driven-development` — the simpler shape for plans without\n  the OMH plugin available. Same architectural pattern but without\n  state machinery, role injection, or evidence tooling.\n\n## Do-not-lose content\n\nThe single most load-bearing insight: **the orchestrator runs evidence,\nnot the verifier.** Always `omh_gather_evidence` BEFORE dispatching\nthe verifier. Include real test output in the verifier's context.\nThis is what makes ralph's verdicts trustworthy; without it, you have\ntwo layers of executor-self-reporting.\n\nSecond: **\"DO NOT modify \u003Cshared file>\" is the discipline that makes\nparallel batches of 3 work.** Every parallel-executor dispatch must\nname what files belong to siblings. Without this, parallel batches\nrace on shared files and one task's commit absorbs another's work.\n\nThird: **strikes have categories.** Test-infra ≠ spec-misread ≠\nimplementation-bug. Tag the category; the 3-strike circuit breaker\nshould fire on the *same* category, not just the same task. Mixing\ncategories produces false-positive halts (or worse, false-negatives\nwhere a real bug masquerades as test-infra).\n\nFourth: **the orchestrator's altitude is \"between iterations,\"**\nnot inside any one task. The iron-law of one-task-per-invocation\nexists so you can stay at altitude — picking batches, encoding\nlearnings forward, gathering evidence, dispatching verifiers,\ndeciding retry vs advance. Drop into the work and you become an\nexecutor; the loop's whole value collapses.\n",{"name":5,"version":24,"metadata":25,"description":7},"1.0.0",{"hermes":26},{"tags":27,"category":34,"requires_toolsets":35},[28,29,30,31,32,33],"execution","ralph","orchestration","multi-agent","parallel","verification","omh",[36,34],"terminal","main","d69096e239f2a89aabc2cd078c47664a9d3b1e11","05-技能与代理开发\u002Fomh-ralph-driver",3,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts","https:\u002F\u002Fgithub.com\u002Flza6","个人vx：Tf00798\r\n个人✈：@TFGY999","2026-10-08 14:29:22",{"source":8,"skillName":5,"commands":46,"prompt":56,"zipAvailable":57},[47,50,53],{"tool":48,"command":49},"npx","npx skills add lza6\u002FArmor-piercing-system-prompts --skill omh-ralph-driver",{"tool":51,"command":52},"bunx","bunx skills add lza6\u002FArmor-piercing-system-prompts --skill omh-ralph-driver",{"tool":54,"command":55},"pnpm","pnpm dlx skills add lza6\u002FArmor-piercing-system-prompts --skill omh-ralph-driver","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F05-技能与代理开发\u002Fomh-ralph-driver\u002FSKILL.md",true,[59,65,69],{"path":60,"resourceType":61,"resourceTypeDesc":62,"sizeBytes":63,"sourceHtmlUrl":64},"references\u002Farchitect-final-review-template.md","REFERENCE","参考文档",10044,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F05-技能与代理开发\u002Fomh-ralph-driver\u002Freferences\u002Farchitect-final-review-template.md",{"path":66,"resourceType":61,"resourceTypeDesc":62,"sizeBytes":67,"sourceHtmlUrl":68},"references\u002Fexecutor-goal-template.md",8070,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F05-技能与代理开发\u002Fomh-ralph-driver\u002Freferences\u002Fexecutor-goal-template.md",{"path":70,"resourceType":61,"resourceTypeDesc":62,"sizeBytes":71,"sourceHtmlUrl":72},"references\u002Fverifier-goal-template.md",7598,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F05-技能与代理开发\u002Fomh-ralph-driver\u002Freferences\u002Fverifier-goal-template.md",[74,81,86,93,100,107],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M7FFG485KY83TD6HSC4YPCMC","obsidian-clipper-template-creator","Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobsidian-clipper-template-creator\u002FSKILL.md",[],[],{"skillNo":82,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M7FFG0T6AZ0STEJPSB3CX84K","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobsidian-clipper-template-creator-antigravity-awesome-skills-main\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":19},"01M7FFFY0QEM14SKWPDYGMXM2P","python-api","Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP\u002FmAP semantics, and source-style import diagnostics.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002Fsub-skills\u002Fpython-api\u002FSKILL.md",[],[],{"skillNo":94,"name":95,"nameZh":6,"description":96,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":19},"01M7FFFVZQZ2GJ0C0TGP7JHD20","file-evaluation","Folder-based PASCAL VOC AP\u002FmAP evaluation from ground-truth and detection text files.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002Fsub-skills\u002Ffile-evaluation\u002FSKILL.md",[],[],{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":19},"01M7FFFSFNYSE77SJ6PE1CK2DA","object-detection-metrics","Guides legacy Object-Detection-Metrics PASCAL VOC AP\u002FmAP evaluation from detection text folders and direct Python API classes.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002FSKILL.md",[],[],{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":19},"01M7FFFP0GCK1RVXBCPQ8APBMT","nx-workspace-patterns","Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fnx-workspace-patterns\u002FSKILL.md",[],[]]