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

id	type	title	domain	repo	status	owner	topic_slug	priority	created	updated	depends_on	related	state_hub_workstream_id
ACTIVITY-WP-0028	workplan	activity CLI — repo-scoped automation review	infotech	activity-core	finished	grok	activity-core	high	2026-08-06	2026-08-06	ACTIVITY-WP-0027 ACTIVITY-WP-0024 ACTIVITY-WP-0018	ACTIVITY-WP-0019 ACTIVITY-WP-0021 ACT-ADR-005	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:

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

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)

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)

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)

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)

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

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)

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)

• 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

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