docs+workplan: activity CLI for repo-scoped automation review
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:
parent
7fb14e7610
commit
1789c535c5
2 changed files with 511 additions and 0 deletions
236
workplans/ACTIVITY-WP-0028-activity-review-cli.md
Normal file
236
workplans/ACTIVITY-WP-0028-activity-review-cli.md
Normal 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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue