workledger-cli 0.8.0__tar.gz → 0.9.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/CHANGELOG.md +18 -0
  2. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/PKG-INFO +22 -29
  3. workledger_cli-0.9.0/README.md +54 -0
  4. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/pyproject.toml +1 -1
  5. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/tests/test_cli.py +2 -2
  6. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/tests/test_cli_introspection.py +3 -3
  7. workledger_cli-0.9.0/tests/test_self_description.py +294 -0
  8. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/uv.lock +1 -1
  9. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/__init__.py +1 -1
  10. workledger_cli-0.9.0/workledger/_about.py +27 -0
  11. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/__init__.py +9 -10
  12. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/_store.py +11 -2
  13. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/append.py +2 -2
  14. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/cli.py +4 -4
  15. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/doctor.py +2 -2
  16. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/explain.py +2 -2
  17. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/learn.py +34 -21
  18. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/list.py +1 -1
  19. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/overview.py +25 -9
  20. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/whoami.py +4 -3
  21. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_errors.py +1 -1
  22. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/explain/__init__.py +1 -1
  23. workledger_cli-0.9.0/workledger/explain/catalog.py +182 -0
  24. workledger_cli-0.8.0/README.md +0 -61
  25. workledger_cli-0.8.0/workledger/explain/catalog.py +0 -167
  26. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/agent-config/SKILL.md +0 -0
  27. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/agent-config/data/backend-fingerprints.yaml +0 -0
  28. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/agent-config/scripts/show.sh +0 -0
  29. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/ask-colleague/SKILL.md +0 -0
  30. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/ask-colleague/prompts/explore.md +0 -0
  31. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/ask-colleague/prompts/review.md +0 -0
  32. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/ask-colleague/prompts/write.md +0 -0
  33. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/ask-colleague/scripts/ask-colleague.sh +0 -0
  34. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/assign-to-workforce/SKILL.md +0 -0
  35. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh +0 -0
  36. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/challenge/SKILL.md +0 -0
  37. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/SKILL.md +0 -0
  38. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/scripts/_resolve-nick.sh +0 -0
  39. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/scripts/portability-lint.sh +0 -0
  40. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/scripts/pr-reply.sh +0 -0
  41. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/scripts/pr-status.sh +0 -0
  42. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/cicd/scripts/workflow.sh +0 -0
  43. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/SKILL.md +0 -0
  44. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/fetch-issues.sh +0 -0
  45. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/mesh-message.sh +0 -0
  46. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/post-comment.sh +0 -0
  47. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/post-issue.sh +0 -0
  48. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/templates/skill-new-brief.md +0 -0
  49. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/communicate/scripts/templates/skill-update-brief.md +0 -0
  50. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/deviate/SKILL.md +0 -0
  51. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/doc-test-alignment/SKILL.md +0 -0
  52. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/doc-test-alignment/scripts/check.sh +0 -0
  53. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/pypi-maintainer/SKILL.md +0 -0
  54. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/pypi-maintainer/scripts/switch-source.sh +0 -0
  55. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/recall/SKILL.md +0 -0
  56. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/recall/scripts/recall.sh +0 -0
  57. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/remember/SKILL.md +0 -0
  58. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/remember/scripts/remember.sh +0 -0
  59. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/run-tests/SKILL.md +0 -0
  60. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/run-tests/scripts/test.sh +0 -0
  61. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/scope/SKILL.md +0 -0
  62. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/sonarclaude/SKILL.md +0 -0
  63. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/sonarclaude/scripts/sonar.sh +0 -0
  64. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/spec-to-plan/SKILL.md +0 -0
  65. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/spec-to-plan/scripts/spec-to-plan.sh +0 -0
  66. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/summarize-delivery/SKILL.md +0 -0
  67. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/think/SKILL.md +0 -0
  68. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/think/scripts/think.sh +0 -0
  69. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/version-bump/SKILL.md +0 -0
  70. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills/version-bump/scripts/bump.py +0 -0
  71. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.claude/skills.local.yaml.example +0 -0
  72. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.flake8 +0 -0
  73. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.github/workflows/publish.yml +0 -0
  74. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.github/workflows/tests.yml +0 -0
  75. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.gitignore +0 -0
  76. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/.markdownlint-cli2.yaml +0 -0
  77. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/AGENTS.colleague.md +0 -0
  78. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/CLAUDE.md +0 -0
  79. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/LICENSE +0 -0
  80. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/culture.yaml +0 -0
  81. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/docs/skill-sources.md +0 -0
  82. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/scripts/sonar-pr-issues.py +0 -0
  83. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/sonar-project.properties +0 -0
  84. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/tests/__init__.py +0 -0
  85. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/tests/test_ledger.py +0 -0
  86. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/tests/test_sonar_pr_issues.py +0 -0
  87. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/__main__.py +0 -0
  88. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_commands/__init__.py +0 -0
  89. {workledger_cli-0.8.0 → workledger_cli-0.9.0}/workledger/cli/_output.py +0 -0
