agent-lifecycle 0.2.0__tar.gz → 0.2.1__tar.gz

{agent_lifecycle-0.2.0 → agent_lifecycle-0.2.1}/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.2.1] - 2026-06-10
+
+### Added
+
+### Changed
+
+- **Expanded `CLAUDE.md` from the bootstrap seed into a full runtime prompt**
+  (via `/init`). It now documents the build/test/lint/rubric commands, the CLI
+  dispatch architecture (the `--json` argv pre-peek, the `register()` pattern,
+  `CliError` traceback suppression), the two cross-cutting contracts (error
+  shape + stdout/stderr split), the four parallel registries a new verb must
+  update, the identity/`whoami` source-of-truth, and the version-bump /
+  cite-don't-import / rename / CI conventions. Flags that the stated
+  process-lifecycle-supervisor domain is **not built yet** — the package ships
+  only the template's introspection CLI today — so a future instance does not
+  mistake the scaffold for the runtime.
+
+### Fixed
+
 ## [0.2.0] - 2026-06-06
 
 ### Added

agent_lifecycle-0.2.1/CLAUDE.md

@@ -0,0 +1,166 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+`agent-lifecycle` is an AgentCulture mesh agent, scaffolded from
+`culture-agent-template`. Its **stated domain** (see `README.md` / `pyproject.toml`)
+is a *harness- and transport-agnostic agent runtime: supervise an agent's process
+lifecycle independent of its harness (brain) and its transport (IRC/Slack/agtag).*
+
+**That runtime is not built yet.** Today the package ships only the template's
+**agent-first introspection CLI** — `whoami`, `learn`, `explain`, `overview`,
+`doctor`, and the `cli` noun group. These verbs describe the agent to other
+agents; none of them supervise processes. When you add the lifecycle-supervisor
+domain, it goes in *new* noun groups alongside the existing introspection verbs,
+not by rewriting them.
+
+The repo is still self-describing as a "clonable template" in several user-facing
+strings (`learn`, `explain` catalog, `overview`). That phrasing is scaffold
+residue — as the real domain lands, update those strings to describe the runtime.
+
+## Commands
+
+This is a `uv` project, Python 3.12+, runtime `dependencies = []` (the CLI is
+cited from `teken`/`agentfront`, not imported).
+
+```bash
+uv sync                                       # install (incl. dev group)
+uv run pytest -n auto                          # full test suite (parallel)
+uv run pytest tests/test_cli.py::test_whoami_text -v   # a single test
+uv run agent-lifecycle whoami                  # run the CLI (or: python -m agent_lifecycle)
+
+# Lint gate (exactly what CI runs — see .github/workflows/tests.yml `lint` job):
+uv run black --check agent_lifecycle tests
+uv run isort --check-only agent_lifecycle tests
+uv run flake8 agent_lifecycle tests
+uv run bandit -c pyproject.toml -r agent_lifecycle
+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills" "#.teken"
+
+# The agent-first rubric gate (CI blocks on this):
+uv run teken cli doctor . --strict
+```
+
+Note: the `teken` binary was renamed to `agentfront`; `teken` still works as a
+deprecated alias, which is what CI and these docs invoke.
+
+The `run-tests` skill (`.claude/skills/run-tests/`) wraps pytest with
+`--ci` / `--quick` / `--coverage` presets if you prefer; plain `uv run pytest`
+is fine.
+
+## Architecture
+
+### CLI dispatch (`agent_lifecycle/cli/`)
+
+`cli/__init__.py:main()` is the single entry point. The flow:
+
+1. **Peek argv for `--json` before parsing** — parse-time errors happen before
+   `args.json` exists, so `main()` sets `_CliArgumentParser._json_hint` (a
+   class-level flag) so even argparse errors honor JSON mode.
+2. **`_build_parser()`** registers every verb. Each command module exposes a
+   `register(sub)` function; `_build_parser` calls them in turn. **To add a verb,
+   write the module, import it in `_build_parser`, and call its `register`.** The
+   subparsers are built with `parser_class=_CliArgumentParser` so the error
+   contract propagates to nested nouns too (see the `cli` noun, which re-passes
+   `type(p)` to its own sub-subparsers).
+3. **`_dispatch()`** invokes `args.func(args)`. Handlers return `None`/`int`
+   (success) or raise `CliError`. Any *other* exception is caught and wrapped
+   into a `CliError` so **no Python traceback ever leaks to stderr**.
+
+### Two cross-cutting contracts (don't break these — tests and the rubric enforce them)
+
+- **Error contract** (`cli/_errors.py`): every failure is a `CliError(code,
+  message, remediation)`. Exit codes: `0` success, `1` user-input error, `2`
+  environment/setup error, `3+` reserved. Text-mode errors render as
+  `error: <msg>` + `hint: <remediation>` on stderr — the `hint:` prefix is
+  required by the agent-first rubric.
+- **Stream split** (`cli/_output.py`): **results to stdout, diagnostics/errors to
+  stderr, never mixed.** Every verb supports `--json`; JSON payloads go to the
+  same split streams. Use `emit_result` / `emit_error` / `emit_diagnostic` — do
+  not `print()`.
+
+### The parallel registries that must stay in sync
+
+A new verb touches **four** places, and the introspection verbs read each other.
+Forgetting one is the most common bug here:
+
+1. The command module + its `register()` call in `_build_parser`.
+2. `explain/catalog.py` — add an `ENTRIES[("yourverb",)]` markdown entry.
+   `test_every_catalog_path_resolves` walks `known_paths()`, and
+   `overview_cli_noun_exists` rubric check expects coverage.
+3. `cli/_commands/overview.py` — the `_VERBS` / `_ARTIFACTS` lists feed both the
+   global `overview` and `cli overview`.
+4. `cli/_commands/learn.py` — both `_TEXT` and `_as_json_payload()` list the
+   command map; the rubric requires `learn` ≥200 chars and mentions of purpose,
+   exit codes, `--json`, and `explain`.
+
+**Rubric invariant for nouns:** any noun with action-verbs must also expose
+`overview`. The `cli` noun exists today purely to satisfy that
+(`overview_cli_noun_exists`) — it has no action-verbs but still ships
+`cli overview`. Mirror that pattern for any new noun group.
+
+### Identity (`whoami.py` is the source of truth)
+
+`whoami.find_culture_yaml()` walks **up from `__file__`** (not CWD) to find the
+agent's *own* `culture.yaml`, and `read_agent_fields()` parses `suffix`/`backend`/
+`model` from the first agent block **with a hand-rolled parser (no YAML dep)** to
+keep runtime deps empty. `doctor.py`, `overview.py`, and `learn.py` all build on
+`whoami.report()`. A wheel install ships no `culture.yaml`, so both `whoami` and
+`doctor` fall back gracefully (literal defaults / a single info check, exit 0).
+
+`doctor` mirrors the invariants `steward doctor` checks: **prompt-file-present**
+(declared `backend` → its prompt file: `claude`→`CLAUDE.md`, `acp`→`AGENTS.md`,
+`gemini`→`GEMINI.md`), **backend-consistency**, plus **skills-present**.
+
+## Conventions
+
+### Every PR bumps the version (CI-enforced)
+
+The `version-check` job fails any PR where `pyproject.toml`'s version equals
+`main` — **including docs/config/CI-only changes.** Use the `version-bump` skill
+(`major|minor|patch`); it updates `pyproject.toml` and prepends a Keep-a-Changelog
+entry to `CHANGELOG.md`. `__version__` is read from installed package metadata
+(`importlib.metadata`), so it's not edited by hand.
+
+### Skills are vendored cite-don't-import
+
+`.claude/skills/` holds 11 skills copied (not depended-on) from **guildmaster**
+(the skills supplier; `steward` keeps only the alignment role). `docs/skill-sources.md`
+is the authoritative provenance ledger and re-sync procedure — **read it before
+touching anything under `.claude/skills/`.** Script bodies are kept verbatim; only
+consumer-identifying *prose* in `SKILL.md` is adapted, and every `SKILL.md` must
+carry `type: command` (load-bearing — `core.skill_loader` silently skips files
+without it). Tracked local divergences (e.g. `agex`→`devex`, `outsource`→
+`ask-colleague`) are documented there.
+
+PR work uses the `cicd` skill (layered on `devex pr`; adds SonarCloud gating via
+`status`/`await`). Cross-repo issues + mesh messages use the `communicate` skill
+(`agtag`-backed). Both `devex` and `agtag` are expected on PATH; `colleague` is
+optional (only `ask-colleague` needs it).
+
+### Renaming the package (when forking this as a new agent)
+
+The name `agent-lifecycle` / `agent_lifecycle` is hard-coded in ~30 tracked
+files (CLI strings, `_ISSUES_URL`, tests, `sonar-project.properties`, `README`,
+catalog markdown). List every occurrence first:
+
+```bash
+git grep -lI 'agent-lifecycle\|agent_lifecycle'
+```
+
+Then rename the package dir, update `culture.yaml` (`suffix` + `backend`), rewrite
+this `CLAUDE.md`, and re-vendor only the skills you need.
+
+## CI / deploy
+
+- **`tests.yml`**: `test` (pytest + coverage → SonarCloud, gated on `SONAR_TOKEN`
+  so fork PRs / token-less repos stay green), `lint` (black/isort/flake8/bandit/
+  markdownlint + the rubric gate), `version-check` (PR-only).
+- **`publish.yml`**: TestPyPI on PRs from the same repo, PyPI on push to `main` —
+  both via Trusted Publishing (OIDC, no stored token). Triggered only by changes
+  under `pyproject.toml` / `agent_lifecycle/**`.
+- **SonarCloud** (`sonar-project.properties`, key `agentculture_agent-lifecycle`):
+  `sonar.qualitygate.wait=true` blocks CI on a red gate. `relative_files = true`
+  in `[tool.coverage.run]` is required — without it coverage maps to absolute
+  paths and Sonar silently reports 0%.

