steward-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{steward_cli-0.2.0 → steward_cli-0.3.0}/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.0] - 2026-04-26
+
+### Added
+
+- `steward doctor --scope siblings` walks every `culture.yaml` in the workspace, scores each declared agent against a corpus-derived baseline, writes per-target feedback into `<target>/docs/steward/steward-suggestions.md` (gated by a marker line so hand-written content there is preserved), and refreshes `docs/perfect-patient.md` in the steward checkout. Diagnostic-only — corpus mode never exits non-zero on per-agent drift.
+- `docs/perfect-patient.md` — committed placeholder; populated on each `--scope siblings` run with required/recommended `culture.yaml` fields, the common skills baseline, common `CLAUDE.md` sections, and corpus stats.
+- `steward/cli/_commands/_corpus.py` — pure helpers (`discover_agents`, `synthesize_baseline`, `render_perfect_patient`, `score_culture_yaml_shape`, `score_agent_against_baseline`, `write_repo_report`) used by `doctor --scope siblings`. Tested in isolation by `tests/test_corpus.py`.
+- `tests/test_corpus.py` and `tests/test_cli_doctor_siblings.py` — unit + end-to-end coverage for corpus mode (discovery handles both `agents:` lists and flat root-level `suffix:` shapes; baseline classification by frequency; report writer is idempotent and preserves hand-written content; JSON output shape; empty-workspace diagnostic; --no-write-reports / --no-refresh-perfect-patient gates).
+
+### Changed
+
+- **Renamed `steward verify` → `steward doctor`** (single-repo mode). Same checks (`portability`, `skills-convention`), same flags (`--json`, `--check`), same exit semantics (non-zero on findings). New flags: `--scope {self,siblings}` (default `self` is backward-compatible with `verify`), `--workspace-root`, `--no-write-reports`, `--no-refresh-perfect-patient`, `--perfect-patient-out`. No `verify` alias kept — this is a breaking CLI change.
+- Added `pyyaml>=6.0` as the first runtime dependency. Required to parse sibling `culture.yaml` manifests in corpus mode; the existing `agent-config` skill already shells out to a Python+PyYAML one-liner, so the dep was implicit.
+- `docs/sibling-pattern.md` and `CLAUDE.md` Roadmap section rewritten to describe `doctor`'s two scopes (self / siblings) and reposition the planned `--apply` repair handlers as the next layer.
+
 ## [0.2.0] - 2026-04-26
 
 ### Added
@@ -71,7 +86,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
-- bump.py docstring no longer overstates what gets updated; the __init__.py rewrite is conditional and is a no-op for steward (3143024085).
+- bump.py docstring no longer overstates what gets updated; the `__init__.py` rewrite is conditional and is a no-op for steward (3143024085).
 
 ## [0.1.0] - 2026-04-26
 

{steward_cli-0.2.0 → steward_cli-0.3.0}/CLAUDE.md

@@ -25,7 +25,9 @@ steward/                    # Python package (pip install steward-cli)
     ├── _errors.py          # StewardError + EXIT_USER_ERROR / EXIT_ENV_ERROR
     ├── _output.py          # emit_result / emit_error / emit_diagnostic
     └── _commands/          # subcommand modules; each has register(sub) + handler
-        └── show.py         # `steward show <target>` → wraps agent-config skill
+        ├── show.py         # `steward show <target>` → wraps agent-config skill
+        ├── doctor.py       # `steward doctor` → single-repo or corpus diagnosis
+        └── _corpus.py      # corpus helpers used by `doctor --scope siblings`
 tests/                      # pytest suite
 .claude/skills/             # see "Skills convention" below
 .github/workflows/          # tests.yml + publish.yml (OIDC Trusted Publishing)
@@ -63,23 +65,35 @@ Steward is a "skills supplier" for the Culture mesh. When a skill stabilizes her
 
 ## Roadmap (CLI surface)
 
