feat(cli): prepare manager tasks through public APIs

[Abiorh001]

Change

WS-CLI-001-19 — Manager task creation, screening and release.

Goal and intent

Complete the existing public manager preparation journey in the Go CLI. Three deliberate commands issue one POST each; the backend still owns authorization, readiness, locked policies, replay and atomic audit writes.

Intent, allowed files, rejected alternatives and acceptance: CLI19 change record.

What changed and design

workstream project task create PROJECT_ID --input FILE --idempotency-key UUID
workstream project task screen PROJECT_ID TASK_ID --idempotency-key UUID [--reason TEXT]
workstream project task release PROJECT_ID TASK_ID --idempotency-key UUID --reason TEXT

• Original closed creation JSON; explicit transition reason and caller-owned replay key. No preflight, automatic sequence or retry.
• A separate complete management response decoder binds identity, status, declaration and locked lineage without expanding contributor disclosure. Deadlines bind the normalized instant; import-batch IDs remain nullable text.
• Reuse the current JSON reader, credential scanner and non-replayable write transport. Contributor response limits remain unchanged.
• Extend the existing real public-API/PostgreSQL journey instead of introducing another server/database bootstrap. Update CLI documentation, roadmap and initiative navigation together.

Scope control

CLI implementation, process/journey tests and affected documentation only. No backend, migration, dependency or workflow change. The cohesive three-operation diff exceeds the preferred L1 size guideline; the record explains its shared projection and retained proof. No hidden routes or additional backend capabilities are exposed.

Evidence

go -C cli vet ./...
go -C cli mod verify
go -C cli mod tidy -diff
CGO_ENABLED=0 go -C cli build -trimpath -o /tmp/workstream-cli19-reconciled ./cmd/workstream
backend/.venv/bin/ruff check cli/tests
python3 scripts/check_markdown_links.py
python3 scripts/check_stale_workstream_wording.py
python3 scripts/check_commitrail_records.py --base-ref origin/main
git diff --check origin/main..HEAD

Current candidate: 224b30943fa643e47e7b0a5b6ab2fd5b7410dc38; base 4c8833b7921f106c8f4bfa06bad4615e6ec13588. The rebuilt binary embeds this revision with vcs.modified=false. Main's merged 4F3/4F4 recovery updates are retained; the INDEX diff against main changes only the CLI19 row. CLI source/tests are byte-identical to the independently approved 1bf0ce46; backend/workflows exactly match current main.

• All listed shared checks pass.
• Exact-current 14 process tests pass in 61.70s, covering new manager operations and retained contributor/guide-activation regressions. All static checks listed above pass.
• Previous real-API/PREP/PostgreSQL journey passed at 1bf0ce46 with cleanup. That execution remains historical: current main adds migrations and AUTH owner changes, so fresh hosted public-API/PostgreSQL integration is running before a new readiness claim.
• Independent counterchecks: removing project binding fails the hostile-receipt test after its valid control. The prior deadline defect accepts a changed instant; the repaired binary rejects it while accepting an equivalent timezone instant.
• Fresh hosted CLI: 144 passed in 201.96s. All required checks pass, including ten Backend lanes and aggregate. Downloaded evidence independently confirms 9,204 collected = 9,204 unique completed, identical node sets, zero skipped/deselected, matching evidence digests and all ten database cleanups complete. Tested merge dec37d84 has parents current base/head and source tree 3222c62d identical to clean head 224b3094. Fresh Backend run.

Test delta

Four new process tests and one helper in the retained production-socket journey. No tests or distinct assertions removed, skipped or weakened. Review caught and repaired deadline echo binding and the import-batch owner mismatch; the blank-release control now follows canonical 422/invalid_request rather than an incorrect 400 expectation.

Impact-routed reviewer results

All three bounded compatibility replays pass on clean 224b3094 / base 4c8833b7: architecture/docs/reuse (cli10_plan), security (cli10_security), QA/test delta (cli10_qa). No findings and all sessions completed. They verified complete incoming-index/roadmap preservation, byte-identical CLI/tests, relevant public-owner compatibility, exact-current process proof and source-compatible fresh hosted integration. Historical mutants retain their original execution custody, not a replaced SHA. The summaries mirror session evidence and do not own receipt custody.

External review

CodeRabbit completed a fresh substantive review of current base/head with no actionable comments; no unresolved threads were found. Its docstring-percentage warning is advisory, not a repository gate; no score-driven source or gate changes were made. All required CI passes. Final fetched head is 224b3094; GitHub confirms mergeable and requires eligible fresh human approval. Merge remains human-owned.

CI and gate integrity

• No workflow, package script, lint or test gate weakened.
• No dependency added; coverage remains diagnostic, not a gate.
• Retained contributor response limit and public disclosure are unchanged.

Remaining risks and follow-up

The native journey arranges retained approved-guide prerequisites; it does not certify live setup inference or deployed Flow Identity. Management replay is state/lineage/authority-sensitive, not an indefinitely reusable receipt. Uncertain writes require deliberate unchanged-input/key recovery. Hidden submission and binary distribution remain outside this change.

Hosted timing remains a known limitation: current Backend verification took 22m16s and misses its diagnostic timing target; CLI tests took 3m22s under their existing 240-second budget. This repair changes no workflow, test selection or timeout.

Human review focus and merge ownership

Inspect the three independent decisions, complete receipt binding, and fresh-authority replay. Merge stays human-owned.

• I can explain what changed and why.
• I accept the remaining risks.
• The user explicitly approved this specific PR for merge.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 4bb40e34-f3d5-49f9-b4d5-a33675cc1b74

---

📥 Commits

Reviewing files that changed from the base of the PR and between 4c8833b and 224b309.

---

📒 Files selected for processing (22)

• .commitrail/INDEX.md
• .commitrail/initiatives/WS-CLI-001/OVERVIEW.md
• .commitrail/initiatives/WS-CLI-001/WS-CLI-001-19.md
• README.md
• cli/README.md
• cli/internal/api/client.go
• cli/internal/api/guide_activation.go
• cli/internal/api/manager_tasks.go
• cli/internal/api/task_mutations.go
• cli/internal/command/guide_activation.go
• cli/internal/command/guide_approval.go
• cli/internal/command/guide_correction.go
• cli/internal/command/guide_create.go
• cli/internal/command/guide_post_approval.go
• cli/internal/command/guide_post_correction.go
• cli/internal/command/manager_tasks.go
• cli/internal/command/tasks.go
• cli/tests/integration/contributor_task_journey.py
• cli/tests/integration/manager_task_journey.py
• cli/tests/integration/test_manager_task_mutations.py
• cli/tests/integration/test_public_self_service.py
• docs/roadmap_status.md

---

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

---

📝 Walkthrough

📝 Walkthrough

📝 Walkthrough

📝 Walkthrough

Walkthrough

The CLI adds separate project-manager commands to create, screen, and release tasks. The API client validates task requests and responses, and integration tests cover command behavior, replay, and authorization.

Changes

Manager task preparation

Layer / File(s)	Summary
Manager task API and response validation cli/internal/api/manager_tasks.go, cli/internal/api/client.go, cli/internal/api/guide_activation.go, cli/internal/api/task_mutations.go	The API client adds task creation and preparation methods with request, response, declaration, and lineage validation. Mutation responses are checked for credential-safe values. Existing task writes use an explicit response-size limit.
CLI commands and input handling cli/internal/command/manager_tasks.go, cli/internal/command/tasks.go, cli/internal/command/guide_*.go, cli/internal/command/guide_post_*.go	The project task command adds create, screen, and release actions with manager-task receipt output. Existing guide commands use readJSONInput instead of readGuideInput; its file checks and size limit remain unchanged.
Command and API integration coverage cli/tests/integration/test_manager_task_mutations.py, cli/tests/integration/manager_task_journey.py, cli/tests/integration/contributor_task_journey.py, cli/tests/integration/test_public_self_service.py	Integration tests cover successful requests, invalid input and responses, replay, authorization, and uncertain outcomes. The contributor journey verifies that Submitter authority does not permit manager task writes.
Command and initiative documentation README.md, cli/README.md, .commitrail/INDEX.md, .commitrail/initiatives/WS-CLI-001/*, docs/roadmap_status.md	Documentation adds the manager task commands and describes separate calls, replay constraints, and the stated capability boundaries.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  actor Manager
  participant TerminalCLI
  participant Client
  participant WorkstreamAPI
  Manager->>TerminalCLI: Run create, screen, or release
  TerminalCLI->>Client: Call CreateTask or PrepareTask
  Client->>WorkstreamAPI: Send one public POST
  WorkstreamAPI-->>Client: Return task response
  Client-->>TerminalCLI: Return validated manager-task receipt

Loading

---

Merge Risk: ⚪ Minimal · up to 224b3

This change adds manager task create, screen, and release CLI commands with response validation and integration tests. No actionable merge-blocking risk was identified in the supplied context.

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 29 functions across 16 files. (6 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description check		The description is detailed and covers the change, intent, design, scope, evidence, tests, review results, risks, and merge ownership. Some template headings and checklist items are consolidated or om…
Title check		The title clearly and concisely identifies the main change: adding CLI support to prepare manager tasks through public APIs.

---

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 29 functions across 16 files. (6 skipped: 6 unsupported.)

---

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}