Files

gsxdsm dff864e098 feat: harden permanent-agent heartbeat instructions (#2081 )

## Summary

Hardens permanent-agent operating law while keeping the
heartbeat/executor split:

- **Critical Rules** in task-scoped and no-task heartbeat system prompts
(survive custom `HEARTBEAT.md`)
- Stronger default procedures: disposition checklist, scoped-wake,
blocked dedup, progress note style
- **Wake Delta multi-assign inventory** (ranked, cap 8,
coordination-only framing) + `checkout_conflict` regression test
- Standing instructions six-section template for blank custom create /
empty detail insert
- Onboarding interview guidance to prefer structured `instructionsText`
- Playbooks, CONCEPTS, agents.md accuracy; remove stale agent
gap-analysis doc

Plan:
`docs/plans/2026-07-12-001-feat-permanent-agent-heartbeat-instructions-plan.md`

## Test plan

- [x] `pnpm --filter @fusion/core exec vitest run
src/__tests__/assigned-task-ranking.test.ts`
- [x] `pnpm --filter @fusion/engine exec vitest run
src/__tests__/agent-heartbeat-procedures.test.ts
src/__tests__/heartbeat-executor.test.ts -u`
- [x] `pnpm --filter @fusion/dashboard exec vitest run
app/components/__tests__/standing-instructions-template.test.ts`
- [ ] CI gate green on PR

## Residual Review Findings

None recorded at open (inline review; no residual sink).

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added ranked multi-assignment context to agent heartbeat wake-ups,
including task status, ownership, and lease details.
* Added standing-instructions templates for creating and editing
permanent agents.
* Improved onboarding guidance with a consistent six-section instruction
structure.
* Added clearer heartbeat handling for blocked tasks, no-task runs, and
checkout conflicts.

* **Documentation**
* Added permanent-agent heartbeat playbooks and expanded coordination
glossary entries.
  * Updated documentation indexes and heartbeat behavior guidance.

* **Tests**
* Added coverage for task ranking, instruction templates, wake-up
context, and conflict handling.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

2026-07-14 08:23:11 -07:00

2.6 KiB

Raw Blame History

Permanent Agent Heartbeat Playbooks

← Agents

Operator and implementer playbooks for durable (permanent) agent heartbeats. Heartbeats are coordination windows; task-body implementation runs on the executor path.

Mental model

Wake (timer / assignment / message / on-demand)
Identity + Wake Delta + procedure
One concrete coordination action
Disposition + fn_heartbeat_done

Do not implement code, run tests, or commit from a default strict heartbeat.

Playbook: Manager health tick

Process inbox / room notices first.
Read reports-health (if present) for stale direct reports.
Pick one: reassign blocked child, message an idle specialist, or create a focused follow-up.
Log outcome with next owner; fn_heartbeat_done.

Playbook: Message / comment wake

Acknowledge the wake payload (message id or comment).
If one clear action: reply / create / delegate — then exit (scoped-wake).
Do not open a multi-step investigation in the same tick.

Playbook: Bound task is executor-class or blocked

Do not re-read PROMPT.md to implement.
Skim for blocker risk; pivot to board signals (stale in-review, idle reports, memory themes).
Blocked dedup: if the same blocker was already logged and nothing new arrived → no-op with reason.

Playbook: No-task ambient run

Inbox first.
Prefer auto-claim candidates only when policy allows and role matches.
Create or delegate one focused task; never unscheduled implementation with ambient tools alone.

Playbook: Multi-assign inventory in Wake Delta

When Wake Delta lists “your assigned tasks (coordination inventory…)”:

Use it to unblock, reassign, or prioritize — not to code.
Bound line (assigned task: FN-…) remains the singular execution bind.
Foreign lease: held-by-other → do not retry checkout this tick.

Playbook: Empty wake / nothing to do

Explicit no-op with reason is success:

fn_heartbeat_done summary: "No new inbox or wake delta; no open coordination lever; no-op."

Anti-patterns

Avoid	Prefer
Implement / test / commit in heartbeat	Executor path / create task
Re-comment same blocker every tick	Blocked dedup no-op
Retry checkout on conflict	Exit / other work
Pause task on failure	Log + create/delegate follow-up
Duplicate `fn_task_create` without scan	Scan open tasks first
Self-only “please review” with no real review path	Explicit reviewer / `in-review` handoff

Composition and settings: Agents
Domain vocabulary: CONCEPTS.md

2.6 KiB Raw Blame History