<!--
  scaffold: desk-cli.md
  bucket: work-management (Bucket 2)
  what belongs here: the read-only overview surface.
    - desk is READ-ONLY. Never edit through desk.
    - The four canonical verbs (overview, today, work, projects).
    - Filter flags.
    - When to reach for desk vs pa work / pa project.
-->

# desk CLI — read-only overview

## Contract

`desk` is **read-only**. It reads work items and project manifests from disk (source of truth) and prints filtered views. Never edit through desk. Writes go through `pa work` and `pa project`.

## Verbs

| Verb | Purpose |
|---|---|
| `desk overview` | Summary of all projects and in-flight work. Top-level "where does the estate stand". |
| `desk today` | What is active and needs attention today. |
| `desk work` | List active work items. Filters: `--mine`, `--theirs`, `--status`, `--project`, `--category`. |
| `desk projects` | List active projects. `--all` includes done/archived. |

Full flag reference: `desk --help`.

## Team-scoped project visibility

`projects/` in the operator repo can be materialised from more than one
team's library-sync transport (see w-2026-07-14-008). Without scoping, one
team's `desk projects` / `desk overview` / `desk today` shows every other
team's projects too — noise at best, confusing at worst.

- **Scoping key**: `project.executor`, falling back to `project.assignee`.
  Never `owner` — owner is a human name that can be shared across teams
  working for the same person under different agent identities.
- **Own-team is a set, not a single name**: in real estates `assignee`
  carries a mix of agent names (`"dave"`) and role names
  (`"system-architect"`) on projects belonging to the same team. Matching
  against `paName` alone would silently hide the role-assigned projects —
  including an operator's highest-priority ones. The effective set is
  `operator/config/preferences.json:teamIdentities` (string[]) when
  present, else `[paName]`. `paName` is **always** a member of the
  effective set even if `teamIdentities` omits it, so the local agent can
  never scope out its own directly-assigned projects via a config
  oversight.
- **Identity source**: `operator/config/preferences.json:paName` (plus the
  optional `teamIdentities` list) — the same `paName` field desk already
  uses for `desk work --mine`/`--theirs`.
- **Fail open**: a project with neither `executor` nor `assignee` set is
  always shown in the default scoped view. Hiding unclassified work
  silently is worse than a little noise.
- **Opt-in, not automatic**: scoping only activates when
  `operator/config/preferences.json` sets `"scopeProjectsToTeam": true`.
  With no config, behaviour is unchanged (show everything) — a package
  bump alone never starts hiding projects.
- **Overrides**: `--all-teams` bypasses scoping for one invocation;
  `--team <identity>` filters to exactly one identity's projects (strict —
  single identity, not the whole set, and no fail-open leak on the
  explicit-filter path). Both flags work on `desk projects`,
  `desk overview`, and `desk today`.
- Same rules apply to `pa project list` (shared logic lives in
  `@stravica-ai/engineering-pa-core/src/desk/team-scope.mjs`).

## When to reach for `desk`

- **On session boot** — as part of the briefing that greets the operator, `desk overview` is the summary source.
- **When the operator asks "what's in flight"** — `desk work` or `desk overview` depending on granularity wanted.
- **When you need to check state** — before dispatching new work, `desk work --status in-progress` shows what else is running.

## When NOT to reach for `desk`

- **Reading the actual JSON** — use `Read` on the work item / project.json for the full state. Desk projects a summary; the file is truth.
- **Writing state** — use `pa work` / `pa project`. Desk has no write verbs.

## Cache behaviour

`desk` reads from disk on every invocation. There is no cache. State is always current — but if you have just written a work item and desk doesn't show it, check the JSON is valid and the id pattern matches (`w-YYYY-MM-DD-NNN`).

## Related

- `pa work --help` / `pa project --help` — write-side.
- `work-items.md` / `projects.md` — the state model desk projects.