From 243f37cfe78c12b6315f003eac51910e3f8a52cc Mon Sep 17 00:00:00 2001 From: Rupak Saha Date: Mon, 3 Aug 2026 23:07:22 +0600 Subject: [PATCH] =?UTF-8?q?roles/tech-lead:=20liveness=20=E2=80=94=20the?= =?UTF-8?q?=20in-process=20tech-lead=20owns=20coder=20stall=20detection?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #269. A spawned coder that ends its turn to wait on a self-armed background watcher may never be re-invoked: the work finishes, the report never arrives, and the loop silently loses wall-clock (observed twice in one /forge run; the second stall cost hours before a human noticed). Adds a Liveness subsection under "Two drivers, one choreography": - coder briefs forbid stop-and-wait (poll in-turn or hand the wait back in the report), - the tech-lead arms an independent ~5-min watchdog over observable progress signals (new commits, tree churn, live build processes) and nudges the idle coder after ~2 quiet cycles, treating the agent's own resume as primary signal and the watchdog as fallback heartbeat. Authority for the mechanism claims: empirical, from the source session — both stalls reproduced the shape (artifacts done, tree dirty, agent idle with no active task); the watchdog+nudge pattern caught the next stall within 10 minutes. Frontmatter gains stall/liveness triggers. Co-Authored-By: Claude Fable 5 --- docs/roles/tech-lead.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/roles/tech-lead.md b/docs/roles/tech-lead.md index d91a848..bdc9fb7 100644 --- a/docs/roles/tech-lead.md +++ b/docs/roles/tech-lead.md @@ -7,6 +7,9 @@ triggers: - partition - integrate coders - parallel build coordinator + - coder stalled + - stall watchdog + - liveness when: Internal. Loaded by an agent acting as the implementation-loop coordinator, spawned by a driver (/forge or candyland) against a settled plan contract. related: - core/build @@ -41,6 +44,15 @@ The tech-lead is the orchestrating role of the parallel implementation loop. It The critical invariant in both: **the tech-lead decides and emits; it never hides coders inside its own context in a way the driver can't see.** Under candyland that means emit-don't-spawn; under `/forge` the sub-agents are the spawn. +### Liveness — the tech-lead owns stall detection (in-process driver) + +A spawned coder that stops its turn to "wait" on its own background watcher (a build monitor, a completion hook) may never be re-invoked — the work finishes but the report never comes, and the loop silently loses wall-clock until a human notices (observed failure shape: build done, tree dirty with finished artifacts, coder idle with no active task). Two rules close this: + +- **Coder briefs forbid stop-and-wait.** Render into every coder brief: never end your turn to wait on a background command or watcher you armed; poll it within the turn (background execution + in-turn checks) or finish the verifiable part and report. If a wait is unavoidable, say so in the report — handing the wait BACK to the tech-lead — instead of going idle. +- **The tech-lead arms an independent watchdog** the moment long-running coder work starts: a periodic check (~5-min cadence; e.g. a Monitor loop) over observable progress signals — new commits, working-tree churn, live compiler/test processes — that raises a STALL after ~2 quiet cycles. On STALL, verify the state read-only (never mutate the coder's tree — TL-F8) and re-invoke the idle coder with a nudge restating exactly where to resume ("build appears done, no fix commit landed — proceed with verification steps X/Y, ignore if mid-work"). A false STALL during a legitimately quiet phase (e.g. a read-only review pass) costs one glance; a missed real stall costs hours. + +Treat the sub-agent's own resume mechanism as the primary wake signal and the watchdog as the fallback heartbeat — never as the only wake path. Under candyland this section is moot: the conductor owns process liveness natively. + ## Forbidden actions (TL-F#) These are checkable prohibitions, not aspirations. A single row fired = the loop is off-contract.