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

steward_cli-0.2.0/.claude/skills/doc-test-alignment/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: doc-test-alignment
+description: >
+  Verify that committed docs (README.md, CLAUDE.md, SKILL.md descriptions) still
+  describe what the code and tests actually do. Use at the end of a plan, before
+  PR creation, or when the user says "check doc-test alignment", "verify docs",
+  or "do the docs still match the code". STUB — `scripts/check.sh` exits with a
+  not-yet-implemented error today; the contract for what it will do lives in
+  this file.
+---
+
+# doc-test-alignment (stub)
+
+This skill is a stub. The real workflow is intentionally not yet implemented —
+the file exists so that `steward verify` can find it and so contributors who
+land here know it is on the roadmap, not forgotten.
+
+## How to run
+
+`scripts/check.sh` is the entry point. Today it prints a not-yet-implemented
+notice and exits non-zero. When the workflow lands, the script will gate
+PR-readiness on the alignment contract below; until then, treat any green
+exit code from this script as a bug.
+
+## What it will check
+
+The skill is the contract for four narrow alignments. README.md command
+examples must still execute against the current checkout and produce output
+that matches the surrounding prose. The "build/test/publish" command lines in
+CLAUDE.md must do the same. For each `.claude/skills/<name>/`, the SKILL.md
+`description` frontmatter must agree with what the scripts under
+`scripts/` actually do — surfacing disagreements (e.g. SKILL.md claims the
+skill bumps versions but `scripts/` has no bump script). And for each test,
+the test name should still describe the assertions the test makes — flagging
+drift where the name advertises a feature the assertions no longer touch.
+
+## Why it ships as a stub
+
+Each of those four checks is independently non-trivial. Shipping a partial
+implementation would either silently pass when it shouldn't, or false-positive
+on intentional doc-vs-code differences. The right path is to land the checks
+one at a time, with their own tests, behind a
+`steward verify --check doc-test-alignment` flag. The parent verbs (`verify`,
+`doctor`) are named in the "Roadmap" section of `CLAUDE.md`; the broader
+sibling-pattern contract lives in `docs/sibling-pattern.md`.
+
+## What this stub guarantees today
+
+- The skill directory exists, so `steward verify`'s skills-convention check
+  finds the standard layout (SKILL.md + `scripts/` with an entry-point).
+- `scripts/check.sh` is the entry-point script, satisfying the steward skills
+  convention requirement that every skill ships an executable script.
+- This `SKILL.md` is the contract for what the skill will do — when the
+  implementation lands, it must satisfy this description or the description
+  must move first.

steward_cli-0.2.0/.claude/skills/doc-test-alignment/scripts/check.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# doc-test-alignment skill — entry point.
+#
+# STUB: the real workflow is not implemented yet. This script exists so the
+# steward skills convention is satisfied (every skill ships an executable
+# entry-point script); when the real implementation lands here, it must
+# satisfy the contract documented in ../SKILL.md.
+#
+# Exits 2 (EXIT_USER_ERROR-ish for "you asked for something that isn't
+# wired up yet") so callers can tell the difference between "checks passed"
+# (would be 0) and "stub".
+
+set -euo pipefail
+
+cat >&2 <<'EOF'
+doc-test-alignment: not yet implemented.
+
+This skill is a stub; the contract for what `check.sh` will assert lives in
+.claude/skills/doc-test-alignment/SKILL.md. Until the implementation lands,
+treat any green exit code from this script as a bug.
+
+Roadmap: see CLAUDE.md ("Roadmap (CLI surface)") and docs/sibling-pattern.md.
+EOF
+exit 2

{steward_cli-0.1.2 → steward_cli-0.2.0}/.markdownlint-cli2.yaml

@@ -1,6 +1,6 @@
 # markdownlint-cli2 config for steward.
-# markdownlint-cli2 stops walking at the git root, so the user's global
-# ~/.markdownlint-cli2.yaml isn't picked up from inside the repo.
+# markdownlint-cli2 stops walking at the git root, so a per-user global
+# config in the home directory isn't picked up from inside the repo.
 # Mirrors the afi-cli / cfafi preset for workspace consistency.
 
 config:

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

