cargo xtask Subcommand Catalog

init

Initialise a project from the claude-quickstart template

New project bootstrap only

dev

Manage the Docker devstack (see dev — devstack lifecycle)

Daily

test

fmt + clippy + nextest

Before committing

validate

Pre-push gate: fmt + clippy + build + nextest + SPDX + signing + visibility + Tier-3 docs + cargo deny. Emits a self-describing per-stage report to test-results/validate-report.json (schema, #1253)

Pre-push hook; the trusted gate

validate-in-network

Run validate inside the canopy docker network so PG-touching tests work without host Postgres (#339, ADR-015)

Opt-in; contributors without host PG

e2e

Playwright E2E against the devstack; --devstack-profile {snap-only,full} (the demo profile was retired in #716)

After UI / route changes

perf

k6 performance tests against the devstack

Manual; load testing

seed

Seed databases with deterministic data; --reset

Fixtures (the role-keyed cast; the dedicated demo profile was retired in #716)

seed-verify

Cross-service referential-integrity auditor over the seeded devstack (see seed-verify — cross-service integrity auditor)

After seed/schema changes

api-docs

Regenerate plain-language API docs / OpenAPI snapshots from utoipa; --update

After endpoint changes

check-docs

Verify Tier-1 docs match the upstream template (SHA-256)

CI doc-integrity gate

docs

Plan lifecycle tooling (see docs — plan lifecycle (ADR-013))

ADR-013 plan hygiene

policy

Policy traceability (see policy — traceability (ADR-011 / ADR-031))

ADR-011 citation work

scenarios

Scenario-inventory gate (ADR-031 §3 / ADR-032): audit schema, bindings, per-corpus coverage

Scenario / corpus work

rules

JDM ruleset schema gate — compile every rulesets/ file via zen-engine

After ruleset edits

compliance

ADR-004 data-tenancy audit + ADR-005 capabilities drift

Compliance gates

quality-budgets

Code-quality debt ratchet (epic &62 M6): count 8 debt metrics against the lock; --write-lock ratchets, --fail-on-regression gates

Blocking in validate [13i/15]

typed-ids

Typed-Path<*Id> rollout gate (#627): bans raw Path<Uuid> extractors

Route work

route-authz

Route write-authz gate (#1004): every case-mutation route carries its authz extractor

Route work

outbox-migrations

ADR-039 single-sourced event_outbox schema: --check parity-gates the per-service copies, --write regenerates

After outbox schema changes

sweep-finalize-orphans

One-shot ADR-038 sweep of pre-saga orphaned finalize graphs (#1055); dry-run by default, --apply compensates

Operator surgery

secrets-yaml-lint

Plaintext-secrets gate for config/*/.yaml (896); an intentional secret needs allow-secret: <reason>

CI security gate

plan-lint

Lint plan documents for the canonical Status vocabulary (universal engine; the project-level twin of docs plan-lint)

Plan hygiene

audit-memory

Advisory hygiene report for the local agent-memory dir (machine-local; report-only, --strict for a non-zero exit)

Agent hygiene

fn-shape-report

Advisory function-shape smell radar (and names, &mut out-params, tuple returns)

Refactor radar

migrate

Snapshot / rollback devstack databases (pg_dump/pg_restore wrappers)

Dev rollback (ADR-016)

secrets

SOPS-encrypted dev-secrets workflow (init/edit/decrypt/add-recipient)

ADR-017 secret management

gen-signing-keys

Generate an ECDSA P-256 key pair for a program service

New program service (ADR-002)

identity

canopy-identity contract conformance + reference IaC templates (ADR-019)

Identity / OIDC work

coverage

Workspace line-coverage gate via cargo-llvm-cov

Coverage checks

vendor-check

Re-hash every vendored JS file against vendor.toml (drift gate)

After touching static vendor assets

ci-config-lint

CI-config regression gate (ADR-040): assert the build-once / gate-complete promotion invariants of .gitlab-ci.yml + the Dockerfiles' COPY coverage

CI + pre-push static gate; after editing .gitlab-ci.yml or a Dockerfile

dev start

Build images, start infrastructure, create per-service DBs, load the Keycloak realm, wait for health

dev refresh

Auto-detect changes by content hash and apply the minimum rebuild/restart

dev reload

Force a coordinated bounce of all services

dev clean [--confirm]

Tear down and remove volumes (fresh DBs)

dev status

Print the URL table (host-mapped ephemeral ports — see Service Catalog)

dev logs

Tail service logs

seed-verify

Cross-service ref auditor — walks FK pairs across the seeded service DBs, exits non-zero on any orphan. Skip-tolerant: checks touching a DB whose container is down (e.g. the program DBs on a SnapOnly stack) are skipped, not failed. --verbose lists each orphan row.

docs plan-lint

Validate every active plan uses the closed-set Status vocabulary (blocking)

docs plan-archive

Move fully-Done plans into plans/archive/

policy audit

Validate citations across both source families (blocking in CI): jurisdiction (citations.toml ↔ jurisdiction.toml, ADR-011) and federal (rulesets/federal/citations.toml ↔ rulesets/federal/*.json, ADR-031 §1). --source all|jurisdiction|federal selects a family (default all)

policy audit-literals / audit-unwraps

Detect hardcoded policy values / silent numeric fallbacks outside params.rs

policy audit-jurisdiction-literals

Detect jurisdiction values leaking outside the ruleset mechanism (#1226): the Georgia helpline in any code (fixtures use 555 numbers) and quoted "GA" state codes in non-test code; allowlist with reasons at compliance/jurisdiction-literal-allowlist.toml. Runs in validate as the jurisdiction-literals gate

policy audit-completeness-reads

Fail when a canopy-reporting federal universe bypasses the two blessed completeness types (#1249, ADR-001 Amendment 1 §B3): CompletenessRead (drain-to-Vec) and its page-at-a-time sibling UniversePager (#1202 MR4, for the report worker’s Draining phase). The pinned universe fetches must return a marker (each constructed only behind the fail-closed total_in_scope tripwire — missing total refused, exhaustion reconciled), the federal extract modules must take one of the two in their assembly signatures, and no hand-rolled page-cursor/total handling may reappear in the consumer layer. Runs in validate as the completeness-reads gate

policy sync-cache

Clone/pull the PAMMS source repos locally + write the sync manifest (per-repo HEAD, per-cited-file SHA-256) into .policy-cache/; --pin back-fills source_sha256 pins onto resolving citations (ADR-031 §1)

policy drift

Report citations whose pinned source changed since verification (re-syncs first; --no-sync for offline). Exit 1 on drift; never edits values — the report prints the re-verify→re-pin loop. CI job adr-031-policy-drift is permanently advisory (ADR-031 §1)

policy action-coverage

Verify the mandated-action catalogue (compliance/action-catalogue/*.toml) against the committed OpenAPI snapshots, offline: path + verb + operationId + security + test-ref per binding; un-allowlisted gaps exit 1 (allowlist needs reason + issue ref). CI job adr-031-action-coverage, advisory until &60 MR5 (ADR-031 §2)