diff --git a/.wiki/concepts/using-system-snapshot-design.md b/.wiki/concepts/using-system-snapshot-design.md new file mode 100644 index 0000000..d188a5e --- /dev/null +++ b/.wiki/concepts/using-system-snapshot-design.md @@ -0,0 +1,59 @@ +--- +title: using-system-snapshot skill design +type: concept +updated: 2026-06-09 +--- + +# using-system-snapshot skill design + +New policy+technique skill (v0.1.0) wrapping the single MCP call +`mcp__projects-meta__meta_system_snapshot`. Replaces the old scatter of +`tasklist` + `docker ps` + a manual `meta_status` read with one round-trip for +session-start ops orientation. + +## Why a skill + +The failure mode it guards: an agent asserts "the poller is running" / "all +containers are up" / "you have N active tasks" from memory or a stale earlier +snapshot, without re-checking. The skill makes the rule explicit — **no claim +about poller / local-docker / task-load state without calling the tool in the +current turn**. Mirrors the read-only, no-grant posture of [[using-vds-ops]]. + +## Tool output shape (verified live 2026-06-09) + +Three keys: + +- `poller`: `{ running: bool, projects: "" }` — **live**. +- `docker`: `[{ name, status }]` — **local** machine containers (includes + `agents-task-runner-*`), NOT the VDS. Status strings like `Up 4 hours`, + `Up 26 hours (healthy)`; problems show as `Restarting` / `Exited` / + `(unhealthy)` / `Created` / `Paused`. **live**. +- `tasks`: `{ "/": { active, blocked } }` — **from the + projects-meta cache**, so approximate. + +## Design decisions + +- **Output = three lines, one per section** (per task spec). Docker line reports + `N/N up` when all healthy, else lists only the bad containers; tasks line gives + Σ active / Σ blocked + the busiest 2–3 projects. Never dump raw JSON. +- **Liveness split made explicit.** Poller + docker are read at call time; task + counts come from the cache. The skill tells the agent to flag task-count + staleness and defer precise per-task work to [[projects-meta-skills]] + (`using-projects-meta` Step 0 freshness gate, or local `.tasks/` on disk). +- **Scope boundaries.** Deep single-container diagnosis (logs/inspect/stats) is + explicitly out — that's [[using-vds-ops]] for the VDS or `docker logs` + locally. The snapshot only carries name + status. +- **Read-only, no per-session grant** — same as [[using-vds-ops]]. The tool + takes no args; no preview/confirm dance (unlike the projects-meta mutations). + +## Prerequisites + +Needs `mcp__projects-meta__meta_system_snapshot` (shipped by `projects-meta-mcp`; +the `meta-system-snapshot` capability lives in `OpeItcLoc03/common`). If the tool +is absent, the server isn't registered → `setup-projects-meta`. + +## TDD note + +Markdown policy artifact — no code/test surface (consistent with sibling skill +tasks). Behavioral trigger smoke-test is the paired `skill-using-system-snapshot-review` +task, not this implementation task. diff --git a/.wiki/index.md b/.wiki/index.md index 4b26961..265343d 100644 --- a/.wiki/index.md +++ b/.wiki/index.md @@ -43,6 +43,7 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever - [session-handoff-skill-design.md](concepts/session-handoff-skill-design.md) — design rationale for the `session-handoff` skill (sliding overwrite into `.tasks/NEXT_SESSION.md`, phrase whitelist + substantive-commit heuristic, optional PostToolUse hook for harness-side determinism, orient+ask default, project scope, cluster 7/7 closure) - [using-tasks-session-break.md](concepts/using-tasks-session-break.md) — `using-tasks` v1.2.0 `session_break` marker: task-author-set boolean/string flag; after a task closes 🟢, before `tasks_claim_next`, an autonomous agent prints the verbatim SESSION BOUNDARY line and stops instead of chaining the next task. Absent → unchanged - [delegate-task-session-break.md](concepts/delegate-task-session-break.md) — `delegate-task` v0.2.2 — authoring side of the `session_break` marker (consumer = [[using-tasks-session-break]]): pre-flight Q6 + optional template field `session_break: true | ""`; three set-it cases (domain-switch / milestone / heavy infra); not a default +- [using-system-snapshot-design.md](concepts/using-system-snapshot-design.md) — `using-system-snapshot` v0.1.0 — thin read-only skill wrapping the single `mcp__projects-meta__meta_system_snapshot` call (poller + local docker + cached task summary); replaces scattered `tasklist`/`docker ps`/manual `meta_status`; core rule = no liveness claim without calling the tool this turn; three-line output; defers deep docker to [[using-vds-ops]] and precise tasks to [[using-projects-meta]] - [delegate-task-negative-trigger-fp.md](concepts/delegate-task-negative-trigger-fp.md) — `delegate-task` v0.2.1 FP fix: «создать задачу себе» stem-matched the «создать задачу на агента» positive trigger; abstract "does NOT apply when doing the work yourself" carve-out loses to literal stem-match under the 1%-rule → made the negative literal + routed (→ using-tasks). Verified pos 5/5, neg 4/5 (was 0/5) ## Packages diff --git a/.wiki/log.md b/.wiki/log.md index ee9f6d6..0b76d82 100644 --- a/.wiki/log.md +++ b/.wiki/log.md @@ -68,4 +68,5 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`. ## [2026-06-09] decision | delegate-task-negative-trigger-fp — `delegate-task` 0.2.0→0.2.1 (PATCH): fixed 5/5-consistent false-positive on «создать задачу себе». Root cause: self-task phrase shares stem «создать задачу» with the «создать задачу на агента» positive trigger; the abstract "Does NOT apply when doing the work yourself" carve-out can't beat a literal stem-match under the 1%-rule. Fix: made the negative literal + routed («создать задачу себе» / «task for myself» / «поставить себе задачу» → using-tasks) in description + body disambiguator («на агента»/«агенту» = delegate; «себе» = own board). Re-verified via fresh-context subagent trigger run: positives 5/5 (no regression), negative 4/5 → using-tasks (was 0/5); the 1 residual miss was an eval-harness artifact (forced skill-name-before-reasoning), not description ambiguity. Concept page written; reusable principle = put the exact colliding negative phrase with an explicit →sibling route, literal beats abstract. ## [2026-06-09] decision | delegate-task-session-break — `delegate-task` 0.2.1→0.2.2 (PATCH): authoring side of the `session_break` marker (consumer = using-tasks v1.2.0). Added pre-flight Q6 (after notify): "Session-break после этой задачи? (domain-switch / milestone / heavy infra)"; if yes → set optional template field `session_break: true | ""` (trailer, next to weight/notify/allow_upgrade; same lowercase frontmatter key using-tasks reads). Usage guidance lists three set-it cases; What-NOT-to-do bullet warns against setting it routinely (it's a real-boundary marker, not a default). Wiki concept page concepts/delegate-task-session-break.md + index. Pairs with using-tasks-session-break. +## [2026-06-09] decision | using-system-snapshot — new skill v0.1.0: thin read-only wrapper over the single `mcp__projects-meta__meta_system_snapshot` call (poller status + local docker containers + cached cross-project task summary). Replaces the scatter of `tasklist` + `docker ps` + manual `meta_status`. Core rule: no claim about poller / local-docker / task-load state without calling the tool in the current turn (memory + stale earlier snapshot ≠ evidence). Output = three lines, one per section (docker lists only problem containers; tasks gives Σ active/blocked + busiest 2–3). Liveness split documented: poller+docker live, tasks from cache (defer precise work to using-projects-meta Step 0). Scope boundaries: deep single-container diagnosis → using-vds-ops / `docker logs`; docker section is LOCAL, not the VDS. Read-only, no per-session grant (mirrors using-vds-ops). Output shape verified by a live call 2026-06-09. Concept page concepts/using-system-snapshot-design.md + index. TDD N/A (markdown policy artifact); behavioral smoke-test = paired skill-using-system-snapshot-review task. ## [2026-06-09] decision | using-tasks-session-break — `using-tasks` 1.1.0→1.2.0 (MINOR): added the `session_break` marker. Task author sets `session_break: true | ""` in task frontmatter (mirrored as `**Session break:**` on the local board); after the task closes 🟢, before `tasks_claim_next`, an autonomous agent prints the verbatim line `🔚 SESSION BOUNDARY — [slug] закрыта. Рекомендую завершить текущую сессию. Следующий трек: [value | "см. STATUS.md"]` and stops instead of chaining the next task. Absent → behaviour unchanged. Enforced in Task completion step 6 + Rules bullet + format docs. Marker not heuristic: the stop-point is an authoring choice, not a runner guess. diff --git a/skills/using-system-snapshot/SKILL.md b/skills/using-system-snapshot/SKILL.md new file mode 100644 index 0000000..6676fc5 --- /dev/null +++ b/skills/using-system-snapshot/SKILL.md @@ -0,0 +1,77 @@ +--- +name: using-system-snapshot +version: 0.1.0 +description: "Use at the start of an ops-context session, and ALWAYS before asserting anything about the agent poller, local docker containers, or cross-project task load — call `mcp__projects-meta__meta_system_snapshot` instead of running `tasklist` / `docker ps` / `meta_status` by hand. Triggers on «что запущено», «что сейчас крутится», «состояние системы», «состояние машины», «поллер работает?», «поллер живой?», «что с докером», «сводка по задачам», «what's running», «system status», «system snapshot», «is the poller up», «is the runner alive», «what containers are up». Read-only — no per-session grant needed. Skip for deep single-container docker diagnosis (that's using-vds-ops for the VDS / docker logs locally) and for mutating or precise per-task work (that's using-projects-meta)." +--- + +# using-system-snapshot + +## Overview + +One call — `mcp__projects-meta__meta_system_snapshot` — returns a whole-machine ops snapshot: agent **poller** status, local **docker** containers, and a cross-project **task** summary (active / blocked counts) from the projects-meta cache. It replaces the old scatter of `tasklist`, `docker ps`, and a manual `meta_status` read with a single round-trip. + +**Core rule: never assert the state of the poller, local containers, or task load without calling this tool first.** Memory and "it was running earlier" are not evidence. + +## When to use + +- Session start in an **ops context** — orienting before doing infra / runner / task-board work. +- The user asks what's alive: «что запущено», «состояние системы», «поллер работает?», «что с докером», «what's running», «is the poller up». +- **Before any claim** about whether the poller is running, which projects it scans, whether a container is up/healthy, or how many tasks are active/blocked. +- A quick cross-project task-load glance ("where's the work concentrated right now"). + +## When NOT to use + +- Deep diagnosis of **one** container (logs, inspect, stats, restart-loops) — that's `using-vds-ops` for the Rusonyx VDS, or `docker logs` locally. The snapshot only gives name + status. +- **Mutating** task state, or reading the **full** board / a precise per-task body — that's `using-projects-meta` (and local `.tasks/` disk for the current project). +- Library docs, code search, single-file questions — unrelated. + +## Prerequisites + +Requires the tool `mcp__projects-meta__meta_system_snapshot` (shipped by the `projects-meta-mcp` server; the `meta-system-snapshot` capability lives in `OpeItcLoc03/common`). If the tool is missing from the session, the server isn't registered — trigger **`setup-projects-meta`** to install and register it, then retry. + +## The call + +`mcp__projects-meta__meta_system_snapshot` takes **no arguments**. Read-only — call it directly, no preview / confirm, no per-session grant. + +It returns three keys: + +| Key | Shape | Liveness | +|---|---|---| +| `poller` | `{ running: bool, projects: "" }` | **live** at call time | +| `docker` | `[{ name, status }]` — local containers | **live** at call time | +| `tasks` | `{ "/": { active, blocked }, … }` | **from the projects-meta cache** — may be stale | + +`docker` is the **local** machine's containers (includes `agents-task-runner-*`), NOT the VDS. `tasks` counts mirror the cache, so treat them as approximate; for accurate task state run the `using-projects-meta` Step 0 freshness gate or read local `.tasks/` on disk. + +## Output format — one line per section + +Compress the JSON into **three lines**. Don't dump the raw object. + +``` +🟢 Poller running — OpeItcLoc03/claude-skills (🔴 if running:false) +🟢 Docker — 8/8 up (else list only the bad ones) +📋 Tasks — 23 active / 41 blocked, 17 projects (name the busiest 2–3) +``` + +Rules per line: + +- **Poller** — 🟢/🔴 + running flag + the `projects` string. If stopped, say so plainly — that's the headline. +- **Docker** — if every status starts with `Up` (incl. `Up … (healthy)`), report `N/N up`. Otherwise list **only** the problem containers by name + status (`Restarting`, `Exited`, `(unhealthy)`, `Created`, `Paused`). Don't enumerate healthy ones. +- **Tasks** — totals (Σ active / Σ blocked across all projects) + the 2–3 projects with the most active work. Full per-project breakdown only if asked. + +## What NOT to do + +- **Do NOT** state "the poller is running" / "all containers are up" / "you have N active tasks" from memory or a prior snapshot. Call the tool in the current turn first. A snapshot from earlier in the session is already stale for liveness claims. +- **Do NOT** fall back to `tasklist` / `docker ps` / a manual `meta_status` to answer these questions — that's the scatter this skill exists to replace. (Drop to raw `docker logs` only for the deep single-container diagnosis this skill explicitly defers.) +- **Do NOT** paste the raw JSON. Three lines, one per section. +- **Do NOT** present `tasks` counts as exact — they come from the cache. Flag staleness if precision matters, and point at `using-projects-meta`. + +## Common mistakes + +| Mistake | Fix | +|---|---| +| "Poller's still up" without calling the tool this turn | Call `meta_system_snapshot` first — liveness claims need current evidence. | +| Running `docker ps` / `tasklist` instead | Use the single snapshot call; that's the point. | +| Reading the snapshot's `docker` as the VDS fleet | It's the **local** machine. VDS containers → `using-vds-ops`. | +| Treating `tasks` counts as authoritative | They're cached. For exact state use `using-projects-meta` Step 0 or local `.tasks/`. | +| Dumping the raw JSON object | Collapse to three lines (poller / docker / tasks). |