# Workspace kit session snapshot (agents)

**Audience:** automated agents. **Do not** treat `docs/maintainers/ROADMAP.md` or `docs/maintainers/data/workspace-kit-status.yaml` as required reading for routine work.

## Maintainer delivery (before you commit)

When implementing scoped **`T###`** work: **branch from `release/phase-<N>`** (or the current phase integration branch), run **`run-transition`** **`start`** **no later than the first implementation commit** on that task branch, then **PR → review → merge** into the phase branch. Do not treat “code is done” as enough without the GitHub + **`run-transition`** **`complete`** evidence path — **`.ai/playbooks/task-to-phase-branch.md`**, **`.cursor/rules/maintainer-delivery-loop.mdc`**.

**Machine hints:** **`get-next-actions`**, **`agent-session-snapshot`**, and **`agent-bootstrap`** include **`maintainerDelivery`** (playbook paths, suggested `release/phase-<key>` branch, **`inProgressTasks`**, optional metadata on the suggested task). When effective config is available, the same readouts add compact **`resolvedPolicySuggestedNext`** / **`resolvedPolicyInProgress`** (from **`resolve-maintainer-delivery-policy`**) and **`taskIntakeSuggestedNext`** / optional **`taskIntakeProposedHeadlines`** (from **`resolve-task-intake-policy`**) so agents do not need to open raw config for defaults. **`list-tasks`** can add **`taskIntakeByTaskId`** when **`includeTaskIntake:true`**. **`pnpm exec wk doctor --delivery-loop`** prints an advisory when the working tree is **dirty** on **`main` / `master` / `release/phase-<n>`** while execution tasks are **`in_progress`**; **`--delivery-loop-strict`** fails **`doctor`** instead.

**Optional task metadata** (for agents / reporting): **`metadata.maintainerDeliveryProfile`** (string, e.g. **`github-pr`**) and **`metadata.requiresPhaseBranch`** (boolean). They are echoed inside **`maintainerDelivery`** when present.

## Refresh execution context

These refresh steps assume this source checkout or an already-attached workspace. In an **attached project**, the canonical command is **`./.workspace-kit/bin/wk`**; it uses **`.workspace-kit/runtime.json`** and does not require a preceding `nvm use`. In this **Workflow Cannon source checkout**, `pnpm exec wk` (or `node dist/cli.js` from a built tree) remains valid for package development. For a **net-new consumer attach**, install the package and run **`pnpm exec wk init --dry-run --json`**, then **`pnpm exec wk init`** with `WORKSPACE_KIT_POLICY_APPROVAL`, then **`./.workspace-kit/bin/wk start`**; do not treat `doctor` as the first command before `init` in an uninitialized project.