@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
5
5
  Format follows [Keep a Changelog](https://keepachangelog.com/). This project
6
6
  adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.9.0] - 2026-11-19
9
+
10
+ ### Changed
11
+
12
+ - The argparse `prog` is now `ledger`, the command the package installs, and every invocation the tool prints uses it: `--help` usage lines (`usage: ledger ...`), `--version` (`ledger <version>`), the `learn` text, the `explain` catalog headings and usage blocks, the subjects `ledger cli` (`cli overview`, text and `--json`) and `ledger doctor: ...`, and error hints and remediations (`run 'ledger --help' ...`, `ledger explain ledger`, `ledger append --stdin`). They used to say `workledger-cli <verb>`, which is not an installed command. The package and distribution are still named `workledger-cli`; `explain`, `explain workledger-cli` and `explain ledger` all still resolve to the root entry.
13
+ - `learn --json`: `explain_pointer` is now `ledger explain <path>`, a new `console_script` field holds `ledger`, and `purpose` describes the ledger. `tool` is still `workledger-cli`.
14
+ - `overview` (text and `--json`) has a new last section, `Purpose`, that says what the package is for. `Identity` and `Verbs` keep their positions (indexes 0 and 1).
15
+ - `overview`: the third section is now titled `Repository artifacts` (was `Sibling-pattern artifacts`), and its skills line reads "vendored skills".
16
+ - The root `explain` entry's heading now names both the package and the command: ``# workledger-cli (command: `ledger`)``.
17
+ - README quickstart uses the `ledger` command and shows `append` and `list`; its list of what the repository contains was rewritten against the tree (18 skills, not 11).
18
+ - The one-sentence summary in `--help`, `learn`, `explain` and `overview` is read from the installed distribution's metadata (`workledger/_about.py`), not copied into each.
19
+
20
+ ### Fixed
21
+
22
+ - The `--help` description, the `learn` text and JSON, the `explain` root entry and the `overview` docs described the starter this repo was scaffolded from ("a clonable template for AgentCulture mesh agents"). They now describe the package: a work ledger for agents, matching the `pyproject.toml` description.
23
+ - The default ledger path was described as `./.workledger/ledger.jsonl`, and then as "under the git toplevel". `learn`, `explain`, `explain append`, `overview` and the README now state what the store does: `$WORKLEDGER_PATH` when set; otherwise `.workledger/ledger.jsonl` under the nearest ancestor directory that contains `.git` (else the current directory). The store's behaviour did not change.
24
+ - README no longer carries the starter's "Make it your own" rename instructions, and a leftover "register your own noun groups" comment is gone from the parser.
25
+
8
26
  ## [0.8.0] - 2026-10-27
9
27
 
10
28
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: workledger-cli
3
- Version: 0.8.0
3
+ Version: 0.9.0
4
4
  Summary: Tracks work in a ledger so agents can prove what they did. An agent records its work as append-only ledger entries, hands the ledger down to subagents, and gets it back with their entries folded in, so the whole tree of work and its results stays traceable and checkable.
5
5
  Project-URL: Homepage, https://github.com/agentculture/workledger-cli
6
6
  Project-URL: Issues, https://github.com/agentculture/workledger-cli/issues
@@ -19,25 +19,33 @@ Description-Content-Type: text/markdown
19
19
 
20
20
  Tracks work in a ledger so agents can prove what they did. An agent records its work as append-only ledger entries, hands the ledger down to subagents, and gets it back with their entries folded in, so the whole tree of work and its results stays traceable and checkable.
21
21
 
22
- ## What you get
22
+ The package and distribution are named `workledger-cli`; the command it
23
+ installs is `ledger`.
23
24
 
24
- - **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
25
- (`afi-cli`) — the runtime package has no third-party dependencies.
26
- - **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
27
- resident prompt file (`AGENTS.colleague.md`, since this template runs
28
- `backend: colleague`).
29
- - **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
30
- vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
31
- - **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
32
- PyPI Trusted Publishing wired into GitHub Actions.
25
+ ## What is in this repository
26
+
27
+ - **The `ledger` command** (`workledger/`) — two ledger verbs, `append` and
28
+ `list`, over an append-only JSONL file, plus the self-describing verbs
29
+ `whoami`, `learn`, `explain`, `overview`, `doctor` and `cli overview`. The
30
+ package declares no runtime dependencies.
31
+ - **A mesh identity** — `culture.yaml` (`suffix`, `backend: colleague`, `model`)
32
+ and the matching resident prompt file, `AGENTS.colleague.md`.
33
+ - **18 skills** under `.claude/skills/`, vendored cite-don't-import. Where each
34
+ one comes from is recorded in [`docs/skill-sources.md`](docs/skill-sources.md).
35
+ - **Tests and CI** — `tests/` (pytest), and `.github/workflows/tests.yml`, which
36
+ runs the tests, black, isort, flake8, bandit, markdownlint, the `teken`
37
+ rubric gate, a version-bump check, and SonarCloud. `publish.yml` publishes to
38
+ PyPI and TestPyPI with Trusted Publishing.
33
39
 
