Build.

# install the CLI
$ pip install motusos
$ motus --help

# install Motus defaults
$ motus install

# init in your repo
$ cd your-repo
$ motus init --lite --path .
$ motus doctor

# set your agent ID
$ export MC_AGENT_ID=you-local

# claim work (day1 ad hoc)
$ LEASE_ID=$(motus work claim ADHOC-DAY1-001 --intent "Day1 smoke" | awk -F': ' '/^Lease ID:/ {print $2}')

# make your change, then attach evidence
$ motus work evidence "$LEASE_ID" test_result --passed 1 --failed 0

# inspect the active packet before close
$ motus work status "$LEASE_ID" --json

# release
$ motus work release "$LEASE_ID" success

# what claim gives back
{
  "decision": "GRANTED",
  "reason_code": "GRANTED_OK",
  "lease_id": "lease-20260403-360e8b5e",
  "message": "Access granted."
}

# what changes after the first loop
$ ls -d ~/.motus .motus
~/.motus
.motus

$ motus work status "$LEASE_ID" --json
{
  "lease_id": "lease-20260403-360e8b5e",
  "lease_status": "active",
  "evidence": [
    {
      "evidence_type": "test_result",
      "test_results": {"passed": 1, "failed": 0, "skipped": 0}
    }
  ]
}

# example work item
$ LEASE_ID=$(motus work claim DOCS-ONBOARDING-001 --intent "Clarify first-run path" | awk -F': ' '/^Lease ID:/ {print $2}')

# attach proof while the work happens
$ motus work evidence "$LEASE_ID" test_result --passed 3 --failed 0

# inspect the active packet
$ motus work status "$LEASE_ID" --json

# if another actor needs to continue, handoff says:
# - objective
# - scope
# - required validation
# - expected receipt
# - failure route

# when accepted, the close record becomes the next starting point
$ motus work release "$LEASE_ID" success --json

# what the next actor trusts
handoff:
  objective: clarify first-run path
  scope: docs + build page only
  required_validation: smoke + website gates
  expected receipt: released close with accepted source state
  evidence_required: smoke transcript + gate report
  failure_route: stop and open follow-up CR if CLI must change

receipt:
  work_item_id: DOCS-ONBOARDING-001
  target_ref: refs/heads/main
  verified_source_state: refs/heads/main @ <accepted-commit-sha>
  evidence_run_hash: sha256:<evidence-bundle-hash>
  verified_by: ci@gate-public-surface
  verified_at: 2026-04-06T13:46:00Z

# day-1 JSON surfaces
$ motus work claim ADHOC-DAY1-001 --intent "Day1 smoke" --json
{
  "decision": "GRANTED",
  "reason_code": "GRANTED_OK",
  "lease_id": "lease-20260403-360e8b5e",
  "message": "Access granted."
}

$ motus work status "$LEASE_ID" --json
{
  "lease_id": "lease-20260403-360e8b5e",
  "lease_status": "active",
  "outcomes": [],
  "evidence": [
    {
      "evidence_id": "evidence-20260403-61fb7d8e",
      "evidence_type": "test_result",
      "test_results": {"passed": 1, "failed": 0, "skipped": 0}
    }
  ],
  "decisions": []
}

$ motus work release "$LEASE_ID" success --json
{
  "decision": "GRANTED",
  "reason_code": "RELEASED_OK",
  "message": "Lease released successfully.",
  "lease_status": "released"
}

# governed receipt shape
{
  "version": "0.1.0",
  "work_item_id": "CR-MOTUS-ONBOARDING-ALIGN-1",
  "to_state": "released",
  "target_ref": "refs/heads/main",
  "verified_source_state": {
    "vcs": "git",
    "commit_sha": "<accepted-commit-sha>",
    "dirty": false
  },
  "evidence_run_id": "run-20260406-onboarding-align",
  "evidence_run_hash": "sha256:<evidence-bundle-hash>",
  "verified_by": "ci@gate-public-surface",
  "verified_at": "2026-04-06T13:46:00Z"
}

The example uses placeholders on purpose. A real receipt stores the accepted commit and evidence hash, but the shape matters more than a copied literal.

# example work contract
work_id: TASK-042
scope:
  paths: ["src/auth/**", "tests/auth/**"]
checks:
  - pytest tests/auth
  - ruff check src/auth
evidence:
  - test_result: passed > 0, failed = 0
  - coverage: >= 80%
owner: @security-team

# starter handoff
Objective:
- align the onboarding surfaces so a zero-context operator can install Motus,
  run doctor, claim work, and close it with a receipt

In scope:
- packages/cli/docs/implementation/README.md
- site/build.html

Required validation:
- clean-home smoke: install -> init -> doctor -> claim -> evidence -> release
- python -m pytest packages/cli/tests/test_work_cmd.py
- bash scripts/run_gates.sh

Expected receipt:
- local day-1 close: JSON release response with decision=GRANTED and lease_status=released
- governed close: receipt with accepted source state, evidence bundle, verifier, and verification time

Evidence required:
- clean-home smoke transcript
- passing CLI test output
- website gate report

Failure route:
- if the docs require a CLI or schema change, stop and open a follow-up CR

# decorative handoff (too weak)
"Continue the onboarding docs and run the normal checks."

# useful handoff
"Align the onboarding docs and build page so a zero-context operator can run
install -> init -> doctor -> claim -> evidence -> release.
Only docs and website copy are in scope.
Run the clean-home smoke, pytest packages/cli/tests/test_work_cmd.py, and
bash scripts/run_gates.sh.
Successful close must include a released lease response, smoke transcript,
and website gate report.
If the docs require a CLI or schema change, stop and open a follow-up CR."

# Option A: Motus policy gate
$ motus policy plan --repo . --files README.md --json
$ motus policy run --repo . --files README.md --json
# deterministic evidence bundle output

# Option B: Custom gate script
# scripts/gates/gate-001-no-todo.sh
#!/usr/bin/env bash
set -euo pipefail
if grep -RInE 'TODO|FIXME' . --exclude-dir=.git --exclude-dir=.motus --exclude='*.md' >/dev/null; then
  echo "FAIL: TODO/FIXME markers found in code."
  exit 1
fi
echo "PASS: no TODO/FIXME markers in code."

# .github/workflows/gate-001.yml
name: gate-001
on:
  pull_request:
    branches: [main]

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run gate-001
        run: ./scripts/gates/gate-001-no-todo.sh

# commit your gate + workflow
$ git add scripts/gates/gate-001-no-todo.sh .github/workflows/gate-001.yml
$ git commit -m "gate: add no-todo gate and CI workflow"