arm101-cli 0.3.2__tar.gz → 0.3.3__tar.gz

{arm101_cli-0.3.2 → arm101_cli-0.3.3}/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.3] - 2026-06-20
+
+### Changed
+
+- CLAUDE.md: replaced the pre-/init seed placeholder with a full runtime guide — documents the actual repo state (mesh-agent scaffold, no arm/gripper code yet), the CLI dispatch/registration/error/output contracts, the explain-catalog lockstep rule, the agent-first rubric, and the CI-gating AgentCulture conventions.
+
+### Fixed
+
+- README: Quickstart now invokes the real console script `arm101` (was `arm101-cli`, which fails to spawn); mesh-identity line now reads `AGENTS.colleague.md` for this agent's `backend: colleague` (was a stale `CLAUDE.md` / `backend: claude`).
+- explain catalog: add a root entry for the `arm101` console-script name. The agent-first rubric's `explain_self` check runs `explain <project-script-name>` (`arm101`), which was failing because the catalog only keyed the internal prog name `arm101-cli` — a latent scaffold bug the rubric gate only exercises via the script name. Locked in by a regression test asserting every `[project.scripts]` name resolves.
+
 ## [0.3.2] - 2026-06-18
 
 ### Added

arm101_cli-0.3.3/CLAUDE.md

