From 981cbceecfe0ab551d6750b15480bd23ba766a53 Mon Sep 17 00:00:00 2001 From: Giancarmine Salucci Date: Thu, 10 Sep 2026 01:57:05 +0200 Subject: [PATCH] fix(conductor): self-heal missing harness config via lh init --yes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit conductor previously jumped straight to lh host, which succeeds even without .agents/harness.config.json, then silently hit a hard failure later reading .agents/memory/INDEX.md (lh doctor confirms: config not initialised). New projects had no automatic recovery path — lh init was documented as a manual step users had to remember. - conductor now runs lh doctor first; if config is missing it runs lh init --yes (non-interactive defaults) and re-checks, before lh host - still stops and reports the exact failing check if lh doctor finds something it can't self-heal (e.g. no verify commands configured) - README/QUICKSTART updated: lh init/lh doctor documented as optional manual pre-flight, not a required step, since conductor self-heals Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/agents/conductor.agent.md | 81 +++++++++++++++++-------------- README.md | 8 +-- docs/QUICKSTART.md | 21 ++++---- 3 files changed, 61 insertions(+), 49 deletions(-) diff --git a/.github/agents/conductor.agent.md b/.github/agents/conductor.agent.md index 0380b64..3b19205 100644 --- a/.github/agents/conductor.agent.md +++ b/.github/agents/conductor.agent.md @@ -13,43 +13,46 @@ Run the full lean harness pipeline. Edit no product files. ## PROCEDURE -1. Run `lh host` first. -2. Read the printed host strategy before any other action. -3. If the strategy permits parallel lanes, use host fan-out. -4. If the strategy says sequential, run every lane one at a time. -5. Run `lh run start` and capture the run id. -6. Emit `lh run event` for every phase transition. -7. Load only `.agents/memory/INDEX.md` by default. -8. Pull memory shards only when the current phase needs them. -9. Start `scribe` after run start. -10. Keep `scribe` non-blocking. -11. For design, invoke `interrogator`. -12. Require `.agents/specs//decisions.md` before planning. -13. Enforce the user gate after design. -14. Do not infer unanswered decisions. -15. For plan, invoke `architect`. -16. Require `.agents/specs//spec.md`. -17. Invoke `splitter` to write `.agents/specs//plan.dag.json`. -18. Validate the DAG with `lh graph`. -19. Own the dynamic DAG after splitter returns. -20. For every checkpoint, read lane status and verifier output. -21. Re-plan at every checkpoint. -22. Spawn, kill, merge, or re-scope lanes only through updated `plan.dag.json` and `lh lane` commands. -23. For read lanes, run `scout` on the shared checkout. -24. For write lanes, run `lh lane create` before any builder starts. -25. Assign each builder exactly one lane and one worktree. -26. Give each builder its declared scope globs and acceptance ids. -27. Run builder and verifier in the Ralph loop. -28. Stop a lane only when all Ralph exit criteria hold. -29. On failure, isolate cause, retry within bound, then re-plan around it. -30. Escalate to the user on max Ralph iterations. -31. When build lanes pass, invoke `integrator`. -32. Require sequential integration even on parallel-capable hosts. -33. Require one final full verify after all lane merges. -34. Invoke `reviewer` for final approval if not already done by integrator. -35. Run `scribe` for final journal and deltas. -36. Run `lh run end` with success or failure. -37. Return only run id, changed lanes, verify status, and blockers. +1. Run `lh doctor`. +2. If it reports `config not initialised`, run `lh init --yes` (non-interactive defaults), then run `lh doctor` again. +3. Do not proceed past a `lh doctor` failure you cannot self-heal (for example missing `verify.commands`); report the exact failing check and stop. +4. Run `lh host`. +5. Read the printed host strategy before any other action. +6. If the strategy permits parallel lanes, use host fan-out. +7. If the strategy says sequential, run every lane one at a time. +8. Run `lh run start` and capture the run id. +9. Emit `lh run event` for every phase transition. +10. Load only `.agents/memory/INDEX.md` by default. +11. Pull memory shards only when the current phase needs them. +12. Start `scribe` after run start. +13. Keep `scribe` non-blocking. +14. For design, invoke `interrogator`. +15. Require `.agents/specs//decisions.md` before planning. +16. Enforce the user gate after design. +17. Do not infer unanswered decisions. +18. For plan, invoke `architect`. +19. Require `.agents/specs//spec.md`. +20. Invoke `splitter` to write `.agents/specs//plan.dag.json`. +21. Validate the DAG with `lh graph`. +22. Own the dynamic DAG after splitter returns. +23. For every checkpoint, read lane status and verifier output. +24. Re-plan at every checkpoint. +25. Spawn, kill, merge, or re-scope lanes only through updated `plan.dag.json` and `lh lane` commands. +26. For read lanes, run `scout` on the shared checkout. +27. For write lanes, run `lh lane create` before any builder starts. +28. Assign each builder exactly one lane and one worktree. +29. Give each builder its declared scope globs and acceptance ids. +30. Run builder and verifier in the Ralph loop. +31. Stop a lane only when all Ralph exit criteria hold. +32. On failure, isolate cause, retry within bound, then re-plan around it. +33. Escalate to the user on max Ralph iterations. +34. When build lanes pass, invoke `integrator`. +35. Require sequential integration even on parallel-capable hosts. +36. Require one final full verify after all lane merges. +37. Invoke `reviewer` for final approval if not already done by integrator. +38. Run `scribe` for final journal and deltas. +39. Run `lh run end` with success or failure. +40. Return only run id, changed lanes, verify status, and blockers. ## INPUTS @@ -75,10 +78,14 @@ Run the full lean harness pipeline. Edit no product files. - Stop when max Ralph iterations are reached. - Stop when `lh graph` keeps failing after re-plan. - Stop when host strategy forbids required action. +- Stop when `lh doctor` fails on a check `lh init --yes` cannot fix (for example missing `verify.commands`); report it, don't guess a fix. ## NEVER DO THIS - Never edit source files yourself. +- Never skip `lh doctor` at start. +- Never run `lh init` with prompts; always `--yes` (non-interactive). +- Never re-run `lh init` if `lh doctor` already reports `config` ok. - Never skip `lh host`. - Never skip `lh run start`. - Never bypass the design user gate. diff --git a/README.md b/README.md index a86a435..8c1bc55 100644 --- a/README.md +++ b/README.md @@ -140,11 +140,13 @@ export CONTEXT7_API_KEY="" # add to ~/.bashrc or ~/.zshrc ```bash cd your-repo -lh init # first-run wizard; writes .agents/harness.config.json -lh doctor # confirm everything is wired +lh init # optional: first-run wizard; writes .agents/harness.config.json +lh doctor # optional: confirm everything is wired ``` -Then, in Copilot CLI or VS Code Copilot: +`conductor` runs `lh doctor` itself and self-heals a missing config with `lh init --yes` +before doing anything else, so the two commands above are an optional manual pre-flight, not +a required step. Then, in Copilot CLI or VS Code Copilot: ``` Use the conductor agent to build a rate limiter for the public API diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 2d76bad..1c664f6 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -172,17 +172,20 @@ subcommand, who calls it, and when. | `lh lane create/status/merge` | `conductor`, `builder`, `integrator` | Automatically, before a write lane starts and when it merges | | `lh memory get/put/scan` | `interrogator`, `architect`, `builder`, `scribe` | Automatically, to pull relevant shards before work and record facts/failures after | | `lh graph` | `verifier` (always), plus `architect`/`splitter`/`conductor`/`reviewer`/`scout`/`integrator` at their own checkpoints | Automatically — it's exit criterion #3, never skipped | -| `lh init` | You (or `scripts/onboard.mjs` on your behalf) | Once per repo, at setup, or to repair a missing `.agents/` baseline | -| `lh doctor` | You | Whenever you want to check the environment yourself — before starting, after upgrading Node/git/the plugin, or to diagnose a stuck run. Also run once automatically right after `lh init` | +| `lh doctor` | `conductor` (first thing, before `lh host`), also you whenever you want to check the environment yourself | Automatically at the start of every pipeline run — `conductor`'s step 1 | +| `lh init --yes` | `conductor`, automatically, only if `lh doctor` reports `config not initialised` | Self-heals a missing `.agents/` baseline with non-interactive defaults, then re-runs `lh doctor` | | `lh report ` | You | After a run, when you want a human-readable markdown summary instead of raw NDJSON. No agent generates this for you | -So the only commands you are expected to type by hand in everyday use are `lh init` (setup), -`lh doctor` (diagnostics), and `lh report` (reading a past run's summary). Everything else — -`lh index`, `lh host`, `lh run`, `lh lane`, `lh memory`, `lh graph` — is invoked by the agents -as a scripted, mandatory step in their own instructions. You'd only run one of those manually -if you're debugging outside the agent flow (e.g. `lh graph` on its own to check structure -before opening Copilot at all, or `lh memory get --shard failures` to read what the harness has -learned). +So in everyday use you don't have to type `lh init` or `lh doctor` by hand at all — +`conductor` runs `lh doctor` first, and if that reports the repo isn't initialised, it runs +`lh init --yes` for you (defaults, no prompts) and re-checks before doing anything else. It +still stops and reports the exact failing check if `lh doctor` finds something it can't +self-heal (for example no verify commands configured yet in a brand-new, empty repo). +`lh init`/`lh doctor` remain available for you to run by hand too — useful before starting +(to pre-flight a repo), after upgrading Node/git/the plugin, or to diagnose a stuck run outside +the agent flow. The only command with no agent equivalent at all is `lh report` (reading a past +run's summary). Everything else — `lh index`, `lh host`, `lh run`, `lh lane`, `lh memory`, +`lh graph` — is invoked by the agents as a scripted, mandatory step in their own instructions. ## 5. Know when it's actually done