recodeee · NagyVikt · Apr 23, 2026 · Apr 23, 2026
@@ -0,0 +1,16 @@
+## Why
+
+The VS Code Active Agents panel already exposes working-state groups, lock state, inspect actions, and session-owned changes, but the main tree is still optimized for filesystem grouping instead of operator triage. When several lanes are active at once, the user still has to drill through worktree grouping and raw change trees before they can answer the high-value questions: who is active now, what task each lane owns, what changed recently, what is risky, and which repo drift is unassigned.
+
+## What Changes
+
+- Replace the primary repo view with a task-first operator layout: `Overview`, `Working now`, `Idle / thinking`, `Unassigned changes`, and `Advanced details`.
+- Render active sessions as compact task rows that prioritize task title, agent, state, changed-file count, lock count, freshness, recent-change summary, and inline risk markers.
+- Move raw worktree/path trees behind a collapsed `Advanced details` section instead of using them as the default scan path.
+- Surface repo-level overview counts for working lanes, idle lanes, unassigned changes, locked files, and conflicts.
+- Update the focused Active Agents tests and extension manifests for the new layout contract.
+
+## Impact
+
+- Affected surfaces: `vscode/guardex-active-agents/*`, `templates/vscode/guardex-active-agents/*`, `test/vscode-active-agents-session-state.test.js`, and this change workspace.
+- No session-file schema or launcher contract changes; the panel still reads the existing Active Agents, lock-registry, and inspect data.
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Active Agents defaults to an operator-first task layout
+The VS Code Active Agents companion SHALL prioritize active task ownership and risk scanning over raw worktree and folder completeness.
+
+#### Scenario: Repo view shows task-first operator sections
+- **WHEN** a repo has one or more visible Guardex sessions
+- **THEN** the repo view contains an `Overview` section
+- **AND** it contains a `Working now` section above `Idle / thinking`
+- **AND** it contains an `Unassigned changes` section when repo drift is not clearly owned by a live session
+- **AND** it keeps raw worktree/path trees under a collapsed `Advanced details` section rather than as the default primary view.
+
+### Requirement: Session rows summarize work and risk inline
+The VS Code Active Agents companion SHALL render each session row as a compact task-first summary instead of leading with branch or folder grouping.
+
+#### Scenario: Working row answers operator triage questions
+- **WHEN** a session appears in `Working now` or `Idle / thinking`
+- **THEN** its primary label is the task title or best available task summary
+- **AND** its row description includes the agent name, session state, changed-file count when present, lock count when present, and a human-readable freshness label
+- **AND** expanding the row reveals recent-change summary, top changed files, and branch/worktree details
+- **AND** conflicts, stale state, lock ownership, or refresh deltas appear inline or in the expanded summary without requiring the raw path tree first.
+
+### Requirement: Repo overview summarizes actionable counts
+The VS Code Active Agents companion SHALL expose repo-level counts for high-value operator decisions.
+
+#### Scenario: Overview row reports working, idle, unassigned, locked, and conflict counts
+- **WHEN** the provider refreshes a repo entry
+- **THEN** the overview surface reports working-agent count, idle-agent count, unassigned-change count, locked-file count, and conflict count
+- **AND** the repo row and badge tooltip reuse those counts instead of only reporting active/dead totals.
@@ -0,0 +1,33 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+Handoff: 2026-04-23 12:29Z codex owns `vscode/guardex-active-agents/*`, `templates/vscode/guardex-active-agents/*`, `test/vscode-active-agents-session-state.test.js`, and this change workspace to ship a task-first Active Agents panel layout for dense multi-agent repo triage.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-active-agents-task-first-layout-2026-04-23-12-29`.
+- [x] 1.2 Define normative requirements in `specs/vscode-active-agents-task-first-layout/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Replace the default repo tree with task-first operator sections for overview, working now, idle / thinking, unassigned changes, and advanced details.
+- [x] 2.2 Render session rows as compact task cards with task title, agent, state, file/lock counts, freshness, recent-change detail, and inline risk summaries.
+- [x] 2.3 Keep raw path/tree detail behind collapsed advanced disclosure and update the focused tests plus mirrored template sources.
+- [x] 2.4 Bump the live/template Active Agents manifest versions for the new shipped layout.
+
+## 3. Verification
+
+- [x] 3.1 Run `node --test test/vscode-active-agents-session-state.test.js`.
+- [x] 3.2 Run `openspec validate agent-codex-active-agents-task-first-layout-2026-04-23-12-29 --type change --strict`.
+- [x] 3.3 Run `openspec validate --specs`.
+
+## 4. Cleanup
+
+- [ ] 4.1 Run `gx branch finish --branch "agent/codex/active-agents-task-first-layout-2026-04-23-12-29" --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).