@@ -0,0 +1,155 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo actually is right now
+
+The package name and description say "Agent and CLI for controlling SO-ARM101
+robotic arm grippers," but **no arm/gripper control code exists yet.** What is
+here is the AgentCulture **mesh-agent scaffold** (cloned from
+`culture-agent-template`): an agent-first introspection CLI, a mesh identity, the
+vendored guildmaster skill kit, and a build/CI/deploy baseline. The gripper
+domain is the *destination*; treat the current CLI as the chassis you extend to
+get there, following the patterns below.
+
+Two consequences worth internalizing before you touch anything:
+
+- **The runtime agent prompt is `AGENTS.colleague.md`, not this file.**
+  `culture.yaml` declares `backend: colleague`, and the backend→prompt-file map
+  (see `doctor` below) resolves `colleague` → `AGENTS.colleague.md`. This
+  `CLAUDE.md` is guidance for *Claude Code working in the repo*; editing it does
+  not change the mesh agent's runtime behavior. (Note: the pre-`/init` seed text
+  and some README prose still say `backend: claude` / `CLAUDE.md` — that is stale;
+  the CHANGELOG `0.3.0` entry records the promotion to `colleague`.)
+- **The installed console script is `arm101`, not `arm101-cli`.**
+  `[project.scripts]` defines `arm101 = "arm101.cli:main"`. The README quickstart
+  (`uv run arm101-cli whoami`) is wrong and will fail with "Failed to spawn." Use
+  `uv run arm101 …` or `python -m arm101 …`. The *internal* prog name is still
+  `arm101-cli`, so `--help` text, error messages, and JSON payloads all say
+  `arm101-cli` — that string is intentional in output, just not as the binary.
+
+## Common commands
+
+```bash
+uv sync                                      # create .venv, install runtime + dev deps
+uv run pytest -n auto                         # full test suite (xdist parallel)
+uv run pytest tests/test_cli.py::test_whoami_text   # a single test
+uv run pytest -n auto --cov=arm101 --cov-report=term # tests with coverage (CI gate: fail_under=60)
+uv run arm101 whoami                          # run the CLI (note: 'arm101', not 'arm101-cli')
+
+# Lint — CI runs all of these; run them before opening a PR
+uv run black --check arm101 tests
+uv run isort --check-only arm101 tests
+uv run flake8 arm101 tests
+uv run bandit -c pyproject.toml -r arm101
+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills" "#.teken"
+
+uv run teken cli doctor . --strict            # the agent-first rubric gate (see below)
+```
+
+The runtime package has **zero third-party dependencies** (`dependencies = []`),
+on purpose. `teken` and the test/lint tools are dev-only. Keep it that way unless
+adding the gripper layer genuinely requires a hardware library — and if it does,
+isolate that dependency so the introspection CLI still imports clean.
+
+## CLI architecture
+
+Everything hangs off `arm101/cli/__init__.py:main()`. The shape is worth
+understanding before adding commands, because three cross-cutting contracts are
+enforced by tests and by the rubric gate.
+
+**Registration pattern.** `_build_parser()` imports each module under
+`arm101/cli/_commands/` and calls its `register(sub)` function, which adds a
+subparser and wires `func` + `--json` via `set_defaults`. To add a global verb:
+write `_commands/<verb>.py` with a `register()`, then add one import + call in
+`_build_parser()`. To add a **noun group** (a subcommand with its own verbs —
+this is how gripper control will likely land, e.g. `arm101 gripper open`), mirror
+`_commands/cli.py`: create the noun's subparsers with
+`parser_class=type(p)` so child parse errors route through the structured error
+contract instead of argparse's default `exit 2`.
+
+**Error contract** (`_errors.py` + the `_dispatch`/`_CliArgumentParser` plumbing).
+Every failure raises `CliError(code, message, remediation)`; `main()` catches it
+and renders via `_output.emit_error`. Any *other* exception is wrapped so no
+Python traceback ever leaks to stderr. Argparse-level errors (unknown verb,
+missing arg) are also captured: `_CliArgumentParser.error()` emits the structured
+form. Because parse errors happen before `args.json` exists, `main()` pre-scans
+raw argv for `--json` and stashes it on the class-level `_CliArgumentParser._json_hint`.
+**Handlers must raise `CliError` on failure — never `sys.exit`, never a bare
+print-and-return.**
+
+**Output contract** (`_output.py`). Results → stdout, errors/diagnostics →
+stderr, **never mixed**; JSON mode keeps the same split. Every command takes
+`--json`. Exit codes: `0` success, `1` user-input error, `2` environment error,
+`3+` reserved (constants in `_errors.py`). Use `emit_result` / `emit_error` /
+`emit_diagnostic` rather than calling `print`.
+
+**The explain catalog** (`arm101/explain/catalog.py`). `ENTRIES` is a dict keyed
+by command-path tuples (`("whoami",)`, `("cli", "overview")`, `()` and
+`("arm101-cli",)` both = root). `explain` resolves a path to verbatim markdown.
+The test `test_every_catalog_path_resolves` asserts every entry renders, but
+nothing forces a *new* verb to have one — so when you add a verb, you must update
+**three places in lockstep** or the docs silently drift: the catalog entry, the
+`_VERBS` list in `overview.py`, and the `_TEXT`/`_as_json_payload` blocks in
+`learn.py`.
+
+**Identity reading** (`whoami.py`). `culture.yaml` is parsed by hand (no YAML
+dependency, to keep runtime deps empty) — only the documented flat
+`suffix`/`backend`/`model` shape is understood; anything fancier falls back to
+defaults. `find_culture_yaml()` walks up from `__file__`, so identity is the
+agent's own even when invoked from another directory; a wheel install (no
+`culture.yaml` alongside the package) falls back to literal defaults and `doctor`
+reports a single info check.
+
+## The agent-first rubric (why some code looks the way it does)
+
+`teken cli doctor . --strict` enforces a seven-bundle "agent-first" rubric in CI,
+and several otherwise-odd shapes exist only to satisfy it — don't "simplify" them
+away:
+
+- `learn` must be ≥200 chars and mention purpose, command map, exit codes,
+  `--json`, and `explain`.
+- Any noun with action-verbs must also expose `overview` — that's the entire
+  reason the `cli` noun group exists (`cli overview` describes the CLI surface,
+  distinct from the global `overview`, which describes the *agent*).
+- Descriptive verbs must never hard-fail on a bad path — hence `overview` accepts
+  an ignored positional `target` and still exits 0.
+
+This is separate from the in-package `arm101 doctor`, which checks **agent-identity
+invariants**: `prompt-file-present` and `backend-consistency` (the
+`backend → prompt file` map is `claude`→`CLAUDE.md`, `colleague`→`AGENTS.colleague.md`,
+`acp`→`AGENTS.md`, `gemini`→`GEMINI.md`), plus `skills-present`. If you change the
+backend in `culture.yaml`, teach `doctor` the matching prompt file or
+`test_doctor_recognizes_declared_backend` fails.
+
+## AgentCulture conventions that gate CI
+
+- **Bump the version on every PR — even docs/config/CI-only changes.** The
+  `version-check` job in `.github/workflows/tests.yml` fails the PR if
+  `pyproject.toml`'s version equals `main`'s. Use the `version-bump` skill (updates
+  `pyproject.toml` + prepends a Keep-a-Changelog entry to `CHANGELOG.md`).
+- **PR lifecycle goes through the `cicd` skill**, which delegates to `devex pr` and
+  adds `status` (SonarCloud quality gate) and `await` (blocks until green / threads
+  resolved). PR comments auto-sign as `- arm101-cli (Claude)` via the skill's
+  `_resolve-nick.sh` (resolved from `culture.yaml`); don't hand-sign inside `cicd`.
+- **SonarCloud gates the `test` job** when `SONAR_TOKEN` is set
+  (`sonar.qualitygate.wait=true`). Token-less repos and fork PRs skip the scan and
+  stay green. `coverage.run.relative_files = true` is load-bearing — without it
+  `coverage.xml` paths don't map to `sonar.sources=arm101` and coverage reports 0%.
+- **PyPI publish is Trusted Publishing via OIDC** (`.github/workflows/publish.yml`):
+  push to `main` → PyPI; PR (same-repo) → a `.devN` build to TestPyPI. No tokens.
+
+## The vendored skill kit — cite-don't-import
+
+`.claude/skills/` holds skills **vendored** from `guildmaster` (a few from
+`colleague`/`devague`); `docs/skill-sources.md` is the authoritative provenance
+ledger with the per-skill re-sync procedure. **Do not hand-edit skill script
+bodies** — the only sanctioned local edits are (a) consumer-identifying prose in
+`SKILL.md` and (b) adding `type: command` to frontmatter (load-bearing: the
+culture backend's `core.skill_loader` silently skips any `SKILL.md` lacking it).
+Two tracked divergences from "always cite guildmaster" are documented in the
+ledger: the `agex`→`devex` rename and `outsource`→`ask-colleague` (vendored
+directly from `colleague` until guildmaster re-broadcasts). Reach for
+`ask-colleague` reflexively for a diverse second opinion — `review`/`explore` are
+read-only and always safe; side-effecting `write --apply`/`--pr` needs the user's
+go-ahead.

{arm101_cli-0.3.2 → arm101_cli-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arm101-cli
-Version: 0.3.2
+Version: 0.3.3
 Summary: Agent and CLI for controlling SO-ARM101 robotic arm grippers
 Project-URL: Homepage, https://github.com/agentculture/arm101-cli
 Project-URL: Issues, https://github.com/agentculture/arm101-cli/issues
@@ -24,7 +24,7 @@ Agent and CLI for controlling SO-ARM101 robotic arm grippers
 - **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
   (`afi-cli`) — the runtime package has no third-party dependencies.
 - **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
-  prompt file (`CLAUDE.md` for `backend: claude`).
+  prompt file (`AGENTS.colleague.md` for this agent's `backend: colleague`).
 - **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
   vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
 - **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
@@ -35,8 +35,8 @@ Agent and CLI for controlling SO-ARM101 robotic arm grippers
 ```bash
 uv sync
 uv run pytest -n auto                 # run the test suite
-uv run arm101-cli whoami  # identity from culture.yaml
-uv run arm101-cli learn   # self-teaching prompt (add --json)
+uv run arm101 whoami                 # identity from culture.yaml (console script is 'arm101')
+uv run arm101 learn                  # self-teaching prompt (add --json)
 uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
 ```
 

{arm101_cli-0.3.2 → arm101_cli-0.3.3}/README.md

@@ -7,7 +7,7 @@ Agent and CLI for controlling SO-ARM101 robotic arm grippers
 - **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
   (`afi-cli`) — the runtime package has no third-party dependencies.
 - **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
-  prompt file (`CLAUDE.md` for `backend: claude`).
+  prompt file (`AGENTS.colleague.md` for this agent's `backend: colleague`).
 - **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
   vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
 - **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
@@ -18,8 +18,8 @@ Agent and CLI for controlling SO-ARM101 robotic arm grippers
 ```bash
 uv sync
 uv run pytest -n auto                 # run the test suite
-uv run arm101-cli whoami  # identity from culture.yaml
-uv run arm101-cli learn   # self-teaching prompt (add --json)
+uv run arm101 whoami                 # identity from culture.yaml (console script is 'arm101')
+uv run arm101 learn                  # self-teaching prompt (add --json)
 uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
 ```
 

{arm101_cli-0.3.2 → arm101_cli-0.3.3}/arm101/explain/catalog.py

@@ -1,7 +1,10 @@
 """Markdown catalog for ``arm101-cli explain <path>``.
 
 Each entry is verbatim markdown. Keys are command-path tuples. The empty tuple
-and ``("arm101-cli",)`` both resolve to the root entry.
+resolves to the root entry, as do both names the CLI answers to: the console
+script ``("arm101",)`` (from ``[project.scripts]``) and the internal prog name
+``("arm101-cli",)``. The script-name key is load-bearing — the agent-first
+rubric's ``explain_self`` check runs ``explain <project-script-name>``.
 
 Keep bodies self-contained: an agent reading one entry should get enough
 context without chaining reads.
@@ -118,6 +121,7 @@ itself (distinct from the global `overview`, which describes the agent).
 
 ENTRIES: dict[tuple[str, ...], str] = {
     (): _ROOT,
+    ("arm101",): _ROOT,
     ("arm101-cli",): _ROOT,
     ("whoami",): _WHOAMI,
     ("learn",): _LEARN,

{arm101_cli-0.3.2 → arm101_cli-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arm101-cli"
-version = "0.3.2"
+version = "0.3.3"
 description = "Agent and CLI for controlling SO-ARM101 robotic arm grippers"
 readme = "README.md"
 license = "MIT"

{arm101_cli-0.3.2 → arm101_cli-0.3.3}/tests/test_cli.py

@@ -113,3 +113,26 @@ def test_every_catalog_path_resolves(capsys: pytest.CaptureFixture[str]) -> None
         rc = main(["explain", *path])
         assert rc == 0, f"explain {' '.join(path)} failed"
         capsys.readouterr()
+
+
+def test_explain_resolves_console_script_name(capsys: pytest.CaptureFixture[str]) -> None:
+    """Every `[project.scripts]` name must have an explain catalog entry.
+
+    The agent-first rubric's `explain_self` check runs `explain
+    <project-script-name>` — the console-script key (`arm101`), not the internal
+    prog name (`arm101-cli`). They differ here, so this guards the catalog
+    against drifting away from the script and re-breaking the rubric gate.
+    """
+    import tomllib
+    from pathlib import Path
+
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    if not pyproject.is_file():  # pragma: no cover - source checkout only
+        pytest.skip("pyproject.toml not alongside tests")
+    scripts = tomllib.loads(pyproject.read_text(encoding="utf-8"))["project"]["scripts"]
+    catalog = set(known_paths())
+    for name in scripts:
+        assert (name,) in catalog, f"explain catalog missing entry for console script '{name}'"
+        rc = main(["explain", name])
+        assert rc == 0
+        assert capsys.readouterr().out.startswith("#")

{arm101_cli-0.3.2 → arm101_cli-0.3.3}/uv.lock

@@ -2,6 +2,37 @@ version = 1
 revision = 3
 requires-python = ">=3.12"
 
+[[package]]
+name = "arm101-cli"
+version = "0.3.3"
+source = { editable = "." }
+
+[package.dev-dependencies]
+dev = [
+    { name = "bandit" },
+    { name = "black" },
+    { name = "flake8" },
+    { name = "isort" },
+    { name = "pytest" },
+    { name = "pytest-cov" },
+    { name = "pytest-xdist" },
+    { name = "teken" },
+]
+
+[package.metadata]
+
+[package.metadata.requires-dev]
+dev = [
+    { name = "bandit", specifier = ">=1.7.5" },
+    { name = "black", specifier = ">=23.7.0" },
+    { name = "flake8", specifier = ">=6.1" },
+    { name = "isort", specifier = ">=5.12.0" },
+    { name = "pytest", specifier = ">=8.0" },
+    { name = "pytest-cov", specifier = ">=4.1" },
+    { name = "pytest-xdist", specifier = ">=3.0" },
+    { name = "teken", specifier = ">=0.8" },
+]
+
 [[package]]
 name = "bandit"
 version = "1.9.4"
@@ -154,37 +185,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/61/e8/cb8e80d6f9f55b99588625062822bf946cf03ed06315df4bd8397f5632a1/coverage-7.14.0-py3-none-any.whl", hash = "sha256:8de5b61163aee3d05c8a2beab6f47913df7981dad1baf82c414d99158c286ab1", size = 211764, upload-time = "2026-05-10T18:02:29.538Z" },
 ]
 
-[[package]]
-name = "arm101-cli"
-version = "0.3.2"
-source = { editable = "." }
-
-[package.dev-dependencies]
-dev = [
-    { name = "bandit" },
-    { name = "black" },
-    { name = "flake8" },
-    { name = "isort" },
-    { name = "pytest" },
-    { name = "pytest-cov" },
-    { name = "pytest-xdist" },
-    { name = "teken" },
-]
-
-[package.metadata]
-
-[package.metadata.requires-dev]
-dev = [
-    { name = "bandit", specifier = ">=1.7.5" },
-    { name = "black", specifier = ">=23.7.0" },
-    { name = "flake8", specifier = ">=6.1" },
-    { name = "isort", specifier = ">=5.12.0" },
-    { name = "pytest", specifier = ">=8.0" },
-    { name = "pytest-cov", specifier = ">=4.1" },
-    { name = "pytest-xdist", specifier = ">=3.0" },
-    { name = "teken", specifier = ">=0.8" },
-]
-
 [[package]]
 name = "execnet"
 version = "2.1.2"

arm101_cli-0.3.2/CLAUDE.md

@@ -1,28 +0,0 @@
-# CLAUDE.md — seed / bootstrap placeholder
-
-> **This is a self-initializing seed, not a finished runtime prompt.**
-> Run `/init` (or describe the agent's domain to your AI assistant) to
-> re-initialize this file into a full runtime prompt, using the description
-> below and the scaffolded repo as context.
-
-## Agent
-
-This repository hosts the **arm101-cli** agent.
-
-## Description
-
-Agent and CLI for controlling SO-ARM101 robotic arm grippers
-
-## Re-init instruction
-
-This file is a seed. To expand it into your full runtime prompt:
-
-1. Open this repo in Claude Code (or your preferred AI assistant).
-2. Run `/init` — the assistant will read the repo, incorporate the description
-   above, and replace this seed with a complete `CLAUDE.md`.
-3. Commit the result.
-
-Until you run `/init`, `arm101-cli` satisfies the `steward doctor`
-`prompt-file-present` and `backend-consistency` invariants (a `CLAUDE.md`
-exists and `culture.yaml` declares `backend: claude`) but the prompt is not
-yet tailored to this agent's domain.