1. Run `./.workspace-kit/bin/wk doctor` from an attached project root (or `pnpm exec wk doctor` / `node dist/cli.js doctor` in this source checkout). Machine **JSON** for the default contract check: **`./.workspace-kit/bin/wk doctor --json`** (or **`--format json`**). For the **machine-readable instruction catalog** (executable vs documentation-only commands, remediation codes), run `./.workspace-kit/bin/wk doctor --agent-instruction-surface` and keep the JSON output handy before relying on a bare `wk run` text menu. For a **digest-only** catalog (compare `instructionSurfaceDigest` to a cached full payload), use `./.workspace-kit/bin/wk doctor --agent-instruction-surface-lean` or add **`--agent-instruction-surface-lean`** alongside the base flag.
2. For a **single argv cold start** (doctor-equivalent contract checks **plus** the composed session bundle), run **`./.workspace-kit/bin/wk run agent-bootstrap '{}'`** (read-only; includes `planningGeneration`, `suggestedNext`, queue health, phase hints). Use **`./.workspace-kit/bin/wk run agent-bootstrap '{"projection":"lean"}'`** to also attach the **lean** instruction-surface digest (same shape as doctor lean). Otherwise use **`./.workspace-kit/bin/wk run agent-session-snapshot '{}'`** alone when doctor was already run separately, or `./.workspace-kit/bin/wk run get-next-actions '{}'` plus `./.workspace-kit/bin/wk run list-tasks '<json-filter>'` for granular reads.
3. **Per-command argv JSON Schema + samples** (generated, CI-checked): see `.ai/agent-cli-snippets/INDEX.json` and `by-command/*.json` — prefer loading one command’s snippet over pasting in the entire `.ai/AGENT-CLI-MAP.extended.md`. **Runnable command list (machine):** `./.workspace-kit/bin/wk run --json` (no subcommand) — stable `commands[]` with policy hints; default bare `wk run` remains human text.
4. For **Tier A / Tier B** mutating `wk run` commands, use **`./.workspace-kit/bin/wk run <cmd> --schema-only`** first, edit the emitted **`sampleArgs`**, then add JSON **`policyApproval`** when required — see `.ai/machine-cli-policy.md` tier table.
5. **Glossary + routing hubs:** machine term index for **`.ai/TERMS.md`** → **`.ai/TERMS.index.json`** (regenerate: `node scripts/generate-terms-index.mjs`; CI `terms-index` stage). The **`term|name=sprint|…`** row lists machine synonyms for bounded phase execution slices (dashboard copy). Subtree entrypoints for agents → **`HUB.md`**: **`.ai/cae/README.md`**, **`.ai/runbooks/README.md`**, **`.ai/adrs/README.md`**.
6. Task queue reads: **`list-tasks`** supports **`id`** / **`ids`** / **`idPrefix`**, plus **`limit`** + opaque **`nextCursor`** pagination (stable sort: `updatedAt` desc, numeric `T###` tie-break). **`create-task`** supports **`allocateId:true`** (omit **`id`**) and **`dryRun:true`**. **`apply-task-batch`** runs multiple **`create-task`** / **`update-task`** shapes in one transaction; **`update-task`** also accepts **`dryRun:true`**.
7. Treat **`workspace-kit run`** + the configured task store as authoritative for `status`, `id`, and queue ordering. Runtime reads/writes use SQLite **`.workspace-kit/tasks/workspace-kit.db`** (legacy `.workspace-kit/tasks/state.json` is **import/migrate only**). When **`tasks.canonicalAuthority`** is **`git-event-log`**, canonical history is branch **`workflow-cannon/task-state`** — routine flow is local-first + background outbox sync; **manual `task-sync-hydrate` / `task-sync-publish` are recovery/admin paths only**. Do not commit the `.db` on closeout — **`.ai/runbooks/task-state-git-operator.md`**, phase closeout **§3a** in **`.ai/playbooks/phase-closeout-and-release.md`**.

**Workspace phase snapshot:** canonical **`current_kit_phase` / `next_kit_phase`** for kit readers live in **`kit_workspace_status`** (planning SQLite, **`user_version` ≥ 10**). Use **`workspace-kit run phase-status '{}'`** to read phase, drift, export freshness, and optional task counts. Use **`workspace-kit run set-current-phase ...`** for the SQLite-first happy-path phase mutation; **`update-workspace-phase-snapshot`** and **`update-workspace-status`** are compatibility / low-level surfaces. **`kit.currentPhaseNumber`** is a **bootstrap / UX hint** only — it does **not** override the DB row; **`doctor`** may note drift but does not fail on config vs DB mismatch (see **`.ai/runbooks/workspace-status-sqlite.md`**). Per-task **`phaseKey`** in the task store is separate from this snapshot.

## Humans vs agents

- **Maintainers** edit long-form strategy in `docs/maintainers/ROADMAP.md`, `docs/maintainers/CHANGELOG.md`, and the status YAML snapshot under `docs/maintainers/data/`.
- **Agents** use this file, `.ai/AGENTS.md`, `.ai/machine-cli-policy.md`, `.ai/MACHINE-PLAYBOOKS.md`, `src/modules/*/instructions/*.md`, and CLI JSON output—not `docs/maintainers/*` prose—for operating procedures.
