--- id: ACTIVITY-WP-0028 type: workplan title: "activity CLI — repo-scoped automation review" domain: infotech repo: activity-core status: finished 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 state_hub_workstream_id: "1f99bf6f-5180-5e4e-b9a5-5137c48d84c4" --- # 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 # 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//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: done priority: high state_hub_task_id: "3c8117c1-81e9-5d92-9221-912350c308dc" ``` 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: done priority: high state_hub_task_id: "38abf01c-fb20-5d7e-a878-2fb19a3fae2c" ``` 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: done priority: high state_hub_task_id: "6f2be701-2738-5cd2-a1f9-eddb0062d403" ``` Depends on T02. 1. Checkpoint load/save under XDG state dir (`schema: 1`). 2. Commands: `checkpoint show|set|clear`, `ack `. 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: done priority: high state_hub_task_id: "2f4ca8a7-498d-580f-8120-5810de366055" ``` 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: done priority: medium state_hub_task_id: "d1bdd871-2ede-5026-979b-a877c379fd03" ``` 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: done priority: medium state_hub_task_id: "9a115c73-19c1-598e-9476-e91db33a02b1" ``` 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: done priority: high state_hub_task_id: "941e4662-5468-56c4-a07b-f2d71ced71a1" ``` 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) - [x] `activity` installable from activity-core - [x] Offline list + git deliverables + checkpoint/ack work in consumer repo - [x] Trust matrix never “did not run” when git has artefact - [x] Live path uses ops API artefacts when available - [x] 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` ## Implementation evidence (2026-08-06) - Package: `activity_core/review_cli/` + console script `activity` - Tests: `tests/test_review_cli.py` (9 passed) - Smoke FI: - `activity --cwd ~/freedom-intelligence list` → FI daily brief - `inbox` shows briefs with trust `ok`/`partial` - `ack path` shrinks inbox by path (not by reviewed_at alone) - API: `GET /ops/automations?target_repo=` filter - Docs: runbook + `docs/repo-automation-review-cli.md` + FI recurrence-ops ritual