coulomb/activity-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs+workplan: activity CLI for repo-scoped automation review
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 2s
Details

Browse source 
Rigorous review of the review-CLI concept; rename to activity, lock offline-
first multi-source design, and open ACTIVITY-WP-0028 for implementation.
This commit is contained in:
tegwick 2026-08-06 11:02:57 +02:00
parent 7fb14e7610
commit 1789c535c5
2 changed files with 511 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

275
docs/repo-automation-review-cli.md Normal file
View file

@ -0,0 +1,275 @@
# Repo-scoped automation review CLI (`activity`)
**Status:** design (ready for implementation — ACTIVITY-WP-0028)
**CLI name:** `activity`
**Related:** [runbook.md](runbook.md), [ops-run-queue.md](ops-run-queue.md),
[recurring-automations-playbook.md](recurring-automations-playbook.md),
[edge-relay-resilience.md](edge-relay-resilience.md),
[llm-connect-host-access.md](llm-connect-host-access.md)
**Origin:** Freedom Intelligence operator need (2026-08-06) — review scheduled
deliverables from the consumer repo without AI tooling.
---
## Rigorous review of the original concept
### What is strong (keep)
| Strength | Why it matters |
| -------- | -------------- |
| **Repo-first lens** | Operators live in consumer repos; org-wide `automation-status` is the wrong default UX for “did FI run?” |
| **Multi-source truth** | Git vs hub vs ops_run disagreement is real (FI 2026-08-06: brief on origin, hub event lag). Single-source answers mislead. |
| **Local checkpoint / ack** | “Since I last looked” is personal; belongs in XDG state, not State Hub or actcore DB |
| **Non-goals** | Not a scheduler, not an agent, not a workplan writer — keeps scope bounded |
| **Reuse stack** | Ops API + artefacts (WP-0027) + git + hub progress — no new backend product |
| **Exit codes for scripting** | Fits morning automation and CI-ish operator habits |
### What was weak or ambiguous (fix)
| Issue | Optimization |
| ----- | ------------ |
| Name `actcore-review` | Prefer **`activity`** — short, repo-native, pairs with domain “activity definitions”. Document collision with unrelated packages; ship as console script of `activity-core`. |
| Five overlapping verbs | Collapse to a **stable verb set** with clear precedence: `status` = compose; `list` / `runs` / `deliverables` / `inbox` = slices; `ack` / `checkpoint` = local state only |
| “~100–200 lines wrapper” | Underestimates definition parsing, multi-source merge, and tests. Target a small **module package** under `activity_core/review_cli/` (~500–800 LOC + tests), not a one-file hack |
| Deliverable globs unspecified | Require a **convention** in definition frontmatter or docs table; v1 ships FI + Binky built-ins + optional `review:` block |
| Collection candidates first-class | **Defer** to v2 — regex mining briefs is fragile; path-level inbox first |
| Exit code 3 always | **Opt-in** `--strict-review` only — default 0/1/2 keeps “green morning” scripts usable |
| Live API always assumed | **Offline-first ladder**: local defs + git always work; API/hub enrich when reachable |
| Checkpoint stores both commits and paths | Prefer **path + ops_run_id** as primary ack keys; commits are optional hints only (paths move less than SHAs across rebase) |
| Prod SSH helper as first path | Prefer **ops API** (`ACTIVITY_CORE_URL` / SSO-reachable host); SSH prod script is break-glass only |
### Verdict
**Concept is good.** Implement it as the **`activity` CLI**, activity-core owned,
consumer-cwd friendly, offline-capable, multi-source honest.
---
## Problem (restated)
From a **consumer repo** (e.g. `freedom-intelligence`), answer without AI:
1. Are regular automations declared / scheduled for this repo?
2. What is the list?
3. What ran or failed in a time window (today / week / since last review)?
4. What deliverables were produced?
5. What is still open for human review?
Evidence is split today: activity-core definitions/runs/ops_runs, State Hub
progress, git artefacts, ops UI. Existing tools are **activity-core-centric**,
not **repo-first**, and lack a personal review cursor.
## Non-goals
- New scheduler or claim worker
- LLM / coding-agent workflow
- Replacement for ops UI
- Hub writes for workplans/tasks (checkpoint is local only)
- Authoring definitions from the CLI
- First-class “collection candidate” inbox items (v2)
## Name and entrypoint
```bash
# Install (activity-core package)
uv tool install -e ~/activity-core # or pip install -e .
# → console script: activity
cd ~/freedom-intelligence
activity status
activity inbox
activity ack briefs/2026/08/2026-08-06.md
```
| Rule | Choice |
| ---- | ------ |
| Binary name | `activity` |
| Package | `activity-core` (`[project.scripts] activity = activity_core.review_cli:main`) |
| Default cwd | Consumer repo root (or any descendant) |
| Repo slug | `--repo` > git remote path > `.repo-classification.yaml` > directory name |
| Config | Env: `ACTIVITY_CORE_URL`, `STATE_HUB_URL`, `ACTIVITY_REVIEW_STATE_DIR` |
| Collision | If another `activity` is on PATH, document `python -m activity_core.review_cli` |
Working name `actcore-review` is **retired** in favour of `activity`.
## Commands
| Command | Operator question | Evidence order |
| ------- | ----------------- | -------------- |
| `list` | What automations bind to this repo? | Local `activity-definitions/*.md` → ops API filter `target_repo` |
| `runs [--since …]` | What ran / failed? | Ops API runs+ops_runs → hub `executor_run` → degraded label |
| `deliverables [--since …]` | What was produced? | ops_run artefacts ∪ git globs ∪ hub completion paths |
| `inbox` | Open for review? | Deliverables since checkpoint − ack set |
| `status` | One-screen dashboard | Compose list + runs + inbox counts + source health |
| `checkpoint show\|set\|clear` | Review cursor | Local state file only |
| `ack <path\|ops-run-id\|--all>` | Mark reviewed | Updates local state; no remote writes |
### Defaults
| Flag | Default |
| ---- | ------- |
| `--since` for `runs` / `deliverables` | `checkpoint` if set, else `today` (Europe/Berlin calendar day) |
| `--since` shortcuts | `today`, `yesterday`, `week`, `sunday`, `checkpoint`, ISO date/time |
| `--format` | `text` \| `json` |
| `--strict-review` | off — when on, exit `3` if inbox non-empty |
| `--repo` | auto-detect |
### Example session
```bash
cd ~/freedom-intelligence && git pull --ff-only
activity status
# Repo: freedom-intelligence
# Automations: 1 enabled (FI Daily Research Brief 30 7 * * 1-5 Europe/Berlin)
# Since checkpoint 2026-08-05T16:00+02:00
# runs: 1 ok, 0 failed deliverables: 1 new inbox: 1
# Sources: defs=ok git=ok api=ok hub=degraded
activity runs --since today
# 2026-08-06 07:30 ok ops_run=… path=briefs/2026/08/2026-08-06.md hub=missing
activity inbox
# [ ] briefs/2026/08/2026-08-06.md (partial: git ok, hub fi_daily_brief missing)
activity ack briefs/2026/08/2026-08-06.md
activity checkpoint show
```
### Exit codes
| Code | Meaning |
| ---- | ------- |
| `0` | No automation failures in window; sources not hard-failed |
| `1` | ≥1 failed run / failed ops_run in window |
| `2` | Evidence degraded (API/hub unreachable; partial answer printed) |
| `3` | Open inbox items remain (**only** with `--strict-review`) |
## Checkpoint model
**Local, operator-owned** — XDG state, not hub/DB.
```text
${ACTIVITY_REVIEW_STATE_DIR:-$XDG_STATE_HOME/activity}/<repo-slug>/checkpoint.json
# default XDG_STATE_HOME=~/.local/state
```
```json
{
"repo": "freedom-intelligence",
"schema": 1,
"reviewed_at": "2026-08-05T16:00:00+02:00",
"reviewed_paths": ["briefs/2026/08/2026-08-05.md"],
"reviewed_ops_run_ids": ["eeccd98a-bd2b-4247-9289-2bf17aa22301"],
"notes": ""
}
```
- Primary ack keys: **`reviewed_paths`**, **`reviewed_ops_run_ids`**
- `reviewed_at` advances on `ack` / `checkpoint set`
- No multi-host sync (v1)
## Resolving “for this repo”
1. **Declared (offline):** parse consumer `activity-definitions/*.md`
Match when `target_repo` == slug, or labels contain slug, or file lives in
that repo’s definitions tree.
2. **Live schedule:** `GET /ops/automations?target_repo=<slug>` (add filter if
missing).
3. **Runs:** `GET /ops/automations/{id}/runs?since=…` (artefacts from WP-0027);
optional `GET /ops-runs?target_repo=&since=`.
4. **Deliverables:** union of artefact paths, git globs, hub completion
`detail.path` for configured event types.
### Trust matrix (do not simplify away)
| Git artefact | Hub completion | Interpretation |
| ------------ | -------------- | -------------- |
| present | present | **ok** |
| present | missing | **partial** — produced; bookkeeping gap (warn, not “did not run”) |
| missing | present | **lag/mismatch** — pull remote / wrong clone / path drift |
| missing | missing | **missing** — did not run or failed before write |
Never answer “did not run” from hub-only absence when git has the artefact.
## Definition convention (v1)
Prefer optional frontmatter (when present):
```yaml
review:
deliverable_globs:
- "briefs/**/*.md"
completion_event_type: fi_daily_brief
path_in_event: detail.path # default
```
**Built-in fallbacks** (no frontmatter required day one):
| Repo / automation id | Globs | Completion event |
| -------------------- | ----- | ---------------- |
| `freedom-intelligence` / `fi-daily-research-brief` | `briefs/**/*.md` | `fi_daily_brief` |
| `binky-control` / binky daily rhythm | `briefs/**/*daily*` | `binky_daily_brief` (if used) |
Unknown automations: still list + show runs; deliverables only from
`ops_run.result.path` when present.
## Placement
| Layer | Role |
| ----- | ---- |
| `activity_core/review_cli/` | CLI + merge logic + checkpoint |
| Ops API | `target_repo` filters; runs already carry artefacts |
| `make activity-review …` | Thin Makefile pass-through (optional) |
| Does **not** replace | `automation-list`, `automation-status`, `prod_automation_status.sh` |
## Architecture
```text
activity status|list|runs|…
│
├─ resolve_repo(cwd, --repo)
├─ load_local_definitions()
├─ load_checkpoint(state_dir)
├─ try ops API (ACTIVITY_CORE_URL)
├─ try State Hub (STATE_HUB_URL)
├─ git log / path exists
└─ merge → trust matrix → text|json + exit code
```
### Minimal phases (implementation)
| Phase | Deliverable | Offline? |
| ----- | ----------- | -------- |
| **P0** | `list` + `status` (defs only) + `--json` | yes |
| **P1** | `deliverables` + `checkpoint` + `ack` + `inbox` (git + checkpoint) | yes |
| **P2** | `runs` + hub completion join + trust matrix | partial |
| **P3** | Live API `target_repo` filter + full green/partial rows | needs URL |
| **P4** | Docs, Makefile, install path, FI morning ritual in playbook | — |
## Open decisions — locked for WP-0028
| # | Decision | Lock |
| - | -------- | ---- |
| 1 | Package location | **activity-core** console script `activity` |
| 2 | Exit code 3 | **Opt-in** `--strict-review` |
| 3 | Deliverable declaration | Optional `review:` frontmatter + built-in table |
| 4 | Collection candidates | **Out of v1** |
| 5 | Default evidence | Offline-first; API enriches |
| 6 | Ack keys | paths + ops_run ids (not commits alone) |
## Relationship to existing tools
| Tool | Role after `activity` ships |
| ---- | --------------------------- |
| `make automation-status` | Org/cluster window (unchanged) |
| `prod_automation_status.sh` | Prod SSH fire counts (break-glass) |
| ops UI | Browser review + trigger/pause |
| **`activity`** | Consumer-repo morning review + personal checkpoint |
## Pin log
| Date | Change |
| ---- | ------ |
| 2026-08-06 | Concept captured (actcore-review working name) |
| 2026-08-06 | Rigorous review; rename to `activity`; optimize scope; WP-0028 |