34
40
  ## Quickstart
35
41
 
36
42
  ```bash
37
43
  uv sync
38
44
  uv run pytest -n auto # run the test suite
39
- uv run workledger-cli whoami # identity from culture.yaml
40
- uv run workledger-cli learn # self-teaching prompt (add --json)
45
+ uv run ledger whoami # identity from culture.yaml
46
+ uv run ledger learn # self-teaching prompt (add --json)
47
+ uv run ledger append '{"agent":"a","action":"edit","summary":"did x"}'
48
+ uv run ledger list --agent a # read entries back (add --json)
41
49
  uv run teken cli doctor . --strict # the agent-first rubric gate CI runs
42
50
  ```
43
51
 
@@ -50,7 +58,7 @@ uv run teken cli doctor . --strict # the agent-first rubric gate CI runs
50
58
  | `explain <path>` | Markdown docs for any noun/verb path. |
51
59
  | `overview` | Read-only descriptive snapshot of the agent. |
52
60
  | `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
53
- | `append <json>` | Append one entry (`agent`, `action`, `summary`; optional `refs`, `data`) to the append-only ledger (`$WORKLEDGER_PATH`, default `.workledger/ledger.jsonl` under the git toplevel of the cwd (the cwd itself outside a repo)). `--stdin` reads JSON from stdin. |
61
+ | `append <json>` | Append one entry (`agent`, `action`, `summary`; optional `refs`, `data`) to the append-only ledger (`$WORKLEDGER_PATH` when set; otherwise `.workledger/ledger.jsonl` under the nearest ancestor directory that contains `.git` (else the current directory)). `--stdin` reads JSON from stdin. |
54
62
  | `list` | Read entries: `--agent`, `--action`, `--since`, `--limit`. |
55
63
  | `cli overview` | Describe the CLI surface itself. |
56
64
 
@@ -58,21 +66,6 @@ Every command supports `--json`. Results go to stdout, errors/diagnostics to
58
66
  stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
59
67
  error, `3+` reserved.
60
68
 
61
- ## Make it your own
62
-
63
- 1. Rename the package `workledger/` and the `workledger-cli`
64
- CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
65
- `sonar-project.properties`, and this `README.md`. The name is hard-coded in
66
- ~100 places, so list every occurrence first — see the `git grep` discovery
67
- command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
68
- 2. Edit `culture.yaml` with your `suffix` and `backend`.
69
- 3. Rewrite `CLAUDE.md` for your agent and run `/init`.
70
- 4. Re-vendor only the skills you need from guildmaster (see
71
- [`docs/skill-sources.md`](docs/skill-sources.md)).
72
-
73
- See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
74
- the `cicd` PR lane, deploy setup).
75
-
76
69
  ## License
77
70
 
78
71
  Apache 2.0 — see [`LICENSE`](LICENSE).
@@ -0,0 +1,54 @@
1
+ # workledger-cli
2
+
3
+ Tracks work in a ledger so agents can prove what they did. An agent records its work as append-only ledger entries, hands the ledger down to subagents, and gets it back with their entries folded in, so the whole tree of work and its results stays traceable and checkable.
4
+
5
+ The package and distribution are named `workledger-cli`; the command it
6
+ installs is `ledger`.
7
+
8
+ ## What is in this repository
9
+
10
+ - **The `ledger` command** (`workledger/`) — two ledger verbs, `append` and
11
+ `list`, over an append-only JSONL file, plus the self-describing verbs
12
+ `whoami`, `learn`, `explain`, `overview`, `doctor` and `cli overview`. The
13
+ package declares no runtime dependencies.
14
+ - **A mesh identity** — `culture.yaml` (`suffix`, `backend: colleague`, `model`)
15
+ and the matching resident prompt file, `AGENTS.colleague.md`.
16
+ - **18 skills** under `.claude/skills/`, vendored cite-don't-import. Where each
17
+ one comes from is recorded in [`docs/skill-sources.md`](docs/skill-sources.md).
18
+ - **Tests and CI** — `tests/` (pytest), and `.github/workflows/tests.yml`, which
19
+ runs the tests, black, isort, flake8, bandit, markdownlint, the `teken`
20
+ rubric gate, a version-bump check, and SonarCloud. `publish.yml` publishes to
21
+ PyPI and TestPyPI with Trusted Publishing.
22
+
23
+ ## Quickstart
24
+
25
+ ```bash
26
+ uv sync
27
+ uv run pytest -n auto # run the test suite
28
+ uv run ledger whoami # identity from culture.yaml
29
+ uv run ledger learn # self-teaching prompt (add --json)
30
+ uv run ledger append '{"agent":"a","action":"edit","summary":"did x"}'
31
+ uv run ledger list --agent a # read entries back (add --json)
32
+ uv run teken cli doctor . --strict # the agent-first rubric gate CI runs
33
+ ```
34
+
35
+ ## CLI
36
+
37
+ | Verb | What it does |
38
+ |------|--------------|
39
+ | `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
40
+ | `learn` | Print a structured self-teaching prompt. |
41
+ | `explain <path>` | Markdown docs for any noun/verb path. |
42
+ | `overview` | Read-only descriptive snapshot of the agent. |
43
+ | `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
44
+ | `append <json>` | Append one entry (`agent`, `action`, `summary`; optional `refs`, `data`) to the append-only ledger (`$WORKLEDGER_PATH` when set; otherwise `.workledger/ledger.jsonl` under the nearest ancestor directory that contains `.git` (else the current directory)). `--stdin` reads JSON from stdin. |
45
+ | `list` | Read entries: `--agent`, `--action`, `--since`, `--limit`. |
46
+ | `cli overview` | Describe the CLI surface itself. |
47
+
48
+ Every command supports `--json`. Results go to stdout, errors/diagnostics to
49
+ stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
50
+ error, `3+` reserved.
51
+
52
+ ## License
53
+
54
+ Apache 2.0 — see [`LICENSE`](LICENSE).
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "workledger-cli"
3
- version = "0.8.0"
3
+ version = "0.9.0"
4
4
  description = "Tracks work in a ledger so agents can prove what they did. An agent records its work as append-only ledger entries, hands the ledger down to subagents, and gets it back with their entries folded in, so the whole tree of work and its results stays traceable and checkable."
5
5
  readme = "README.md"
6
6
  license = "Apache-2.0"
@@ -21,7 +21,7 @@ def test_version_flag(capsys: pytest.CaptureFixture[str]) -> None:
21
21
  def test_no_args_prints_help(capsys: pytest.CaptureFixture[str]) -> None:
22
22
  rc = main([])
23
23
  assert rc == 0
24
- assert "usage: workledger-cli" in capsys.readouterr().out
24
+ assert "usage: ledger" in capsys.readouterr().out
25
25
 
26
26
 
27
27
  def test_unknown_command_errors(capsys: pytest.CaptureFixture[str]) -> None:
@@ -97,7 +97,7 @@ def test_explain_json(capsys: pytest.CaptureFixture[str]) -> None:
97
97
  assert rc == 0
98
98
  payload = json.loads(capsys.readouterr().out)
99
99
  assert payload["path"] == ["whoami"]
100
- assert "workledger-cli whoami" in payload["markdown"]
100
+ assert "ledger whoami" in payload["markdown"]
101
101
 
102
102
 
103
103
  def test_explain_unknown_path_errors(capsys: pytest.CaptureFixture[str]) -> None:
@@ -41,14 +41,14 @@ def test_overview_graceful_on_bad_path(capsys: pytest.CaptureFixture[str]) -> No
41
41
  def test_cli_overview_text(capsys: pytest.CaptureFixture[str]) -> None:
42
42
  rc = main(["cli", "overview"])
43
43
  assert rc == 0
44
- assert "# workledger-cli cli" in capsys.readouterr().out
44
+ assert "# ledger cli" in capsys.readouterr().out
45
45
 
46
46
 
47
47
  def test_cli_overview_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
48
48
  rc = main(["cli", "overview", "--json"])
49
49
  assert rc == 0
50
50
  payload = json.loads(capsys.readouterr().out)
51
- assert payload["subject"] == "workledger-cli cli"
51
+ assert payload["subject"] == "ledger cli"
52
52
  assert isinstance(payload["sections"], list)
53
53
 
54
54
 
@@ -77,7 +77,7 @@ def test_cli_overview_unknown_flag_structured_error(
77
77
  def test_doctor_text(capsys: pytest.CaptureFixture[str]) -> None:
78
78
  rc = main(["doctor"])
79
79
  assert rc in (0, 1)
80
- assert "workledger-cli doctor" in capsys.readouterr().out
80
+ assert "ledger doctor" in capsys.readouterr().out
81
81
 
82
82
 
83
83
  def test_doctor_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
@@ -0,0 +1,294 @@
1
+ """The package's self-descriptions say what it is: a work ledger for agents.
2
+
3
+ The repo was scaffolded from a mesh-agent starter, and its help text, ``learn``,
4
+ ``explain`` and ``overview`` once described that starter instead of the ledger.
5
+ These tests hold every user-facing self-description to the summary in
6
+ ``pyproject.toml``, to the command that is actually installed (``ledger``), and
7
+ to what the store really does when it picks the ledger file.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import argparse
13
+ import contextlib
14
+ import json
15
+ import re
16
+ import tomllib
17
+ from importlib.metadata import PackageNotFoundError
18
+ from pathlib import Path
19
+
20
+ import pytest
21
+
22
+ from workledger import _about
23
+ from workledger.cli import _build_parser, main
24
+ from workledger.explain import known_paths
25
+
26
+ _REPO = Path(__file__).resolve().parents[1]
27
+ _PYPROJECT = _REPO / "pyproject.toml"
28
+ _JSON_FLAG = "--json"
29
+ _OVERVIEW = "overview"
30
+ _SECTIONS = "sections"
31
+
32
+ # Phrases left over from the starter this repo was scaffolded from. Whole
33
+ # phrases, not single words, so honest later wording is not refused.
34
+ _LEFTOVER_PHRASES = (
35
+ "clonable template",
36
+ "this template",
37
+ "clone it",
38
+ "rename the package",
39
+ "make it your own",
40
+ "register your own",
41
+ "sibling-pattern",
42
+ )
43
+
44
+ # How the store picks the default ledger file (see ``_store.ledger_path``).
45
+ _PATH_RULE = "nearest ancestor directory that contains .git (else the current directory)"
46
+ _WRONG_PATH_RULE = "git toplevel"
47
+
48
+
49
+ def _verbs() -> list[str]:
50
+ """Every top-level verb the parser registers."""
51
+ actions = _build_parser()._actions
52
+ sub = next(a for a in actions if isinstance(a, argparse._SubParsersAction))
53
+ return list(sub.choices)
54
+
55
+
56
+ _VERBS = _verbs()
57
+ # The package name followed by a verb: an invocation that is not installed.
58
+ _NOT_INSTALLED = re.compile(r"workledger-cli\s+(?:" + "|".join(map(re.escape, _VERBS)) + r")\b")
59
+
60
+
61
+ def _pyproject_summary() -> str:
62
+ """The first sentence of the ``pyproject.toml`` description."""
63
+ with _PYPROJECT.open("rb") as handle:
64
+ description = tomllib.load(handle)["project"]["description"]
65
+ return description.split(". ", 1)[0].rstrip(".") + "."
66
+
67
+
68
+ def _flat(text: str) -> str:
69
+ """Lower-case, drop backticks and collapse whitespace (line wrapping is ignored)."""
70
+ return " ".join(text.lower().replace("`", "").split())
71
+
72
+
73
+ def _run(argv: list[str], capsys: pytest.CaptureFixture[str]) -> str:
74
+ """Run the CLI and return stdout and stderr together, whatever the exit."""
75
+ with contextlib.suppress(SystemExit):
76
+ main(argv)
77
+ captured = capsys.readouterr()
78
+ return captured.out + captured.err
79
+
80
+
81
+ def _assert_no_leftovers(text: str, where: str) -> None:
82
+ flat = _flat(text)
83
+ for phrase in _LEFTOVER_PHRASES:
84
+ assert phrase not in flat, f"{where} still carries starter wording: {phrase!r}"
85
+
86
+
87
+ def _assert_describes_the_ledger(text: str, where: str) -> None:
88
+ assert _flat(_about.summary()) in _flat(text), f"{where} does not carry the summary"
89
+ _assert_no_leftovers(text, where)
90
+
91
+
92
+ # --- one source for the summary -------------------------------------------
93
+
94
+
95
+ def test_summary_matches_pyproject() -> None:
96
+ assert _about.summary() == _pyproject_summary()
97
+ assert _about.summary() == "Tracks work in a ledger so agents can prove what they did."
98
+
99
+
100
+ def test_summary_fallback_matches_pyproject(monkeypatch: pytest.MonkeyPatch) -> None:
101
+ def _missing(name: str) -> None:
102
+ raise PackageNotFoundError(name)
103
+
104
+ monkeypatch.setattr(_about, "metadata", _missing)
105
+ assert _about.summary() == _pyproject_summary()
106
+
107
+
108
+ def test_command_is_the_installed_script() -> None:
109
+ with _PYPROJECT.open("rb") as handle:
110
+ scripts = tomllib.load(handle)["project"]["scripts"]
111
+ assert list(scripts) == [_about.COMMAND]
112
+
113
+
114
+ # --- every surface carries the summary ------------------------------------
115
+
116
+
117
+ @pytest.mark.parametrize(
118
+ "argv",
119
+ [[], ["learn"], ["explain"], ["explain", "workledger-cli"], ["explain", "ledger"], [_OVERVIEW]],
120
+ )
121
+ def test_surface_describes_the_ledger(argv: list[str], capsys: pytest.CaptureFixture[str]) -> None:
122
+ assert main(argv) == 0
123
+ _assert_describes_the_ledger(capsys.readouterr().out, " ".join(argv) or "--help")
124
+
125
+
126
+ @pytest.mark.parametrize("argv", [["learn"], ["explain"]])
127
+ def test_surface_says_append_only(argv: list[str], capsys: pytest.CaptureFixture[str]) -> None:
128
+ assert main(argv) == 0
129
+ assert "append-only" in capsys.readouterr().out
130
+
131
+
132
+ def test_learn_json_describes_the_ledger(capsys: pytest.CaptureFixture[str]) -> None:
133
+ assert main(["learn", _JSON_FLAG]) == 0
134
+ payload = json.loads(capsys.readouterr().out)
135
+ _assert_describes_the_ledger(payload["purpose"], "learn --json purpose")
136
+ assert payload["console_script"] == _about.COMMAND
137
+ assert payload["explain_pointer"] == "ledger explain <path>"
138
+
139
+
140
+ # --- learn keeps what the rubric asks for ---------------------------------
141
+
142
+
143
+ def test_learn_text_keeps_the_rubric_topics(capsys: pytest.CaptureFixture[str]) -> None:
144
+ assert main(["learn"]) == 0
145
+ out = capsys.readouterr().out
146
+ assert len(out) >= 200
147
+ for topic in ("Purpose", "Commands", "Exit-code policy", _JSON_FLAG, "explain"):
148
+ assert topic in out
149
+
150
+
151
+ @pytest.mark.parametrize("verb", _VERBS)
152
+ def test_learn_text_has_a_row_for_each_verb(verb: str, capsys: pytest.CaptureFixture[str]) -> None:
153
+ assert main(["learn"]) == 0
154
+ row = re.compile(rf"^ ledger {re.escape(verb)}\b.*\S", re.MULTILINE)
155
+ assert row.search(capsys.readouterr().out), f"no command row for {verb!r}"
156
+
157
+
158
+ def test_learn_json_lists_each_verb(capsys: pytest.CaptureFixture[str]) -> None:
159
+ assert main(["learn", _JSON_FLAG]) == 0
160
+ payload = json.loads(capsys.readouterr().out)
161
+ listed = {command["path"][0] for command in payload["commands"]}
162
+ assert listed == set(_VERBS)
163
+
164
+
165
+ def test_every_verb_has_a_catalog_entry() -> None:
166
+ assert {(verb,) for verb in _VERBS} <= set(known_paths())
167
+
168
+
169
+ # --- the invocation is the installed command ------------------------------
170
+
171
+
172
+ def _user_facing_argvs() -> list[list[str]]:
173
+ argvs: list[list[str]] = [[], ["--help"], ["learn"], ["learn", _JSON_FLAG]]
174
+ argvs.extend([verb, "--help"] for verb in _VERBS)
175
+ argvs.extend(["explain", *path] for path in known_paths())
176
+ argvs.extend(
177
+ [
178
+ [_OVERVIEW],
179
+ [_OVERVIEW, _JSON_FLAG],
180
+ ["cli", _OVERVIEW],
181
+ ["cli", _OVERVIEW, _JSON_FLAG],
182
+ ["doctor"],
183
+ ["bogus"],
184
+ ["explain", "nonexistent"],
185
+ ["explain", "nonexistent", _JSON_FLAG],
186
+ ["append", "--bogus"],
187
+ ["append"],
188
+ ]
189
+ )
190
+ return argvs
191
+
192
+
193
+ @pytest.mark.parametrize("argv", _user_facing_argvs(), ids=" ".join)
194
+ def test_no_output_names_an_uninstalled_command(
195
+ argv: list[str], capsys: pytest.CaptureFixture[str]
196
+ ) -> None:
197
+ output = _run(argv, capsys)
198
+ assert output.strip()
199
+ assert not _NOT_INSTALLED.search(output), _NOT_INSTALLED.search(output)
200
+
201
+
202
+ def test_help_usage_names_the_command(capsys: pytest.CaptureFixture[str]) -> None:
203
+ assert main([]) == 0
204
+ assert "usage: ledger" in capsys.readouterr().out
205
+
206
+
207
+ def test_parse_error_hint_names_the_command(capsys: pytest.CaptureFixture[str]) -> None:
208
+ assert "hint: run 'ledger --help'" in _run(["bogus"], capsys)
209
+
210
+
211
+ def test_explain_error_hint_names_the_command(capsys: pytest.CaptureFixture[str]) -> None:
212
+ assert "ledger explain ledger" in _run(["explain", "nonexistent"], capsys)
213
+
214
+
215
+ def test_readme_names_the_installed_command() -> None:
216
+ readme = (_REPO / "README.md").read_text(encoding="utf-8")
217
+ assert not _NOT_INSTALLED.search(readme)
218
+ _assert_no_leftovers(readme, "README.md")
219
+
220
+
221
+ # --- no starter wording anywhere ------------------------------------------
222
+
223
+
224
+ @pytest.mark.parametrize("verb", _VERBS)
225
+ def test_verb_help_has_no_starter_wording(verb: str, capsys: pytest.CaptureFixture[str]) -> None:
226
+ _assert_no_leftovers(_run([verb, "--help"], capsys), f"{verb} --help")
227
+
228
+
229
+ @pytest.mark.parametrize("path", known_paths(), ids=" ".join)
230
+ def test_catalog_entry_has_no_starter_wording(
231
+ path: tuple[str, ...], capsys: pytest.CaptureFixture[str]
232
+ ) -> None:
233
+ assert main(["explain", *path]) == 0
234
+ _assert_no_leftovers(capsys.readouterr().out, f"explain {' '.join(path)}")
235
+
236
+
237
+ def test_parser_source_has_no_starter_comment() -> None:
238
+ source = (_REPO / "workledger" / "cli" / "__init__.py").read_text(encoding="utf-8")
239
+ assert "my_noun" not in source
240
+ _assert_no_leftovers(source, "workledger/cli/__init__.py")
241
+
242
+
243
+ # --- the default ledger path is described as the store resolves it --------
244
+
245
+
246
+ @pytest.mark.parametrize(
247
+ "argv",
248
+ [["learn"], ["explain"], ["explain", "append"], [_OVERVIEW], [_OVERVIEW, _JSON_FLAG]],
249
+ )
250
+ def test_default_path_rule_is_stated(argv: list[str], capsys: pytest.CaptureFixture[str]) -> None:
251
+ assert main(argv) == 0
252
+ flat = _flat(capsys.readouterr().out)
253
+ assert _PATH_RULE in flat
254
+ assert "$workledger_path" in flat
255
+ assert _WRONG_PATH_RULE not in flat
256
+
257
+
258
+ def test_readme_states_the_default_path_rule() -> None:
259
+ flat = _flat((_REPO / "README.md").read_text(encoding="utf-8"))
260
+ assert _PATH_RULE in flat
261
+ assert _WRONG_PATH_RULE not in flat
262
+
263
+
264
+ # --- overview --------------------------------------------------------------
265
+
266
+
267
+ def _overview_sections(capsys: pytest.CaptureFixture[str]) -> list[dict[str, object]]:
268
+ assert main([_OVERVIEW, _JSON_FLAG]) == 0
269
+ return json.loads(capsys.readouterr().out)[_SECTIONS]
270
+
271
+
272
+ def test_overview_json_keeps_identity_first(capsys: pytest.CaptureFixture[str]) -> None:
273
+ titles = [section["title"] for section in _overview_sections(capsys)]
274
+ assert titles == ["Identity", "Verbs", "Repository artifacts", "Purpose"]
275
+
276
+
277
+ def test_overview_json_purpose_describes_the_ledger(capsys: pytest.CaptureFixture[str]) -> None:
278
+ purpose = _overview_sections(capsys)[-1]
279
+ _assert_describes_the_ledger(json.dumps(purpose), "overview --json purpose")
280
+
281
+
282
+ def test_overview_artifacts_exist(capsys: pytest.CaptureFixture[str]) -> None:
283
+ artifacts = _overview_sections(capsys)[2]
284
+ assert artifacts["items"]
285
+ for item in artifacts["items"]:
286
+ names = str(item).split(" — ", 1)[0]
287
+ for name in names.split(" + "):
288
+ assert (_REPO / name).exists(), f"overview names {name!r}, which is not in the repo"
289
+
290
+
291
+ def test_readme_skill_count_matches_the_tree() -> None:
292
+ readme = (_REPO / "README.md").read_text(encoding="utf-8")
293
+ skills = [p for p in (_REPO / ".claude" / "skills").iterdir() if (p / "SKILL.md").is_file()]
294
+ assert f"{len(skills)} skills" in readme
@@ -448,7 +448,7 @@ wheels = [
448
448
 
449
449
  [[package]]
450
450
  name = "workledger-cli"
451
- version = "0.8.0"
451
+ version = "0.9.0"
452
452
  source = { editable = "." }
453
453
 
454
454
  [package.dev-dependencies]
@@ -1,4 +1,4 @@
1
- """workledger-cli — agent-first CLI for an AgentCulture mesh agent."""
1
+ """workledger-cli — a work ledger for agents, with an agent-first CLI."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
@@ -0,0 +1,27 @@
1
+ """What this package calls itself: one source for every self-description.
2
+
3
+ The distribution is ``workledger-cli``; the command it installs is ``ledger``.
4
+ The one-sentence summary comes from the installed distribution's metadata (the
5
+ ``description`` in ``pyproject.toml``), so the help text, ``learn``, ``explain``
6
+ and ``overview`` cannot drift from it.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from importlib.metadata import PackageNotFoundError, metadata
12
+
13
+ DISTRIBUTION = "workledger-cli"
14
+ COMMAND = "ledger"
15
+
16
+ # Used only when the distribution's metadata cannot be read.
17
+ _FALLBACK_SUMMARY = "Tracks work in a ledger so agents can prove what they did."
18
+
19
+
20
+ def summary() -> str:
21
+ """The first sentence of the distribution's Summary, ending in a full stop."""
22
+ try:
23
+ text = metadata(DISTRIBUTION)["Summary"]
24
+ except PackageNotFoundError:
25
+ return _FALLBACK_SUMMARY
26
+ first = (text or "").split(". ", 1)[0].strip().rstrip(".")
27
+ return f"{first}." if first else _FALLBACK_SUMMARY
@@ -1,9 +1,10 @@
1
- """Unified CLI entry point for workledger-cli.
1
+ """Unified CLI entry point for workledger-cli (the ``ledger`` command).
2
2
 
