feat(cli): create draft projects with explicit replay custody

[Abiorh001]

Change

WS-CLI-001-08 — create a draft project shell through the public API.

Goal and planning context

Add one complete CLI setup step, not another backend lifecycle or authorization
implementation. Bounded record
defines intent, scope, alternatives, acceptance criteria and human focus.

What changed

• workstream project create --name TEXT --slug TEXT --idempotency-key UUID [--description TEXT]: one public POST; caller bearer/key unchanged.
• Creation requires exact 201 and full ProjectResponse. Existing operations
  retain exact 200. Project inspection shares parsing and safe output.
• Preserve optional description, backend text bounds, an 8-KiB encoded request
  cap, canonical known denials and explicit uncertain outcomes. No automatic
  replay, preflight, key generation, guide upload or activation.
• Update CLI/root README, affected capability-ledger claims and durable CLI
  navigation in the same change. Core product gates and policy branches do not
  change; this exposes an existing public API in the CLI only.

Scope control

Only planned CLI source/tests and CLI documentation/records changed. Backend,
MCP, workflows, Go dependencies and existing test selection are unchanged.

Evidence

Go verify/tidy-diff/vet/gofmt/build; Ruff/style; Markdown links; four stale scans;
Commitrail checks and 16 workflow guards passed.

Current repair head is 637929c2057ba78e956c22c4aa1d2b4dded4ecd5, incorporating
main b6e62f0e and migration 0022_submission_packet_custody. INDEX retains the
CLI08 row from the prior head and the ARCH packet-custody row exactly from main.
CLI source/tests are byte-identical to the prior head; backend, MCP, workflows
and dependencies are byte-identical to current main. README and roadmap retain
both initiatives' updates. Current-head Go/style, link/stale/Commitrail checks
and 16 workflow guards pass. 48 current-head local HTTP/process tests pass.
The fresh hosted full CLI/API journey passed all 49 tests in 50.50s,
after migration 0022. Hosted checkout 25ff5571 and current review head share
exact tree 22849fc56273a8ea157a57961a1779019ea5f927.
Full Backend
passed all nine lanes and the aggregate check. The final authenticated artifact
reconciles 8,693 unique collected/completed backend nodes, no skips/deselections,
all execution exits zero and no interrupted selected lane. Evidence hashes,
PostgreSQL migration 0022, real MinIO probes and database/storage cleanup verified.
Agent Gates and MCP CI also passed.

Retry history is preserved: attempt 1 hit the existing 1,200-second task-lifecycle-a
deadline after 449/460 completed nodes, with no failed assertion recorded. The same
source's complete 460-test retry passed in 859.471s; the aggregate uses that passing
lane plus the eight original passing lanes. The interrupted attempt is not passing
evidence. No timeout, selection or CI rule changed. The timing target remains unmet:
aggregate Backend wall time including retry is 2,581.638s (~43m2s). This CLI change
does not solve the existing CI bottleneck.
Eligible human approval is still required after the latest push.
Historical f99b0bbc proof remains separate: 49 complete local/hosted CLI tests
and 8,688 backend completions before incorporating main. Earlier local deadline
failures were not counted as passing evidence; the unchanged local run subsequently
passed in 320s with a local-only budget. No CI deadline or selection changed.

The installed-process suite tests exact wire inputs/output, nullable description,
Unicode/encoded-size boundaries, malformed replies, error credential reflection,
unknown outcomes and HTTP/2 GOAWAY. A scratch build with rewindable mutation
bodies fails the named GOAWAY regression by sending twice.

The public-API journey adds creation/GET parity, unchanged manual replay,
body mismatch, slug non-overwrite, system versus project scope, revoked-grant
recovery/new-key denial and suspension with a valid positive control. It restores
the spare actor and grants before the retained task journey.

Test delta

Two integration sources added; existing public journey extended. No Go unit
suite, skipped/removed tests, weakened assertions or coverage-percentage gate.

Impact-routed internal reviews

Prior implementation head: f99b0bbcfda17091c57efed9c16893e7da714d00.

• Architecture/docs: PASS; neutral parent help repair verified.
• Security and QA/test-delta: PASS after inspecting exact-head full execution,
  persisted-state assertions and fixture restoration; no findings remain.
• Proof boundaries: HTTP process/TLS peer for wire and replay; real FastAPI and
  migrated PostgreSQL for stored state and authorization. Inspection is not
  substituted for missing execution. Reviews are advisory session evidence.

Current merge-preservation documentation replay: PASS at 637929c2, with exact
parent-row preservation and independent README/roadmap three-way blob checks.
QA/test-delta integration replay: PASS at 637929c2, after inspecting the fresh
hosted 49-test migration-compatibility proof and unchanged test/owner bytes.
Previous reviews are retained as historical scoped evidence, not relabeled as
new-head reviews; there is no CLI behavior or test change in the reconciliation.

External review and CI integrity

CodeRabbit completed a substantive review of 637929c2 with no actionable
comments. Its default docstring percentage warning is not a repository policy;
no quota-only source changes are added. Hosted checks and conversations remain GitHub-owned.
No workflow, package command, dependency or complete-test requirement weakened.

Remaining risks and human focus

This is a draft shell, not an approved guide or ready work. Retain the unchanged
input and UUID key if manually recovering an unknown outcome.

The existing project-create API recovers committed results before fresh PREP,
including after creation-grant revocation. This differs from task replay and is
not authority for another creation. Suspended/revoked-link committed recovery is
an explicit preexisting AUTH-owner question, not a client-side guard or new claim.

Source build does not establish binary distribution or hosted deployment.
No subsequent CLI step starts in this PR.

Human merge ownership

• I can explain the change and its risks.
• I approve 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: f7750f4c-7b21-468c-9338-c7cc0e304ff7

📥 Commits

Reviewing files that changed from the base of the PR and between b6e62f0 and 637929c.

📒 Files selected for processing (15)

• .commitrail/INDEX.md
• .commitrail/initiatives/WS-CLI-001/OVERVIEW.md
• .commitrail/initiatives/WS-CLI-001/WS-CLI-001-08.md
• README.md
• cli/README.md
• cli/internal/api/client.go
• cli/internal/api/project.go
• cli/internal/api/project_create.go
• cli/internal/api/task_mutations.go
• cli/internal/command/command.go
• cli/internal/command/project_create.go
• cli/tests/integration/project_create_journey.py
• cli/tests/integration/test_project_create_http.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

The CLI adds workstream project create to create draft project shells through the public projects endpoint. The command validates input, uses a caller-supplied idempotency key, validates the response, and reports uncertain outcomes. Integration tests cover command behavior, replay, authorization, and persistence.

Changes

Draft Project Creation

Layer / File(s)	Summary
API request and response handling cli/internal/api/client.go, cli/internal/api/project.go, cli/internal/api/project_create.go, cli/internal/api/task_mutations.go, .commitrail/initiatives/WS-CLI-001/WS-CLI-001-08.md	The API client accepts an expected success status and validates canonical mutation errors. Project creation validates request fields and the encoded request size, expects HTTP 201, and supplies replay guidance for unknown outcomes. Project response parsing is shared and validates the project ID and response fields.
CLI command and project output cli/internal/command/*, README.md, cli/README.md, .commitrail/INDEX.md, .commitrail/initiatives/WS-CLI-001/*, docs/roadmap_status.md	The CLI registers project create, requires explicitly supplied name and slug values, and includes the description only when its flag is set. Project output uses shared formatting. The documentation and initiative records describe the command, its boundaries, and the delivered work.
Creation and recovery verification cli/tests/integration/*, .commitrail/initiatives/WS-CLI-001/WS-CLI-001-08.md	Integration tests cover request validation, response handling, uncertain outcomes, and single transmission. The public API journey checks route exposure, persistence, replay, conflicts, authorization changes, and actor suspension.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant APIClient
  participant ProjectsEndpoint
  CLI->>APIClient: project fields and idempotency key
  APIClient->>ProjectsEndpoint: POST /api/v1/projects
  ProjectsEndpoint-->>APIClient: HTTP 201 response
  APIClient-->>CLI: validated result or failure

Loading

Merge Risk: ⚪ Minimal · up to 63792

This adds a draft-project creation command with explicit idempotency-key handling and strict response validation. No concrete merge-blocking risk was identified. Confirm that the hosted checks pass on the current head before merging.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding draft project creation to the CLI with explicit replay custody.
Description check	✅ Passed	The description gives substantial detail on the change, scope, design, evidence, test delta, reviews, risks, and human merge ownership. Some template headings and details are not stated in the templat…

Full details: Docstring Coverage

Explanation

Docstring coverage is 8.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 24 functions across 9 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

• Autopilot · 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.}