255 lines
8.1 KiB
Markdown
255 lines
8.1 KiB
Markdown
---
|
||
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: "a405ce6a-2f1d-47b0-8ab8-85ae9cb8bfb2"
|
||
---
|
||
|
||
# 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: "9a780335-d97a-4c39-9845-7654d3bdf206"
|
||
```
|
||
|
||
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: "c5ebb26f-2494-4fac-8540-d9a9d74e350b"
|
||
```
|
||
|
||
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: "3e39e349-c43e-406a-b86d-f7dc704707c1"
|
||
```
|
||
|
||
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: "a3203d03-5f6e-4ddf-875f-9d5c31ea9aeb"
|
||
```
|
||
|
||
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: "f687c2af-80ef-44f3-94da-5fb663b035c3"
|
||
```
|
||
|
||
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: "a6cd4704-1284-4859-8cee-3ea49aae4312"
|
||
```
|
||
|
||
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: "84b090ce-168c-4c3b-9390-1de8a4d5f488"
|
||
```
|
||
|
||
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
|