-The current CLI ships one verb (`steward show`). The next two verbs are
-`verify` (read-only diagnosis against the AgentCulture sibling pattern) and
-`doctor` (diagnose-and-fix; default dry-run, `--apply` to commit). Together
-they encode steward's mission as code instead of prose:
-
-- `steward verify <path>` — score a target repo against `docs/sibling-pattern.md`.
-  Aggregates findings across all selected checks, then exits non-zero if any
-  finding was reported. Human-readable findings go to stderr; `--json` emits
-  the structured findings list to stdout. The first cut runs steward's own
-  vendored `.claude/skills/pr-review/scripts/portability-lint.sh` against the
-  target (so the target doesn't need to vendor it), plus a skills-convention
-  check (every `SKILL.md` has a sibling `scripts/` entry-point).
-- `steward doctor <path>` — repair what `verify` flagged, where the repair is
-  unambiguous (missing `scripts/` directory, missing `.markdownlint-cli2.yaml`,
-  missing `.claude/skills.local.yaml.example`, etc.). Larger emissions (CLI
-  scaffold) land later as additional repair handlers, eventually consuming
-  `../afi-cli/afi/cite/_engine.py` rather than re-implementing it.
+The CLI ships two verbs today: `steward show` and `steward doctor`. Doctor
+runs in two modes — single-repo diagnosis (the original "verify" flow,
+folded into doctor) and corpus mode (the agent-iteration flow). The
+`--apply` repair mode is the next layer on top.
+
+- `steward doctor <path>` (default `--scope self`) — score a target repo
+  against `docs/sibling-pattern.md`. Aggregates findings across all
+  selected checks, then exits non-zero if any finding was reported.
+  Human-readable findings go to stderr; `--json` emits the structured
+  findings list to stdout. Today: `portability` (runs steward's own
+  vendored `.claude/skills/pr-review/scripts/portability-lint.sh` against
+  the target, so the target doesn't need to vendor it) and
+  `skills-convention` (every `SKILL.md` has a sibling `scripts/`
+  entry-point and matching frontmatter `name`).
+- `steward doctor --scope siblings` — walks every `culture.yaml` in the
+  workspace (`<workspace-root>/*/culture.yaml`, sibling-only by default),
+  tallies field/skill/CLAUDE.md-section frequency across the corpus to
+  synthesize `docs/perfect-patient.md`, scores every declared agent
+  against that baseline, and writes per-target feedback into
+  `<target>/docs/steward/steward-suggestions.md` (gated by a marker line
+  so hand-written content in that path is preserved). Diagnostic-only —
+  exits 0 even when individual agents drift from the baseline; that is
+  reported in the per-target file rather than as a CLI failure.
+- `steward doctor --apply` *(planned)* — repair what diagnosis flagged,
+  where the repair is unambiguous (missing `scripts/` directory, missing
+  `.markdownlint-cli2.yaml`, missing `.claude/skills.local.yaml.example`,
+  etc.). Larger emissions (CLI scaffold) land later as additional repair
+  handlers, eventually consuming `../afi-cli/afi/cite/_engine.py` rather
+  than re-implementing it.
 
 Per-skill upstreams (which repo owns the canonical copy of `version-bump`,
 `pr-review`, etc.) are recorded in `docs/skill-sources.md` so `doctor` can

{steward_cli-0.2.0 → steward_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steward-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Steward — aligns and maintains resident agents across Culture projects.
 Project-URL: Homepage, https://github.com/agentculture/steward
 Project-URL: Issues, https://github.com/agentculture/steward/issues
@@ -13,6 +13,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development
 Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
 Description-Content-Type: text/markdown
 
 # steward

steward_cli-0.3.0/docs/perfect-patient.md

@@ -0,0 +1,35 @@
+# Perfect patient
+
+> This file is auto-generated by `steward doctor --scope siblings`. The
+> committed copy is a placeholder; run the command locally to populate it
+> with real corpus statistics from the `culture.yaml` files in your
+> workspace.
+>
+> The baseline is descriptive, not prescriptive: it describes what a
+> typical healthy agent looks like in the current corpus, so drift can
+> be spotted. Edit by hand only if you intend to ratchet the bar —
+> `steward doctor --scope siblings` overwrites this file.
+
+## Required `culture.yaml` fields
+
+Populated on first `steward doctor --scope siblings` run.
+
+## Recommended `culture.yaml` fields
+
+Populated on first `steward doctor --scope siblings` run.
+
+## Common skills baseline
+
+Populated on first `steward doctor --scope siblings` run.
+
+## Recommended skills
+
+Populated on first `steward doctor --scope siblings` run.
+
+## Common `CLAUDE.md` sections
+
+Populated on first `steward doctor --scope siblings` run.
+
+## Corpus stats
+
+Populated on first `steward doctor --scope siblings` run.

{steward_cli-0.2.0 → steward_cli-0.3.0}/docs/sibling-pattern.md

@@ -2,13 +2,22 @@
 
 The shape every AgentCulture sibling repo (`steward`, `cfafi`, `ghafi`, `daria`,
 …) is expected to wear. This document is the single source of truth that
-`steward verify` and `steward doctor` consume.
+`steward doctor` consumes.
 
 The companion file `sibling-pattern.json` (TBD; emit from this doc) is the
-machine-readable form. Until it lands, the checks `verify` runs are hard-coded
-in `steward/cli/_commands/verify.py`; this document remains the human-readable
+machine-readable form. Until it lands, the checks `doctor` runs are hard-coded
+in `steward/cli/_commands/doctor.py`; this document remains the human-readable
 contract that those hard-coded checks are expected to honor.
 
+`steward doctor` runs in two modes:
+
+- **`--scope self <target>`** (default) — the single-repo invariants below
+  (portability, skills-convention).
+- **`--scope siblings`** — walks every `culture.yaml` in the workspace, scores
+  each declared agent against a corpus-derived baseline
+  (`docs/perfect-patient.md`, regenerated on each run), and writes a per-target
+  report into `<target>/docs/steward/steward-suggestions.md`.
+
 ## Required artifacts
 
 | # | Artifact | Path | Why |
@@ -29,9 +38,9 @@ contract that those hard-coded checks are expected to honor.
 ## Invariants (machine-checkable)
 
 The full set of invariants the AgentCulture sibling pattern asserts. The
-**Status** column reflects what is wired into `steward verify` *today*; items
-marked `(planned)` are described here as the contract `verify` is expected to
-grow into.
+**Status** column reflects what is wired into `steward doctor --scope self`
+*today*; items marked `(planned)` are described here as the contract `doctor`
+is expected to grow into.
 
 - **portability** *(implemented as `--check portability`)* — no
   `/home/<user>/...` paths in tracked files; no `~/.<dotfile>` config refs in
@@ -52,10 +61,11 @@ grow into.
 
 ## Repairs (machine-fixable, run by `steward doctor`)
 
-`steward doctor` is **not yet implemented** (see `CLAUDE.md`'s Roadmap
-section); the table below is the contract it will honor when it lands. A
-repair is included only if it is **deterministic and idempotent**. Where the
-right answer depends on judgement, `doctor` will report the gap and stop.
+`steward doctor --apply` is **not yet implemented** (see `CLAUDE.md`'s
+Roadmap section); the table below is the contract it will honor when it
+lands. A repair is included only if it is **deterministic and idempotent**.
+Where the right answer depends on judgement, `doctor` will report the gap
+and stop.
 
 | Invariant violated | Planned repair |
 |--------------------|----------------|

{steward_cli-0.2.0 → steward_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steward-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Steward — aligns and maintains resident agents across Culture projects."
 readme = "README.md"
 license = "MIT"
@@ -13,7 +13,9 @@ classifiers = [
     "Topic :: Software Development",
     "Intended Audience :: Developers",
 ]
-dependencies = []
+dependencies = [
+    "pyyaml>=6.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/agentculture/steward"

{steward_cli-0.2.0 → steward_cli-0.3.0}/steward/cli/__init__.py

@@ -32,8 +32,8 @@ class _StewardArgumentParser(argparse.ArgumentParser):
 def _build_parser() -> argparse.ArgumentParser:
     # Deferred import to avoid coupling the parser module to the command modules
     # at import time (matches afi-cli's pattern; cheap insurance).
+    from steward.cli._commands import doctor as _doctor_cmd
     from steward.cli._commands import show as _show_cmd
-    from steward.cli._commands import verify as _verify_cmd
 
     parser = _StewardArgumentParser(
         prog="steward",
@@ -47,7 +47,7 @@ def _build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command", parser_class=_StewardArgumentParser)
 
     _show_cmd.register(sub)
-    _verify_cmd.register(sub)
+    _doctor_cmd.register(sub)
 
     return parser