236
workplans/ACTIVITY-WP-0028-activity-review-cli.md Normal file
View file

@ -0,0 +1,236 @@
---
id: ACTIVITY-WP-0028
type: workplan
title: "activity CLI — repo-scoped automation review"
domain: infotech
repo: activity-core
status: ready
owner: grok
topic_slug: activity-core
priority: high
created: "2026-08-06"
updated: "2026-08-06"
depends_on:
- ACTIVITY-WP-0027
- ACTIVITY-WP-0024
- ACTIVITY-WP-0018
related:
- ACTIVITY-WP-0019
- ACTIVITY-WP-0021
- ACT-ADR-005
---
# ACTIVITY-WP-0028 — `activity` CLI (repo-scoped automation review)
## Origin
Operator need (Freedom Intelligence, 2026-08-06): review scheduled automations
and deliverables **from the consumer repo**, without AI tooling. Concept doc
`docs/repo-automation-review-cli.md` reviewed and refined: name **`activity`**,
offline-first multi-source merge, local checkpoint/ack.
Builds on WP-0027 (run artefacts / Forgejo links), WP-0024 (ops API), WP-0018
(automation-status contract patterns).
## Goal
Ship an installable **`activity`** CLI so that from e.g. `~/freedom-intelligence`:
```bash
activity status # one-screen dashboard
activity list # automations for this repo
activity runs --since today
activity deliverables --since checkpoint
activity inbox # open for human review
activity ack <path> # mark reviewed (local only)
```
Answers use local definitions + git always; ops API and State Hub enrich when
reachable. Multi-source trust matrix must never claim “did not run” when git has
the artefact.
## Non-goals
- Scheduler / claim loop changes
- LLM or agent workflow
- Replacing ops UI or `make automation-status`
- Hub/workplan writes
- Collection-candidate mining (v2)
- Multi-host checkpoint sync
## Design locks (from concept review)
| Lock | Choice |
| ---- | ------ |
| CLI name | `activity` |
| Package | activity-core console script |
| Checkpoint | `~/.local/state/activity/<slug>/checkpoint.json` |
| Exit 3 | only with `--strict-review` |
| Deliverable globs | optional `review:` frontmatter + built-in FI/Binky table |
| Evidence | offline-first ladder |
Canon: `docs/repo-automation-review-cli.md`.
## Tasks
## Task: Package entrypoint and repo resolution
```task
id: ACTIVITY-WP-0028-T01
status: todo
priority: high
```
1. Add `activity_core/review_cli/` package with `main()` argparse dispatcher.
2. Register `[project.scripts] activity = "activity_core.review_cli:main"` in
`pyproject.toml`.
3. Implement `resolve_repo_slug(cwd, --repo)`:
- explicit flag
- git remote path (last path component of forgejo/github URL)
- `.repo-classification.yaml` if present
- directory basename
4. Support `--format text|json`, global `--repo`, `--help`.
5. Unit tests for slug resolution (no network).
**Done when:** `uv run activity --help` and `activity list --help` work from a
consumer cwd in tests or documented local install.
## Task: Local definition list (P0 offline)
```task
id: ACTIVITY-WP-0028-T02
status: todo
priority: high
```
Depends on T01.
1. Parse `activity-definitions/*.md` in consumer repo (reuse definition_parser
patterns where possible).
2. Filter to this repo: `target_repo`, labels, or defs living in this tree.
3. `activity list` prints name, cron/timezone, enabled, executor hint if known.
4. `activity status` minimum: list count + “sources: defs=ok”.
5. Built-in table for FI/Binky review globs + completion event types.
**Done when:** offline `cd freedom-intelligence && activity list` shows FI daily
definition without API.
## Task: Checkpoint, ack, deliverables from git (P1 offline)
```task
id: ACTIVITY-WP-0028-T03
status: todo
priority: high
```
Depends on T02.
1. Checkpoint load/save under XDG state dir (`schema: 1`).
2. Commands: `checkpoint show|set|clear`, `ack <path|ops-run-id|--all>`.
3. `deliverables --since today|week|checkpoint|ISO`: git paths matching globs
(and optional `ops_run` paths when available later).
4. `inbox`: deliverables since checkpoint minus acked paths/ids.
5. Exit codes 0/2 for degraded; document `--strict-review` → 3.
**Done when:** ack a brief path; `inbox` empties; state file survives process exit.
## Task: Runs + hub completion + trust matrix (P2)
```task
id: ACTIVITY-WP-0028-T04
status: todo
priority: high
```
Depends on T03.
1. `activity runs --since …` merges:
- ops API runs when `ACTIVITY_CORE_URL` set and healthy
- State Hub progress (`fi_daily_brief`, `executor_run`, …) when hub URL set
- never silence git-present rows as missing
2. Implement trust matrix rows: `ok` | `partial` | `lag` | `missing` | `failed`.
3. `status` dashboard: run counts, inbox size, per-source health
(`defs`/`git`/`api`/`hub`).
4. Tests with mocked HTTP + temp git repo.
**Done when:** fixture where git has brief and hub lacks event prints **partial**,
not “did not run”; exit `1` only on real failures.
## Task: Ops API target_repo filter + live enrichment (P3)
```task
id: ACTIVITY-WP-0028-T05
status: todo
priority: medium
```
Depends on T04.
1. Add `target_repo` query param to `GET /ops/automations` and status where
missing (filter client-side first if server change is larger).
2. Prefer `GET /ops/automations/{id}/runs` artefacts (WP-0027) for deliverable
links and ops_run ids (ack by id).
3. Optional `GET /ops-runs?target_repo=&since=` if cheap.
4. Wire `ACTIVITY_CORE_URL` default discovery doc (SSO host vs ClusterIP vs
port-forward break-glass).
5. Contract tests for API filter if server-side.
**Done when:** with live API URL, `activity runs --since week` shows FI fires
and Forgejo/path artefacts without SSH.
## Task: Docs, Makefile, morning ritual, install notes
```task
id: ACTIVITY-WP-0028-T06
status: todo
priority: medium
```
Depends on T03 (docs can land with P1).
1. Keep `docs/repo-automation-review-cli.md` as canon; link from runbook +
recurring-automations playbook.
2. FI recurrence-ops: morning ritual
`git pull && activity status && activity inbox`.
3. Optional `make activity-review ARGS='status'` pass-through.
4. AGENTS.md / README: durable review uses `activity`, not coding-assistant
memory.
5. Document PATH collision and `python -m activity_core.review_cli`.
**Done when:** an operator can install and run the ritual from docs alone.
## Task: Smoke on freedom-intelligence (railiance evidence)
```task
id: ACTIVITY-WP-0028-T07
status: todo
priority: high
```
Depends on T04–T05.
1. Install CLI on workstation (and optionally railiance host).
2. Smoke matrix:
- offline `list` / `status` in `freedom-intelligence`
- after real or manual fire: `runs` + `deliverables` + `inbox` + `ack`
- JSON mode for scripting
3. Record non-secret sample output paths/exit codes in this workplan.
4. `statehub fix-consistency` after status updates.
**Done when:** morning ritual works for FI without AI and without SSH for the
common case (API or offline+git).
## Acceptance (workplan)
- [ ] `activity` installable from activity-core
- [ ] Offline list + git deliverables + checkpoint/ack work in consumer repo
- [ ] Trust matrix never “did not run” when git has artefact
- [ ] Live path uses ops API artefacts when available
- [ ] Docs describe ritual; org-wide make targets unchanged
## References
- Design: `docs/repo-automation-review-cli.md`
- Artefacts: ACTIVITY-WP-0027, `docs/ops-run-queue.md`
- Ops API: `src/activity_core/ops_api.py`
- Status patterns: `src/activity_core/automation_status.py`