3
- The agent-first global verbs (``whoami``, ``learn``, ``explain``, ``overview``,
4
- ``doctor``) are registered here under :mod:`workledger.cli._commands`,
5
- alongside the ``cli`` noun group. Future noun groups register via their own
6
- ``register()`` functions following the same pattern.
3
+ The ledger verbs (``append``, ``list``) and the agent-first global verbs
4
+ (``whoami``, ``learn``, ``explain``, ``overview``, ``doctor``) are registered
5
+ here under :mod:`workledger.cli._commands`, alongside the ``cli`` noun group.
6
+ Future noun groups register via their own ``register()`` functions following
7
+ the same pattern.
7
8
 
8
9
  Error propagation contract
9
10
  --------------------------
@@ -25,6 +26,7 @@ import argparse
25
26
  import sys
26
27
 
27
28
  from workledger import __version__
29
+ from workledger._about import COMMAND, DISTRIBUTION, summary
28
30
  from workledger.cli._errors import EXIT_USER_ERROR, CliError
29
31
  from workledger.cli._output import emit_error
30
32
 
@@ -72,8 +74,8 @@ def _build_parser() -> argparse.ArgumentParser:
72
74
  from workledger.cli._commands import whoami as _whoami_cmd
73
75
 
74
76
  parser = _CliArgumentParser(
75
- prog="workledger-cli",
76
- description="workledger-cli — a clonable template for AgentCulture mesh agents.",
77
+ prog=COMMAND,
78
+ description=f"{summary()} (package {DISTRIBUTION}, command {COMMAND})",
77
79
  )