{agent_lifecycle-0.2.0 → agent_lifecycle-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle
-Version: 0.2.0
+Version: 0.2.1
 Summary: Harness- and transport-agnostic agent runtime: supervises an agent's process lifecycle independent of its harness (brain) and transport (IRC/Slack/agtag).
 Project-URL: Homepage, https://github.com/agentculture/agent-lifecycle
 Project-URL: Issues, https://github.com/agentculture/agent-lifecycle/issues

{agent_lifecycle-0.2.0 → agent_lifecycle-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-lifecycle"
-version = "0.2.0"
+version = "0.2.1"
 description = "Harness- and transport-agnostic agent runtime: supervises an agent's process lifecycle independent of its harness (brain) and transport (IRC/Slack/agtag)."
 readme = "README.md"
 license = "MIT"

{agent_lifecycle-0.2.0 → agent_lifecycle-0.2.1}/uv.lock

@@ -2,6 +2,37 @@ version = 1
 revision = 3
 requires-python = ">=3.12"
 
+[[package]]
+name = "agent-lifecycle"
+version = "0.2.1"
+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 = "agent-lifecycle"
-version = "0.2.0"
-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"

agent_lifecycle-0.2.0/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 **agent-lifecycle** agent.
-
-## Description
-
-Harness- and transport-agnostic agent runtime: supervises an agent's process lifecycle independent of its harness (brain) and transport (IRC/Slack/agtag).
-
-## 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`, `agent-lifecycle` 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.