@@ -5,6 +5,44 @@ 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.0] - 2026-04-26
+
+### Added
+
+- `steward verify <path>` — read-only diagnosis of a sibling repo against the
+  AgentCulture sibling pattern. Two checks today: `portability` (runs steward's
+  own vendored `portability-lint.sh --all` with `cwd=<target>`, so the target
+  doesn't need to vendor it and `verify` only ever executes a known-trusted
+  script) and `skills-convention` (every `SKILL.md` has a sibling `scripts/`
+  directory and a matching frontmatter `name`). Aggregates findings across all
+  selected checks; human-readable findings go to stderr, `--json` puts the
+  structured findings list on stdout. `--check <name>` repeatable. Exits 1 if
+  any finding was reported.
+- `docs/sibling-pattern.md` — single source of truth for the AgentCulture
+  sibling pattern (12 required artifacts, 5 machine-checkable invariants,
+  5 deterministic repairs). Consumed by `steward verify`; will be consumed
+  by the future `steward doctor`.
+- `docs/skill-sources.md` — per-skill upstream declarations and vendoring
+  policy so `doctor` can vendor deterministically.
+- `.claude/skills/doc-test-alignment/` — stub skill describing the intended
+  doc/test alignment workflow. Implementation TBD.
+- `tests/test_skills_convention.py` — repo-level invariants for steward's own
+  skills (every skill has SKILL.md + scripts/, frontmatter name matches dir,
+  no per-user/home-dir paths in skill scripts).
+- `tests/test_cli_verify.py` — end-to-end tests for the new verb, including a
+  dogfood test that runs `steward verify` against steward itself.
+
+### Changed
+
+- `CLAUDE.md` gains a "Roadmap (CLI surface)" section naming `verify` and
+  `doctor` as the next two verbs.
+- `.markdownlint-cli2.yaml` header comment reworded to avoid tripping the
+  portability lint with its own self-reference (caught by the new
+  `tests/test_cli_verify.py` dogfood test on first run).
+- `tests/test_cli.py` help-output assertion loosened to match individual
+  verb names instead of the literal `{show}` group, so adding verbs doesn't
+  break it.
+
 ## [0.1.2] - 2026-04-26
 
 ### Added

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