78
80
  parser.add_argument(
79
81
  "--version",
@@ -92,9 +94,6 @@ def _build_parser() -> argparse.ArgumentParser:
92
94
  _append_cmd.register(sub)
93
95
  _list_cmd.register(sub)
94
96
  _cli_group.register(sub)
95
- # Register your own noun groups here:
96
- # from workledger.cli._commands import my_noun as _my_noun_group
97
- # _my_noun_group.register(sub)
98
97
 
99
98
  return parser
100
99
 
@@ -27,6 +27,13 @@ INPUT_FIELDS = frozenset(REQUIRED_FIELDS) | {"refs", "data"}
27
27
  GENERATED_FIELDS = frozenset({"id", "timestamp"})
28
28
  UTC_OFFSET = "+00:00"
29
29
 
30
+ # How :func:`ledger_path` picks the file when ``$WORKLEDGER_PATH`` is unset. The
31
+ # one wording every self-description (learn, explain, overview) repeats.
32
+ DEFAULT_LOCATION_RULE = (
33
+ f"{DEFAULT_PATH.as_posix()} under the nearest ancestor directory that contains .git "
34
+ "(else the current directory)"
35
+ )
36
+
30
37
 
31
38
  # Fixed-format UTC timestamps (what ``now_utc`` writes); lexicographic order == time order.
32
39
  TIMESTAMP_RE = re.compile(
@@ -45,8 +52,10 @@ def _git_toplevel(start: Path) -> Path | None:
45
52
  def ledger_path() -> Path:
46
53
  """Resolve the ledger file.
47
54
 
48
- ``$WORKLEDGER_PATH`` wins; otherwise ``.workledger/ledger.jsonl`` under the
49
- git toplevel of the cwd, or under the cwd when not inside a repository.
55
+ A non-empty ``$WORKLEDGER_PATH`` wins and is used as given (a relative value
56
+ is relative to the cwd). Otherwise the file is ``.workledger/ledger.jsonl``
57
+ under the nearest directory that contains a ``.git`` entry, searching from
58
+ the cwd itself upwards; with no such directory, under the cwd.
50
59
  """
51
60
  env = os.environ.get(ENV_PATH)
52
61
  if env:
@@ -1,4 +1,4 @@
1
- """``workledger-cli append`` — append one entry to the ledger (the only write verb)."""
1
+ """``ledger append`` — append one entry to the ledger (the only write verb)."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
@@ -32,7 +32,7 @@ def cmd_append(args: argparse.Namespace) -> int:
32
32
  raise CliError(
33
33
  code=EXIT_USER_ERROR,
34
34
  message="--stdin was given but stdin is an interactive terminal",
35
- remediation="pipe the entry in (echo '{...}' | workledger-cli append --stdin)",
35
+ remediation="pipe the entry in (echo '{...}' | ledger append --stdin)",
36
36
  )
37
37
  text = sys.stdin.read() if args.stdin else args.entry
38
38
  try: