arm101-cli 0.4.0__tar.gz → 0.5.0__tar.gz

arm101_cli-0.5.0/.devague/current

@@ -0,0 +1 @@
+arm101-cli-grows-its-first-hardware-verbs-arm101-f

arm101_cli-0.5.0/.devague/current_plan

@@ -0,0 +1 @@
+arm101-cli-grows-its-first-hardware-verbs-arm101-f

arm101_cli-0.5.0/.devague/frames/arm101-cli-grows-its-first-hardware-verbs-arm101-f.json

@@ -0,0 +1,362 @@
+{
+  "slug": "arm101-cli-grows-its-first-hardware-verbs-arm101-f",
+  "title": "arm101-cli grows its first hardware verbs: 'arm101 find-port' detects which USB serial port the SO-101 arm is on, and 'arm101 calibrate' records each joint's range of motion \u2014 both following the existing agent-first error/output/explain contracts.",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-06-26T21:26:56Z",
+  "updated": "2026-06-26T21:41:33Z",
+  "claims": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "arm101-cli grows its first hardware verbs: 'arm101 find-port' detects which USB serial port the SO-101 arm is on, and 'arm101 calibrate' records each joint's range of motion \u2014 both following the existing agent-first error/output/explain contracts.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h5",
+          "text": "Both 'arm101 find-port' and 'arm101 calibrate' exist as real registered verbs that pass the in-package doctor, the teken cli doctor --strict rubric gate, and the full pytest suite with no hardware attached.",
+          "status": "rejected"
+        },
+        {
+          "id": "h6",
+          "text": "All three verbs (find-port, calibrate, setup-motors) exist as registered verbs that pass the in-package doctor, teken cli doctor --strict, and the CI pytest suite (surface + contracts + profile round-trip + find-port enumeration) with no hardware attached.",
+          "status": "confirmed"
+        },
+        {
+          "id": "h7",
+          "text": "calibrate's and setup-motors' real motor-I/O paths have been exercised against a physical SO-101 follower arm at least once before the feature is considered done.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "An operator (human or mesh agent) bringing up a physical SO-101 arm for the first time, who needs to know which /dev port the arm is on and to calibrate joint ranges before any motion.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h14",
+          "text": "The verbs serve both a human at a terminal and a mesh agent: every prompt-driven flow (find-port --detect, setup-motors) has a documented non-interactive and/or --json path, so an agent is never forced through a blocking TTY prompt to obtain a result.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c3",
+      "kind": "before_state",
+      "text": "arm101-cli has zero hardware verbs \u2014 it can introspect its own identity but cannot see, address, or calibrate the physical arm. Operators copy lerobot-find-port / lerobot-calibrate workflows by hand.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h15",
+          "text": "On current main, 'arm101 --help' lists no find-port/calibrate/setup-motors verbs and no module under arm101/ opens a serial port \u2014 verifiable by grep before the change lands.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c4",
+      "kind": "after_state",
+      "text": "Running 'arm101 find-port' identifies the arm's serial port; 'arm101 calibrate' walks the operator through recording min/mid/max for each of the 6 joints and persists a named calibration profile that later motion commands consume.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [
+        {
+          "id": "h3",
+          "text": "calibrate's persisted profile round-trips: writing then reading a profile yields identical per-joint min/mid/max, and the schema is documented where motion commands will later read it.",
+          "status": "proposed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "Calibration is the precondition for any safe motion: without per-joint min/max, position commands can drive a joint into a hard stop. find-port removes the brittle hand-copied device path. These two verbs are the on-ramp from 'introspection chassis' to 'controls a real arm'.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "Not in scope: actual teleoperation, training, or motion-execution verbs; the leader-arm variant's differently-geared motors; and setup-motors (writing motor IDs/baudrates to EEPROM) unless explicitly pulled in. This spec is find-port + calibrate for one follower arm.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [
+        {
+          "id": "q2",
+          "text": "Is setup-motors (writing per-motor IDs/baudrates to EEPROM) in scope, or a deliberate follow-up? It's the third LeRobot verb and a prerequisite to a fresh arm working at all.",
+          "resolved": false,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "An operator with a connected SO-101 runs 'arm101 find-port' and gets the right /dev path, then 'arm101 calibrate my_arm' and a calibration profile file is written; both commands honor --json, exit-code policy, and never leak a traceback. Tests + rubric gate pass with no hardware attached.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c8",
+      "kind": "non_goal",
+      "text": "Does not vendor or wrap the full LeRobot stack; arm101-cli stays a standalone CLI, not a LeRobot plugin.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "The hardware-touching layer (serial enumeration + Feetech motor I/O) is isolated behind an adapter module so the introspection CLI still imports with zero third-party deps; hardware libs install via an optional extra (e.g. pip install '.[hardware]').",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h1",
+          "text": "After the feature lands, 'python -c \"import arm101.cli\"' still succeeds in an env with no third-party packages installed, and the hardware adapter import is lazy (only triggered when a hardware verb actually talks to the bus).",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c10",
+      "kind": "requirement",
+      "text": "Both verbs follow the existing contracts verbatim: register() under _commands/, CliError-only failures, emit_result/emit_error split, a --json mode, and lockstep updates to the explain catalog + overview _VERBS + learn _TEXT.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [
+        {
+          "id": "h2",
+          "text": "A new test asserts find-port and calibrate each: raise CliError (never sys.exit), keep stdout/stderr split in both text and --json modes, and that the explain catalog, overview _VERBS, and learn _TEXT all reference the new verbs (the lockstep-or-drift invariant).",
+          "status": "rejected"
+        },
+        {
+          "id": "h8",
+          "text": "A test asserts find-port, calibrate, and setup-motors each raise CliError (never sys.exit), keep the stdout/stderr split in both text and --json modes, and that the explain catalog, overview _VERBS, and learn _TEXT all reference all three verbs (the lockstep-or-drift invariant).",
+          "status": "proposed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c11",
+      "kind": "decision",
+      "text": "find-port offers a non-interactive enumeration mode (list candidate serial ports, agent-friendly, default) AND an interactive disconnect-diff mode (--detect) that prompts the operator to unplug the arm and resolves the single changed port \u2014 mirroring lerobot-find-port.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h4",
+          "text": "find-port's default (enumeration) mode is fully non-interactive and agent-safe (no blocking prompt), and the interactive --detect mode degrades to a clear CliError when run without a TTY rather than hanging.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c12",
+      "kind": "assumption",
+      "text": "Serial-port enumeration can start as stdlib-only on Linux (glob /dev/ttyACM*, /dev/ttyUSB*, /dev/serial/by-id) so find-port needs no third-party dep; pyserial is only pulled in if/when cross-platform enumeration is required.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [
+        {
+          "id": "q3",
+          "text": "risk: Stdlib /dev globbing is Linux-only; macOS operators (the LeRobot docs show /dev/tty.usbmodem...) would get nothing until pyserial lands. Need to decide whether macOS support is required at launch.",
+          "resolved": false,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c13",
+      "kind": "assumption",
+      "text": "calibrate persists a JSON profile keyed by a user-given arm id (e.g. 'arm101 calibrate my_follower') under a calibrations/ dir, storing per-joint {min, mid, max} for the 6 named joints (shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper).",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [
+        {
+          "id": "q4",
+          "text": "Where should calibration profiles live and be keyed \u2014 a calibrations/ dir next to the package, an XDG/user config dir, or under culture.yaml? And is the arm id a required positional or defaulted?",
+          "resolved": false,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c14",
+      "kind": "decision",
+      "text": "Real Feetech STS3215 motor I/O lives behind the isolated hardware adapter; with no hardware/SDK present, calibrate fails cleanly via CliError (exit 2, env error) \u2014 it does not stub fake readings. The CLI surface, profile schema, and adapter interface are fully built and tested without hardware.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [
+        {
+          "id": "q1",
+          "text": "Should calibrate fail-clean without hardware (define surface now, real I/O later), or must this spec include real Feetech STS3215 reads tested against a physical arm before it's 'done'?",
+          "resolved": false,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c15",
+      "kind": "boundary",
+      "text": "In scope: find-port, calibrate, and setup-motors for ONE follower SO-101 arm, Linux at launch. Out of scope: the leader-arm variant (differently-geared motors), teleoperation, training, and motion-execution verbs.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h12",
+          "text": "The leader-arm variant, teleoperation, training, and motion-execution verbs are entirely absent from this spec's deliverable \u2014 no half-built stubs for them ship.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c16",
+      "kind": "success_signal",
+      "text": "An operator with a connected SO-101 runs: find-port (returns the right /dev path), calibrate <id> (records real STS3215 min/mid/max to a profile), setup-motors (sets per-motor id/baudrate). Surface + contract + profile round-trip + find-port enumeration tests and the rubric gate pass in CI with NO hardware; real motor I/O is validated manually against a physical arm before 'done'.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h13",
+          "text": "CI is green on the surface/contract/round-trip/enumeration tests with no hardware attached, AND a manual run-log against a physical follower arm records find-port, calibrate, and setup-motors working end-to-end.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c17",
+      "kind": "decision",
+      "text": "calibrate performs REAL Feetech STS3215 reads via the Feetech SDK, lazy-imported from the optional [hardware] install extra. With no bus/SDK present it raises CliError (exit 2, env error). The hardware adapter is tested in CI against a fake/in-memory bus; real reads are validated manually against a physical arm, and that manual validation is part of 'done'.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c18",
+      "kind": "decision",
+      "text": "Calibration profiles persist as JSON under an XDG/user config dir ($XDG_CONFIG_HOME or ~/.config/arm101/calibrations/<id>.json). The arm id is a REQUIRED positional argument, mirroring lerobot --robot.id. Profiles are reinstall-safe and not committed to the repo.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c19",
+      "kind": "requirement",
+      "text": "setup-motors walks the operator through one-motor-at-a-time EEPROM id/baudrate assignment (gripper=6 down to shoulder_pan=1), prompting to connect each motor alone before pressing Enter \u2014 mirroring lerobot-setup-motors. It is interactive and degrades to a clear CliError when run without a TTY.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h9",
+          "text": "setup-motors never proceeds to write EEPROM without an explicit operator Enter per motor, and a non-TTY invocation exits with CliError(2) rather than hanging or auto-writing.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c20",
+      "kind": "decision",
+      "text": "Serial-port enumeration is Linux stdlib-only at launch (glob /dev/ttyACM*, /dev/ttyUSB*, /dev/serial/by-id). Optional [mac] and [win] install extras exist as placeholders; on macOS/Windows the hardware verbs return a clean 'unsupported for now' CliError rather than silently finding nothing.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c21",
+      "kind": "after_state",
+      "text": "find-port returns the arm's serial port; calibrate <id> walks the operator through recording min/mid/max for each of the 6 joints (shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper) and persists a named profile that later motion commands consume; setup-motors assigns each motor's id/baudrate in EEPROM.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h10",
+          "text": "calibrate's persisted profile round-trips: writing then reading a profile yields identical per-joint min/mid/max, and the schema is documented where motion commands will later read it.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c22",
+      "kind": "why_it_matters",
+      "text": "Calibration is the precondition for safe motion: without per-joint min/max, position commands can drive a joint into a hard stop. find-port removes the brittle hand-copied device path, and setup-motors makes a fresh-from-factory arm addressable at all. Together these three verbs are the on-ramp from 'introspection chassis' to 'controls a real arm'.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h16",
+          "text": "The persisted profile's per-joint min/max is stored in the documented units/encoding that a future motion verb will read to clamp commands \u2014 the schema is the actual safety contract, not merely a record.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c23",
+      "kind": "requirement",
+      "text": "All three verbs follow the existing contracts verbatim: register() under _commands/, CliError-only failures, the emit_result/emit_error stdout-stderr split, a --json mode, and lockstep updates to the explain catalog + overview _VERBS + learn _TEXT.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h11",
+          "text": "A test asserts find-port, calibrate, and setup-motors each raise CliError (never sys.exit), keep the stdout/stderr split in both text and --json modes, and that the explain catalog, overview _VERBS, and learn _TEXT all reference all three verbs (the lockstep-or-drift invariant).",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    }
+  ],
+  "open_vagueness": []
+}