@@ -61,6 +61,30 @@ Per-machine paths (Culture server manifest location, sibling-project paths, etc.
 
 Steward is a "skills supplier" for the Culture mesh. When a skill stabilizes here, the next step is propagating it to sibling projects (`culture`, `daria`, etc.) — the all-backends rule applied to skills.
 
+## 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.
+
+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
+vendor deterministically.
+
 ## Working with Culture from here
 
 Steward will need to read or write Culture artifacts (agent definitions, server configs, mesh links). Useful entry points:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steward-cli
-Version: 0.1.2
+Version: 0.2.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

steward_cli-0.2.0/docs/sibling-pattern.md

@@ -0,0 +1,80 @@
+# AgentCulture sibling pattern
+
+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.
+
+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
+contract that those hard-coded checks are expected to honor.
+
+## Required artifacts
+
+| # | Artifact | Path | Why |
+|---|----------|------|-----|
+| 1 | Toolchain | `pyproject.toml` (hatchling, Python ≥3.12, zero runtime deps where possible) | Uniform install/build/publish across the mesh. |
+| 2 | Top-level package | `<pkg>/__init__.py`, `<pkg>/__main__.py` | `__version__` via `importlib.metadata`; `python -m <pkg>` works. |
+| 3 | CLI scaffolding | `<pkg>/cli/__init__.py`, `cli/_errors.py`, `cli/_output.py`, `cli/_commands/` | The afi-cli pattern: structured errors, stdout/stderr split, `--json`. |
+| 4 | Agent-first verbs | `cli/_commands/{learn,explain,whoami}.py` | `learn`/`explain` are the agent-affordance verbs; `whoami` is the smallest auth probe. |
+| 5 | Mutation safety | Any write verb defaults to dry-run; `--apply` to commit | Agents call CLIs in loops; safe-by-default is mandatory. |
+| 6 | Tests | `tests/test_cli_*.py`, pytest-xdist, coverage | CI gate; no untested verb ships. |
+| 7 | CI | `.github/workflows/tests.yml`, `.github/workflows/publish.yml` | Tests + lint + version-check; PyPI/TestPyPI via Trusted Publishing. |
+| 8 | Changelog | `CHANGELOG.md` (Keep-a-Changelog) | Bumped on every PR by the `version-bump` skill. |
+| 9 | Skills | `.claude/skills/<name>/SKILL.md` + `scripts/` entry-point per skill | Convention: no external path deps, no per-user dotfile refs. |
+| 10 | Per-machine config | `.claude/skills.local.yaml.example` (committed) + `.claude/skills.local.yaml` (git-ignored) | Skills read the local file, fall back to the example. |
+| 11 | Lint configs | `.flake8`, `.markdownlint-cli2.yaml` (repo-local) | No reliance on per-user home-directory configs. |
+| 12 | `CLAUDE.md` | Project shape, build/test/publish commands, conventions | What future Claude instances need that isn't discoverable from a 30-second `ls`. |
+
+## 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.
+
+- **portability** *(implemented as `--check portability`)* — no
+  `/home/<user>/...` paths in tracked files; no `~/.<dotfile>` config refs in
+  committed `.md`/`.yaml`/`.toml`/`.json`/`.jsonc` outside the carve-outs
+  (`~/.claude/skills/.../scripts/`, `~/.culture/`).
+  *Source:* `.claude/skills/pr-review/scripts/portability-lint.sh`.
+- **skills-convention** *(implemented as `--check skills-convention`)* —
+  every `.claude/skills/<name>/SKILL.md` has a sibling
+  `.claude/skills/<name>/scripts/` directory, **and** the SKILL.md frontmatter
+  `name` equals the directory name. (The "every skill has at least one
+  entry-point script" invariant is satisfied by the directory existing today
+  to keep the check noise-free; tightening to "directory has ≥1 file" is
+  *(planned)*.)
+- **changelog-format** *(planned)* — `CHANGELOG.md` has at least one
+  `## [x.y.z] - YYYY-MM-DD` heading.
+- **lint-config-local** *(planned)* — `.markdownlint-cli2.yaml` exists at the
+  repo root (no reliance on per-user home configs).
+
+## 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.
+
+| Invariant violated | Planned repair |
+|--------------------|----------------|
+| `.claude/skills/<name>/scripts/` missing | Create the empty directory + a stub entry-point script. |
+| `.markdownlint-cli2.yaml` missing | Vendor steward's copy verbatim. |
+| `.claude/skills.local.yaml.example` missing | Vendor a minimal template documenting the `culture_server_yaml` and `sibling_projects` keys. |
+| `CHANGELOG.md` missing | Create a Keep-a-Changelog skeleton with one `## [Unreleased]` heading. |
+| `SKILL.md` frontmatter `name` ≠ dir name | Reported only — too many false-positive renames to auto-correct. |
+| Hard-coded `/home/...` path in tracked file | Reported only — fix requires understanding intent. |
+
+## Skill upstream policy
+
+Per-skill upstream declarations live in `docs/skill-sources.md`. `doctor`
+consults that file when vendoring a skill into a target sibling: each skill
+has exactly one canonical source repo, and `doctor` copies from there.
+
+## Out of scope (for the pattern, not for steward)
+
+- Pre-commit hooks (suggested but not required; siblings vary on this).
+- Specific CI runners or Python versions beyond ≥3.12.
+- Anything Culture-mesh-specific (server manifest, agent definitions) — that
+  belongs in `docs/` of the relevant Culture-side project, not in this pattern.

steward_cli-0.2.0/docs/skill-sources.md

@@ -0,0 +1,43 @@
+# Skill upstream sources
+
+Each skill has exactly one canonical source repo. `steward doctor` consults
+this file when vendoring a skill into a target sibling so the choice is
+deterministic.
+
+When a skill exists in multiple repos, the **upstream** column wins. Other
+repos are downstream copies that may lag and should periodically re-sync from
+upstream.
+
+| Skill | Upstream | Downstream copies (known) | Notes |
+|-------|----------|---------------------------|-------|
+| `version-bump` | `steward` (`.claude/skills/version-bump/`) | `cfafi`, `afi-cli` | Pure Python, prepends Keep-a-Changelog entry; no per-repo customization needed. |
+| `pr-review` | `steward` (`.claude/skills/pr-review/`) | `cfafi` (variant) | Steward owns the canonical workflow; downstream copies may add reviewer-specific wiring (Qodo/Copilot, etc.). |
+| `agent-config` | `steward` (`.claude/skills/agent-config/`) | — | Steward-specific (resolves Culture agent suffixes); not portable as-is. |
+| `doc-test-alignment` | `steward` (`.claude/skills/doc-test-alignment/`) | — | Stub; real implementation TBD. |
+| `cfafi`, `cfafi-write` | `cfafi` (`.claude/skills/cfafi*/`) | — | CloudFlare-specific; not vendored elsewhere. |
+| `poll` | `cfafi` (`.claude/skills/poll/`) | — | Background-reviewer subagent; candidate for promotion to `steward` if it stabilizes. |
+
+## Vendoring policy
+
+- **Cite, don't import.** Skills are copied into the consuming repo, not
+  symlinked or installed as a dependency. Each consumer owns and may modify
+  their copy.
+- **Re-sync explicitly.** When upstream changes, downstream copies do not
+  auto-update. `steward doctor --skill <name>` is the intended re-sync path
+  (TBD).
+- **Diverge intentionally.** A downstream copy may diverge for repo-specific
+  reasons (e.g. `cfafi`'s `pr-review` adds CloudFlare-API reviewers). Record
+  the divergence in the downstream `SKILL.md`'s frontmatter `description`.
+
+## When a skill should be promoted upstream
+
+A skill currently owned downstream (e.g. `poll` in `cfafi`) should be promoted
+to `steward` when:
+
+1. At least one other sibling has copy-pasted it, OR
+2. Its scripts have no repo-specific assumptions (no hard-coded API
+   credentials, no per-product paths), AND
+3. Its `SKILL.md` describes a pattern (not a single product's workflow).
+
+Promotion is a manual decision — `steward doctor` will not move skills
+between repos.

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

@@ -1,6 +1,6 @@
 [project]
 name = "steward-cli"
-version = "0.1.2"
+version = "0.2.0"
 description = "Steward — aligns and maintains resident agents across Culture projects."
 readme = "README.md"
 license = "MIT"

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

@@ -33,6 +33,7 @@ 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 show as _show_cmd
+    from steward.cli._commands import verify as _verify_cmd
 
     parser = _StewardArgumentParser(
         prog="steward",
@@ -46,6 +47,7 @@ def _build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command", parser_class=_StewardArgumentParser)
 
     _show_cmd.register(sub)
+    _verify_cmd.register(sub)
 
     return parser
 

steward_cli-0.2.0/steward/cli/_commands/verify.py

@@ -0,0 +1,228 @@
+"""``steward verify`` — read-only diagnosis of a sibling repo against the
+AgentCulture sibling pattern (`docs/sibling-pattern.md`).
+
+First cut: two checks — `portability` (delegates to steward's own vendored
+`portability-lint.sh --all` run with the target as cwd) and `skills-convention`
+(every `SKILL.md` has a sibling `scripts/` directory). All findings are
+aggregated; the command exits non-zero if any check produced findings.
+`--json` emits structured findings to stdout.
+
+Future checks land here behind `--check <name>` flags. The full set of
+invariants is enumerated in `docs/sibling-pattern.md` ("Invariants").
+"""
+
+from __future__ import annotations
+
+import argparse
+import json as json_mod
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from steward.cli._errors import EXIT_ENV_ERROR, EXIT_USER_ERROR, StewardError
+from steward.cli._output import emit_diagnostic, emit_result
+
+FRONTMATTER_NAME_RE = re.compile(r"^name:\s*(\S+)\s*$", re.MULTILINE)
+PORTABILITY_LINT_RELPATH = Path(".claude/skills/pr-review/scripts/portability-lint.sh")
+
+
+@dataclass
+class Finding:
+    check: str
+    path: str
+    message: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"check": self.check, "path": self.path, "message": self.message}
+
+
+def _resolve_target(raw: str) -> Path:
+    target = Path(raw).expanduser().resolve()
+    if not target.is_dir():
+        raise StewardError(
+            code=EXIT_USER_ERROR,
+            message=f"target is not a directory: {raw}",
+            remediation="pass a path to a sibling repo checkout",
+        )
+    return target
+
+
+def _find_git_root(start: Path) -> Path | None:
+    for directory in (start, *start.parents):
+        if (directory / ".git").exists():
+            return directory
+    return None
+
+
+def _resolve_steward_portability_lint() -> Path:
+    """Locate steward's own vendored ``portability-lint.sh``.
+
+    Walks up from cwd, but **stops at the git repository boundary** (mirrors
+    the resolver in :mod:`steward.cli._commands.show`). Running steward's
+    own copy — instead of executing whatever script the *target* repo ships —
+    keeps ``verify`` to a fixed, known-trusted code surface.
+    """
+    start = Path.cwd().resolve()
+    repo_root = _find_git_root(start)
+
+    current = start
+    while True:
+        candidate = current / PORTABILITY_LINT_RELPATH
+        if candidate.is_file():
+            return candidate
+        if current == repo_root or current.parent == current:
+            break
+        if repo_root is None:
+            break
+        current = current.parent
+
+    hint = f"run from inside a Steward git checkout that contains {PORTABILITY_LINT_RELPATH}"
+    raise StewardError(
+        code=EXIT_ENV_ERROR,
+        message="steward's portability-lint.sh not found",
+        remediation=hint,
+    )
+
+
+def _check_skills_convention(target: Path) -> list[Finding]:
+    """Every `.claude/skills/<name>/SKILL.md` has a sibling `scripts/` dir,
+    and the SKILL.md frontmatter `name` matches the directory name."""
+    findings: list[Finding] = []
+    skills_dir = target / ".claude" / "skills"
+    if not skills_dir.is_dir():
+        return findings  # No skills is fine; not every sibling has them yet.
+    for skill_dir in sorted(p for p in skills_dir.iterdir() if p.is_dir()):
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.is_file():
+            findings.append(
+                Finding(
+                    check="skills-convention",
+                    path=str(skill_dir.relative_to(target)),
+                    message="missing SKILL.md",
+                )
+            )
+            continue
+        if not (skill_dir / "scripts").is_dir():
+            findings.append(
+                Finding(
+                    check="skills-convention",
+                    path=str(skill_dir.relative_to(target)),
+                    message="missing scripts/ directory",
+                )
+            )
+        match = FRONTMATTER_NAME_RE.search(skill_md.read_text())
+        if not match:
+            findings.append(
+                Finding(
+                    check="skills-convention",
+                    path=str(skill_md.relative_to(target)),
+                    message="no `name:` field in frontmatter",
+                )
+            )
+        elif match.group(1) != skill_dir.name:
+            findings.append(
+                Finding(
+                    check="skills-convention",
+                    path=str(skill_md.relative_to(target)),
+                    message=f"frontmatter name {match.group(1)!r} != dir {skill_dir.name!r}",
+                )
+            )
+    return findings
+
+
+def _check_portability(target: Path) -> list[Finding]:
+    """Run steward's own vendored ``portability-lint.sh --all`` against the
+    target's working tree.
+
+    The script is resolved from the steward checkout (not the target), then
+    invoked with ``cwd=target`` so its ``git ls-files`` lists target files.
+    This means ``verify`` works whether or not the target has vendored its
+    own copy of the lint, and limits subprocess execution to a known-trusted
+    script.
+    """
+    script = _resolve_steward_portability_lint()
+    # bandit S603: argv is a fixed two-element list (resolved script path +
+    # literal "--all"); no shell, no expansion. Script path comes from
+    # _resolve_steward_portability_lint() which is constrained to the
+    # current git checkout, so an attacker can't substitute a different
+    # portability-lint.sh from an ancestor directory.
+    try:
+        completed = subprocess.run(  # noqa: S603
+            [str(script), "--all"],
+            cwd=target,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except OSError as exc:
+        raise StewardError(
+            code=EXIT_ENV_ERROR,
+            message=f"could not execute {script}: {exc}",
+            remediation="ensure the script is executable (chmod +x)",
+        ) from exc
+    if completed.returncode == 0:
+        return []
+    return [
+        Finding(
+            check="portability",
+            path=".",
+            message=(completed.stdout + completed.stderr).strip()
+            or f"portability-lint exited {completed.returncode}",
+        )
+    ]
+
+
+CHECKS = {
+    "skills-convention": _check_skills_convention,
+    "portability": _check_portability,
+}
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "verify",
+        help="Diagnose a sibling repo against the AgentCulture sibling pattern.",
+        description=(
+            "Read-only diagnosis. Aggregates findings across selected checks, "
+            "then exits 0 if there are none and 1 if there are any. See "
+            "docs/sibling-pattern.md for the invariants."
+        ),
+    )
+    parser.add_argument(
+        "target",
+        help="Path to a sibling repo directory.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit findings as JSON to stdout instead of human-readable lines on stderr.",
+    )
+    parser.add_argument(
+        "--check",
+        action="append",
+        choices=sorted(CHECKS.keys()),
+        help="Run only the named check (repeatable). Default: run all checks.",
+    )
+    parser.set_defaults(func=_handle)
+
+
+def _handle(args: argparse.Namespace) -> int:
+    target = _resolve_target(args.target)
+    selected = args.check or sorted(CHECKS.keys())
+    findings: list[Finding] = []
+    for name in selected:
+        findings.extend(CHECKS[name](target))
+
+    if args.json:
+        # Structured output is the command's *result* — goes to stdout per
+        # the steward stdout/stderr split.
+        emit_result(json_mod.dumps([f.to_dict() for f in findings], indent=2))
+    elif findings:
+        # Human-readable findings are diagnostics — stderr by default.
+        for f in findings:
+            emit_diagnostic(f"{f.check}: {f.path}: {f.message}")
+    else:
+        emit_result(f"verify clean ({len(selected)} checks against {target})")
+
+    return 0 if not findings else 1

{steward_cli-0.1.2 → steward_cli-0.2.0}/tests/test_cli.py

@@ -30,7 +30,9 @@ def test_no_args_prints_help_and_exits_zero(capsys: pytest.CaptureFixture[str])
     assert rc == 0
     captured = capsys.readouterr()
     assert "usage: steward" in captured.out
-    assert "{show}" in captured.out
+    # Subcommand list — match loosely so adding more verbs doesn't break this.
+    assert "show" in captured.out
+    assert "verify" in captured.out
 
 
 def test_unknown_command_exits_with_user_error_code(

steward_cli-0.2.0/tests/test_cli_verify.py

@@ -0,0 +1,78 @@
+"""End-to-end tests for `steward verify`."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from steward.cli import main
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def test_verify_against_steward_repo_passes(capsys: pytest.CaptureFixture[str]) -> None:
+    """Steward should pass `steward verify` on itself.
+
+    This is the dog-food test: if steward can't verify steward, the pattern
+    isn't internally consistent.
+    """
+    rc = main(["verify", str(REPO_ROOT)])
+    captured = capsys.readouterr()
+    assert rc == 0, f"verify failed:\n{captured.out}\n{captured.err}"
+    assert "verify clean" in captured.out
+
+
+def test_verify_unknown_target_fails_user_error(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A non-directory target exits 1 with a structured error on stderr."""
+    rc = main(["verify", "/nonexistent/path/that/should/not/exist"])
+    captured = capsys.readouterr()
+    assert rc == 1
+    assert "error: target is not a directory" in captured.err
+
+
+def test_verify_json_output_is_parseable(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """`--json` emits a JSON list (empty when clean)."""
+    rc = main(["verify", "--json", str(REPO_ROOT)])
+    captured = capsys.readouterr()
+    assert rc == 0
+    parsed = json.loads(captured.out)
+    assert isinstance(parsed, list)
+    assert parsed == []
+
+
+def test_verify_skills_convention_catches_missing_scripts(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Skill with SKILL.md but no scripts/ dir is reported on stderr."""
+    skill = tmp_path / ".claude" / "skills" / "broken"
+    skill.mkdir(parents=True)
+    (skill / "SKILL.md").write_text("---\nname: broken\ndescription: x\n---\n")
+    rc = main(["verify", "--check", "skills-convention", str(tmp_path)])
+    captured = capsys.readouterr()
+    assert rc == 1
+    # Findings are diagnostics → stderr, per the stdout/stderr split in
+    # steward.cli._output.
+    assert "missing scripts/ directory" in captured.err
+    assert captured.out == ""
+
+
+def test_verify_skills_convention_catches_name_mismatch(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """SKILL.md whose frontmatter name differs from the dir name is reported."""
+    skill = tmp_path / ".claude" / "skills" / "real-name"
+    (skill / "scripts").mkdir(parents=True)
+    (skill / "SKILL.md").write_text("---\nname: wrong-name\ndescription: x\n---\n")
+    rc = main(["verify", "--check", "skills-convention", str(tmp_path)])
+    captured = capsys.readouterr()
+    assert rc == 1
+    assert "frontmatter name 'wrong-name' != dir 'real-name'" in captured.err
+    assert captured.out == ""

steward_cli-0.2.0/tests/test_skills_convention.py

@@ -0,0 +1,106 @@
+"""Repo-level invariants for steward's own skills.
+
+These are the same checks `steward verify` will run against any sibling repo,
+applied here to steward itself so we eat our own dog food and CI catches
+regressions before PR review.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILLS_DIR = REPO_ROOT / ".claude" / "skills"
+FRONTMATTER_NAME_RE = re.compile(r"^name:\s*(\S+)\s*$", re.MULTILINE)
+
+
+def _skill_dirs() -> list[Path]:
+    return sorted(p for p in SKILLS_DIR.iterdir() if p.is_dir())
+
+
+@pytest.mark.parametrize("skill_dir", _skill_dirs(), ids=lambda p: p.name)
+def test_skill_has_skill_md(skill_dir: Path) -> None:
+    """Every skill directory ships a SKILL.md."""
+    assert (skill_dir / "SKILL.md").is_file(), f"missing SKILL.md in {skill_dir}"
+
+
+@pytest.mark.parametrize("skill_dir", _skill_dirs(), ids=lambda p: p.name)
+def test_skill_has_scripts_directory(skill_dir: Path) -> None:
+    """Every skill directory ships a `scripts/` directory.
+
+    Per the skills convention in CLAUDE.md: "Following the skill should be
+    'run this script,' not 'do these ten manual steps.'" An empty `scripts/`
+    (with `.gitkeep`) is acceptable for stub skills that document the
+    contract before the implementation lands.
+    """
+    scripts = skill_dir / "scripts"
+    assert scripts.is_dir(), f"missing scripts/ in {skill_dir}"
+
+
+@pytest.mark.parametrize("skill_dir", _skill_dirs(), ids=lambda p: p.name)
+def test_skill_frontmatter_name_matches_dir(skill_dir: Path) -> None:
+    """SKILL.md frontmatter `name` equals the directory name."""
+    text = (skill_dir / "SKILL.md").read_text()
+    match = FRONTMATTER_NAME_RE.search(text)
+    assert match, f"no `name:` field in {skill_dir / 'SKILL.md'}"
+    assert (
+        match.group(1) == skill_dir.name
+    ), f"SKILL.md name {match.group(1)!r} != dir {skill_dir.name!r}"
+
+
+_HOME_RE = re.compile(r"/home/[a-z][a-z0-9_-]+/")
+# Match every per-user dotfile ref; carve_outs below allow specific shapes.
+_DOTFILE_RE = re.compile(r"~/\.[A-Za-z][A-Za-z0-9_-]*")
+_DOTFILE_CARVE_OUTS = (
+    re.compile(r"~/\.claude/skills/[^\s\"]+/scripts/"),
+    re.compile(r"~/\.culture/"),
+)
+
+
+def _scan_line_for_offenses(path: Path, lineno: int, line: str) -> list[str]:
+    offenses: list[str] = []
+    if _HOME_RE.search(line):
+        offenses.append(f"{path}:{lineno}: hard-coded /home/ path: {line.strip()}")
+    for hit in _DOTFILE_RE.finditer(line):
+        if any(c.match(line, hit.start()) for c in _DOTFILE_CARVE_OUTS):
+            continue
+        offenses.append(f"{path}:{lineno}: per-user dotfile ref: {line.strip()}")
+    return offenses
+
+
+def _read_text_or_none(path: Path) -> str | None:
+    try:
+        return path.read_text()
+    except UnicodeDecodeError:
+        return None
+
+
+def _iter_script_files() -> list[Path]:
+    files: list[Path] = []
+    for skill_dir in _skill_dirs():
+        for path in (skill_dir / "scripts").rglob("*"):
+            if path.is_file():
+                files.append(path)
+    return files
+
+
+def test_no_per_user_paths_in_skill_scripts() -> None:
+    """No `/home/<user>/...` or per-user `~/.dotfile` refs in skill scripts.
+
+    This is the same rule `portability-lint.sh` enforces on PR diffs, applied
+    here at the unit-test level so a single-file change can never reintroduce
+    a leak that's missed by the diff lint (e.g. a brand-new file added in a
+    commit but the lint only ran on a different range).
+    """
+    offenders: list[str] = []
+    for path in _iter_script_files():
+        text = _read_text_or_none(path)
+        if text is None:
+            continue
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            offenders.extend(_scan_line_for_offenses(path, lineno, line))
+
+    assert not offenders, "skills/scripts portability violations:\n  " + "\n  ".join(offenders)

{steward_cli-0.1.2 → steward_cli-0.2.0}/uv.lock

@@ -439,7 +439,7 @@ wheels = [
 
 [[package]]
 name = "steward-cli"
-version = "0.1.2"
+version = "0.2.0"
 source = { editable = "." }
 
 [package.dev-dependencies]