hera skill: correct plan-DAG gating docs, fan-in footgun, short-id naming, load-before-planning front-matter

[anutron]

Why

A hera coordinator handed a multi-stage feature build authored a plan-DAG straight from the hera_* MCP tool schemas and improvised an incorrect mental model of how the plan-DAG works. Its self-reported reasoning made two factual claims that are wrong, verified against internal/heragater/heragater.go:

• "Planned nodes auto-spawn when a blocker goes idle." Actually the gater materializes a node only when every blocker reaches hera role-status done (the worker's explicit finish, which rolls its task to in_review). Idle-without-done keeps the node planned; a blocker whose session ended without done holds the dependent and pings the coordinator. It never spawns on mere idle.
• "Nodes land on the project default branch." Actually non-root nodes stack on the most-recently-done blocker's branch (resolveBaseBranch); only root nodes fall back to the project default.

Both were already documented correctly in the skill body — the coordinator simply never loaded it, because skills are progressively disclosed (only the front-matter description is in context until the Skill tool loads the body) and the old description neither directed the agent to load the body before planning nor hinted that the plan-DAG mechanics are non-obvious.

What changed (docs only — .claude/skills/hera/SKILL.md)

• Front-matter now directs: LOAD AND READ THIS SKILL IN FULL before authoring or driving any multi-stage / multi-worker plan, and names what is non-obvious (gating on role-status done, branch-stacking, short-id naming, living reconciliation) so the agent doesn't improvise from the tool schemas.
• Fan-in branch footgun: a node with multiple blockers bases off the single most-recently-done blocker's branch — it does not merge the others. Documented in §3, the worked example, and as a gotcha.
• done ≠ merged/integrated: the gater materializes a dependent the instant its blocker reports done, ahead of the coordinator's review/merge.
• Self-rebase + self-guard prompt patterns documented as the standard mitigation for stacked-integration and contract-discovery work.
• <stage><member> short-id naming elevated from a buried parameter note to a rationale-bearing rule: descriptive node names blow the rail/DAG boxes wide and wreck legibility at scale; 1a/2a ids keep it tight.

Scope / risk

Documentation only. No Go code, no CI wiring, no spec deltas — make pre-pr is unaffected. The branch carries exactly the two skill commits, cut clean off master (not the broader bug-bash branch they originated on).

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[anutron]

Recast: this PR now delivers a two-skill split (3rd commit 70cd95c), superseding the original single-file scope.

The earlier "load before any multi-stage plan" front-matter was too strong — it read as "use the plan-DAG for any multi-stage plan" and discouraged in-process Claude sub-agents for in-session work. Restructured instead:

• New .claude/skills/hera-plan/SKILL.md (on-demand): the full plan-DAG surface — authoring/mutation verbs, gating-on-done, branch-stacking + fan-in footgun, short-id naming, sub-coordinator nodes, self-guard prompt patterns, worked example. The body fixes from the first two commits live here.
• Base hera/SKILL.md slimmed: plan-DAG detail → a pointer to hera-plan; front-matter softened to role / multi-session triggers (no "any plan" over-reach); new §4 decision triad — in-session sub-agents → hera workers → plan-DAG, auto-deciding the plan-DAG when the multi-session units have dependencies among them, asking the human only when multi-session-ness itself is ambiguous.
• claude/snippets/hera.md (always-loaded): role-aware loader ("spawned as a worker / hold-or-creating a coordinator binding → load the hera skill") + the same triad + dependency trigger. This is the reliable always-in-context lever; a skill can't self-load.
• README mentions hera-plan (the installer enumerates .claude/skills/* dynamically, so it auto-installs).

Docs-only; make pre-pr unaffected. The PR title is now slightly narrow — happy to retitle to "Split hera skill into base + hera-plan" if preferred.