activity-core/workplans/ACTIVITY-WP-0028-activity-review-cli.md

---
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 <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: 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 <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: 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