session-orchestrator 3.23.0 → 4.0.0

package/skills/session-end/references/session-summary-template.md

@@ -0,0 +1,62 @@
+# Phase 6: Session Summary Template
+
+> Sub-file of the session-end skill (#1157 — agentskills.io: SKILL.md core < 500 lines, procedure in `references/`). Extracted VERBATIM from `skills/session-end/SKILL.md`; `SKILL.md` keeps a one-line stub naming this phase and its gate condition.
+
+Present to the user:
+
+```
+## Session Summary
+
+### Completed
+- [x] Issue #N: [description] — [evidence: tests passing, files changed]
+- [x] Issue #M: [description]
+
+### Carried Over
+- [ ] Issue #P: [what's left] — new issue #Q created
+- [ ] [description] — blocked by [reason]
+
+### Dropped at Handover Gate (deselected in triage — origin issue left open) [#769]
+- [ ] [middle-band item] — origin #<IID> — reason: [operator deselected in Phase 1.65 triage; no [Carryover] duplicate filed]
+
+### New Issues Created
+- #R: [title] (priority: [X], status: ready)
+- #S: [title] (priority: [X], status: ready)
+
+### Unresolved Review Findings (MED/LOW — recorded, not ticketed) [#617]
+- [MED] <finding> — <file:line> — <why deferred / fold decision>
+- [LOW] <finding> — <file:line>
+
+### Metrics
+- Duration: [total wall-clock time]
+- Waves: [N completed]
+- Agents: [total dispatched] ([X complete, Y partial, Z failed])
+- Files changed: [N]
+- Per-wave breakdown:
+  - Wave 1 (Discovery): [duration] — [N agents] — [K files]
+  - Wave 2 (Impl-Core): [duration] — [N agents] — [K files]
+  - ...
+- Tests: [passing/total] · Δ this session: +[added] / −[removed] / ~[consolidated] · tests:src LOC ratio [x.xx] (advisory ceiling 1.60)
+- TypeScript: 0 errors
+- Commits: [N] pushed to [branch]
+- Mirror: [synced/skipped]
+- Docs Health: Vault staleness — [render one of the three cases below based on Phase 2.3 result]
+  - Findings present (warn mode): `[N stale projects, M stale narratives] (mode=warn). See .orchestrator/metrics/vault-staleness.jsonl.`
+  - Skipped (disabled or mode=off): `skipped (disabled | mode=off).`
+  - Clean run: `clean (mode=<mode>).`
+- Custom Phases: [render based on Phase 2.5 result — omit the line entirely if `custom-phases` was absent/empty]
+  - Per phase: `<name>: <pass|FAIL> (exit <code>, mode=<mode>)[ — review: <path>]`
+  - None ran (all filtered out by `when`): `none applicable for session-type=<type>.`
+- Enforcement: [N violations blocked / M warnings] (or "N/A" if enforcement off)
+- Circuit breaker: [N agents hit limits, M spirals detected] (or "none")
+- Metrics written to: `.orchestrator/metrics/sessions.jsonl`
+- Learnings: [N] new, [M] confirmed, [K] contradicted/expired — written to `.orchestrator/metrics/learnings.jsonl`
+
+### Next Session Recommendations
+- Priority: [what should be tackled next]
+- Type: [housekeeping/feature/deep recommended]
+- Notes: [any context for next session]
+```
+
+> **Test-delta anchor:** the `Δ this session` figures are aggregated from the `test_delta` field of this session's agent reports (added / removed / consolidated test cases); the `tests:src LOC ratio` is `wc -l` over `tests/` divided by `wc -l` over `scripts/` + `hooks/`. A bare `passing/total` count is not a progress signal — a growing suite reads as progress even when the growth is redundant, which is exactly why the delta and the ratio are reported alongside it. When the ratio exceeds the advisory ceiling, recommend that the NEXT session's Quality wave run as a **consolidation wave**: no new test lands without a redundant one being removed in the same change. This is advisory only — it never blocks the close.
+
+> **Documentation Coverage anchor:** If Phase 3.2 ran and produced task verification results (i.e. `docs-orchestrator.enabled: true` and `docs-tasks` were found), the results appear here as a `### Documentation Coverage (docs-orchestrator)` subsection emitted by Phase 3.2 Step 7. The content is written dynamically — it is not pre-populated in this template. When `docs-orchestrator.enabled` is `false` or `docs-tasks` were absent, this subsection is omitted entirely.

package/skills/session-plan/SKILL.md

@@ -333,6 +333,23 @@ Map roles to the configured wave count:
 | 4 | W1=Discovery, W2=Impl-Core+Impl-Polish, W3=Quality, W4=Finalization |
 | 5 | W1=Discovery, W2=Impl-Core, W3=Impl-Polish, W4=Quality, W5=Finalization |
 | 6+ | W1=Discovery, W2-W3=Impl-Core (split), W4-W5=Impl-Polish (split), W6=Quality+Finalization |
+| 7 + `session-profile: ultradeep` | W1=Research+Code-Discovery, W2=Synthesis-Gate (`coordinator-direct: true`, `agents: 0`), W3=Impl-Core, W4=Impl-Polish, W5=Review-Panel, W6=Quality, W7=Release/Finalization |
+
+The last row applies ONLY when STATE.md frontmatter carries `session-profile: ultradeep` (written by the `/session ultradeep` argument alias — see `commands/session.md`). `session-type` stays `deep`; the profile changes the wave SHAPE, nothing else. Without the profile, `waves: 7` falls back to the `6+` row. Spec: `docs/prd/2026-09-06-ultradeep-session-profile.md` § 5.
+
+**Ultradeep agent counts per wave** (caps, not targets — the Quality cap is still EARNED per the Step 3 rule):
+
+| W | Role | Agents | Writes? |
+|---|------|--------|---------|
+| 1 | Research + Code-Discovery | ≤ 18 (separately scoped) | No (read-only) |
+| 2 | Synthesis-Gate | 0 (coordinator-direct) | Coordinator only: audit report, STATE.md, plan |
+| 3 | Impl-Core | ≤ 8 | Yes |
+| 4 | Impl-Polish | ≤ 8 | Yes |
+| 5 | Review-Panel | 3 (read-only) | No |
+| 6 | Quality | `min(cap, ceil((HIGH+MED)/3))` | Tests only |
+| 7 | Release/Finalization | ≤ 4 | Yes |
+
+Wave 1 splits into two disjointly-scoped groups: **Research** agents (web-enabled, see `skills/wave-executor/SKILL.md` § Ultradeep Profile) and **Code-Discovery** agents (repo-only). Both are read-only. Wave 2 dispatches NO agents — the coordinator consolidates wave 1, writes `docs/audits/<YYYY-MM-DD>-<slug>.md`, and asks ONE blocking `AskUserQuestion` before wave 3.
 
 When roles are combined into a single wave, agents from both roles execute in that wave. The combined wave inherits the more restrictive verification level.
 
@@ -356,6 +373,20 @@ When `docs-orchestrator.enabled: true`, apply the following concrete dispatch ru
 
 **Empty roles:** If a role has 0 tasks, skip its wave entirely. Do NOT dispatch an empty wave. Remaining waves retain their original role names but are renumbered sequentially (e.g., if Discovery has 0 tasks and waves=5: W1=Impl-Core, W2=Impl-Polish, W3=Quality, W4=Finalization). Update `total-waves` in the plan output to reflect the actual wave count.
 
+**Exception — a wave declared `coordinator-direct: true` is NEVER removed by the empty-role rule.** The rule's premise is "0 tasks means nothing to dispatch, so the wave is dead weight". For a coordinator-direct wave that premise is inverted: dispatching zero agents is the wave's PURPOSE, not evidence of its emptiness. Its plan item therefore carries BOTH markers and is emitted verbatim:
+
+```
+- wave: 2
+  role: Synthesis-Gate
+  coordinator-direct: true
+  agents: 0
+```
+
+- `agents: 0` on such an item is a DECLARATION, never a defect — do not "fix" it upward, and do not let the Step 3.5 constraint check or the Step 3 tier table raise it.
+- The wave still counts toward `total-waves` and still occupies its wave number; the renumbering above skips over it, it does not absorb it.
+- The ultradeep Synthesis-Gate (wave 2) is the only such wave today. Without this exception the empty-role rule deletes it — and it is the one wave whose entire job is to stop and ask before any code is written (`docs/prd/2026-09-06-ultradeep-session-profile.md` AC-4).
+- The exception is scoped to the MARKER, not to the profile: any future coordinator-direct wave inherits it without another edit here.
+
 ### Role Details
 
 **Discovery**
@@ -531,6 +562,24 @@ Present the plan in this format:
 Ready to execute? Use /go to begin.
 ```
 
+### Step 6.5: Heartbeat on the operator's answer (#1229)
+
+The wait between presenting this plan and the operator's answer is the LONGEST unheartbeated stretch in the whole flow — the coordinator can sit on it for hours, and a 4 h-TTL lock does not survive that. Measured: session-20's lock was reaped as stale by an unrelated SessionEnd with an 11.3 h-old heartbeat (STATE.md deviation 2026-09-05T06:08:46Z). `hooks/on-session-start.mjs` covers session entry; this is the second call site.
+
+**The FIRST thing to do when the operator answers** — whether the answer is `/go` or a change request routing to Step 7 — is refresh the lock:
+
+```js
+// #1229 — the plan-approval wait is the longest unheartbeated stretch in the flow.
+// Best-effort: a failure must NOT block the handoff to wave-executor.
+import { updateHeartbeat } from 'scripts/lib/session-lock.mjs';
+updateHeartbeat({ sessionId, repoRoot: process.cwd() });
+```
+
+- **Ownership-guarded — this cannot steal a peer's lock.** `updateHeartbeat` (`scripts/lib/session-lock.mjs`) reads the lock first and returns `false` WITHOUT writing when `session_id` differs from the one passed, when no lock exists, or when `sessionId` is empty. The write is reached only for a lock this session already owns.
+- **What it does not do:** nothing can beat while a blocking AskUserQuestion is pending, so the wait window itself stays unheartbeated. What this closes is the session RESUMING with an hours-stale heartbeat and carrying it into wave 1 and every later reaper pass.
+- `sessionId` is the identifier session-start Phase 1.2 `acquire()` established — the `session_id` field of `.orchestrator/session.lock`, matching STATE.md frontmatter `session:`.
+- Skip silently when `persistence: false` in Session Config — no `session.lock` exists in that mode.
+
 ## Step 7: Handle Plan Changes
 
 If the user requests changes: