coherence-cli 0.4.1__tar.gz → 0.5.0__tar.gz

coherence_cli-0.5.0/.eidetic/memory/coherence-cli__public.jsonl

@@ -0,0 +1,7 @@
+{"id": "devague-converge-gate-all-claims", "hash": "84fd98b0e0d94229ece87b13a1ff64e9d2a04223daed7b036c019b0e6cb388fc", "content": "devague converge gate: the rule \"a confirmed honesty condition on every spec-affecting claim\" covers ALL core frame claims \u2014 audience, before_state, after_state, why_it_matters, boundary, success_signal \u2014 not just kind=requirement claims. Interrogate + confirm a condition on each, or converge fails with one gap per frame claim. Also: devague auto-adds .devague/reviews/ to .gitignore on first review; frames + specs are committed, review artifacts are working state. (Learned scoping coherence-cli issue #4, 2026-07-04.)", "scope": {"name": "coherence-cli", "visibility": "public"}, "metadata": {"type": "note", "record_metadata": {"source": "coherence-cli spec session", "topic": "devague usage", "date": "2026-07-04"}, "created": "2026-07-04T07:21:59.005289+00:00", "last_recall": null, "recall_count": 0, "links": [], "supersedes": null, "lifecycle": "active", "added_by": null}}
+{"id": "meaning-gradient-continuation-2026-07-04", "hash": "7e590a120f07f1dfe9bad3d76d14115ac4fa28099beabfcec03c29c90672e847", "content": "Meaning Gradient (issue #4) scoping complete 2026-07-04; PR #5 MERGED \u2014 spec, plan, frame state all on main. Implementation tracker with full continuation guidance (serial path, /assign-to-workforce path with per-task model split, roadmap, paid-for gotchas): https://github.com/agentculture/coherence-cli/issues/6. Resume: recall this record, read issue #6, branch feat/meaning-gradient, work waves 0-5 TDD-first. Key confirmed decisions: coherence meaning noun (not separate CLI); anchor-axis projection, 5 subdimensions (consequence, agency, causality, affordance, future_constraint); trend verb with f-prime/f-double-prime of scores AND embedding drift; numpy+httpx first runtime deps; COHERENCE_EMBED_URL/_MODEL env contract (eidetic gear default); offline CI via recorded-vector fixtures.", "scope": {"name": "coherence-cli", "visibility": "public"}, "metadata": {"type": "note", "record_metadata": {"source": "issue-6 implementation tracker", "topic": "meaning gradient", "issue": "6", "pr": "5", "date": "2026-07-04"}, "created": "2026-07-04T08:16:15.263629+00:00", "last_recall": null, "recall_count": 0, "links": ["devague-converge-gate-all-claims"], "supersedes": null, "lifecycle": "shadowed", "added_by": null}}
+{"id": "colleague-toolcall-format-bug-2026-07", "hash": "088fa4a396dd6f5249035400ab4ace35fada8e4cc5dd72d75bbfb543c56f2308", "content": "GOTCHA (paid for): the `colleague` backend (vllm-openai + Qwen3.6-27B at localhost:8001) reliably FAILS `ask-colleague write` on any non-trivial task. Root cause: the model emits tool calls as TEXT content (markdown ```bash <tool>``` fences or `<tool>{json}` XML) instead of native OpenAI tool_calls, so the harness parses 0 steps, burns the whole --max-steps budget, and returns status:incomplete with steps:[]. A trivial scaffold task (t1) worked; 3/3 medium tasks failed identically, even with a lean brief and 40 steps. `colleague doctor --probe` passes (single-shot tool-call OK) because the probe is too simple to trigger it. Why: filed as agentculture/colleague#289. How to apply: when using /assign-to-workforce with colleague as the worker, expect failure beyond trivial tasks \u2014 swap the worker to Claude general-purpose subagents (still in isolated worktrees, \u2264N parallel, TDD-gated merges) rather than retrying colleague. Verified 2026-07-04 during the Meaning Gradient build.", "scope": {"name": "coherence-cli", "visibility": "public"}, "metadata": {"type": "note", "record_metadata": {"topic": "assign-to-workforce / colleague", "issue": "agentculture/colleague#289", "date": "2026-07-04", "source": "meaning-gradient build session"}, "created": "2026-07-04T15:34:16.511073+00:00", "last_recall": null, "recall_count": 0, "links": ["meaning-gradient-mvp-shipped-2026-07-04"], "supersedes": null, "lifecycle": "active", "added_by": null}}
+{"id": "embed-gear-at-8001-lazyload-2026-07", "hash": "48c7ae4ee962ff1aae7746c6b88e07d37adb8aadb6bca7bf7ad70c689e7d4908", "content": "INFRA FACT: this machine's OpenAI-compatible embedding gear is the multi-lobe router at http://localhost:8001/v1 (same server as the colleague chat model), NOT the coherence/eidetic default http://localhost:8002/v1 (which is down). `GET localhost:8001/v1/models` lists Qwen/Qwen3-Embedding-0.6B (dim 1024) + Qwen3-Reranker-0.6B alongside the chat models, owned_by 'lobes'. The lobes LAZY-LOAD on first request, so a cold embeddings call can exceed 30s (times out). How to apply: to run `coherence meaning score/compare/trend` live or to run scripts/refresh_meaning_vectors.py, set COHERENCE_EMBED_URL=http://localhost:8001/v1, COHERENCE_EMBED_MODEL=Qwen/Qwen3-Embedding-0.6B, COHERENCE_EMBED_TIMEOUT=120 (the timeout knob added in coherence-cli 0.5.0 for exactly this cold-start case). Same applies to eidetic recall: set EIDETIC_EMBED_URL=http://localhost:8001/v1.", "scope": {"name": "coherence-cli", "visibility": "public"}, "metadata": {"type": "note", "record_metadata": {"topic": "embed gear / infra", "date": "2026-07-04", "source": "meaning-gradient build session"}, "created": "2026-07-04T15:34:16.512575+00:00", "last_recall": null, "recall_count": 0, "links": ["colleague-toolcall-format-bug-2026-07"], "supersedes": null, "lifecycle": "active", "added_by": null}}
+{"id": "venv-markdownlint-ci-gotcha-2026-07", "hash": "0634779a88819e172f3f6b319791d997ba24617ce355fa92ca5f05a898154404", "content": "GOTCHA (paid for): in AgentCulture repos whose CI lint runs `markdownlint-cli2 \"**/*.md\"`, adding the FIRST runtime dependency flips this check red. Before: `dependencies = []` means CI's `uv sync` installs nothing, so `.venv` has no markdown and the glob passes. After adding deps (e.g. numpy/httpx), `uv sync` populates `.venv/lib/.../*.dist-info/licenses/LICENSE.md` (numpy has ~9), which trip markdownlint (70 errors) because `.venv/**` was not in the ignore list. Fix: add `- \".venv/**\"` to `.markdownlint-cli2.yaml` `ignores:`. How to apply: when introducing runtime deps to a zero-dep AgentCulture repo, pre-empt this by adding `.venv/**` to the markdownlint ignores in the same PR. Fixed in coherence-cli PR #7.", "scope": {"name": "coherence-cli", "visibility": "public"}, "metadata": {"type": "note", "record_metadata": {"topic": "CI / markdownlint", "date": "2026-07-04", "source": "meaning-gradient PR #7"}, "created": "2026-07-04T15:34:16.522095+00:00", "last_recall": null, "recall_count": 0, "links": [], "supersedes": null, "lifecycle": "active", "added_by": null}}
+{"id": "sonar-pr-quality-gate-2026-07", "hash": "03491653b0008ba66083221b47cad276364d89a74f546959106d96fffec38cd1", "content": "REFERENCE (paid for): coherence-cli's CI has a SonarCloud quality gate on NEW CODE that blocks the PR (project key agentculture_coherence-cli). Two traps: (1) the /sonarclaude `status` verb queries the MAIN-branch gate, which can read PASSED while the PR gate is ERROR \u2014 query the PR gate directly: `curl -u \"$SONAR_TOKEN:\" \"https://sonarcloud.io/api/qualitygates/project_status?projectKey=agentculture_coherence-cli&pullRequest=<PR>\"`, and PR bugs: `.../api/issues/search?componentKeys=...&pullRequest=<PR>&types=BUG&resolved=false`. (2) Rule python:S1244 (no `== 0.0` on floats) fires on zero-norm guards like `if norm == 0.0:` \u2014 new_reliability_rating jumps to 3 and fails the gate. Fix: guard with a small epsilon (`norm <= 1e-12`), which is also more robust. SONAR_TOKEN is available in this environment. How to apply: after opening a PR here, check the PR-scoped Sonar gate, not just CI red/green or the main-branch status.", "scope": {"name": "coherence-cli", "visibility": "public"}, "metadata": {"type": "note", "record_metadata": {"topic": "CI / SonarCloud", "date": "2026-07-04", "source": "meaning-gradient PR #7"}, "created": "2026-07-04T15:34:16.522259+00:00", "last_recall": null, "recall_count": 0, "links": [], "supersedes": null, "lifecycle": "active", "added_by": null}}
+{"id": "meaning-gradient-mvp-shipped-2026-07-04", "hash": "2b5657f62b8bfa1ef9905e4e98a9ee4c4fecfad30699b180b7fca4a54869c027", "content": "Meaning Gradient MVP is BUILT and in review as coherence-cli PR #7 (branch feat/meaning-gradient, v0.5.0), superseding the continuation pointer. All 10 plan tasks / 6 waves done via /assign-to-workforce (workers were Claude subagents after colleague failed \u2014 see colleague-toolcall-format-bug-2026-07). Ships: `coherence meaning score/compare/trend` (--json, exit 0/1/2), the coherence/meaning engine (embed/axis+12 anchors/diagnostics/score/compare/trend), README + examples/experiments/issue-priority.yaml, and offline tests (133 passing) with committed recorded-vector fixtures + scripts/refresh_meaning_vectors.py. FALSIFIABILITY CONFIRMED: with real Qwen3-Embedding vectors the ordering test passes out of the box \u2014 every high-meaning fixture strictly outranks its paired low one, rewrite series monotonic, NO anchor tuning needed. numpy+httpx are the first runtime deps. Deferred (issue #6 roadmap, no code paths): experiment runner, LLM judge, doctor/certify --dimension meaning, pluggable providers, routing-policy output.", "scope": {"name": "coherence-cli", "visibility": "public"}, "metadata": {"type": "note", "record_metadata": {"topic": "meaning gradient", "pr": "7", "issue": "6", "date": "2026-07-04", "source": "meaning-gradient build session"}, "created": "2026-07-04T15:34:16.522572+00:00", "last_recall": null, "recall_count": 0, "links": ["colleague-toolcall-format-bug-2026-07", "embed-gear-at-8001-lazyload-2026-07"], "supersedes": "meaning-gradient-continuation-2026-07-04", "lifecycle": "active", "added_by": null}}

{coherence_cli-0.4.1 → coherence_cli-0.5.0}/.gitignore

@@ -231,3 +231,8 @@ skills.local.yaml
 
 # devague working state (not committed by default)
 .devague/reviews/
+
+# Recorded embedding vectors for the offline meaning tests ARE committed (see
+# tests/fixtures/meaning/recorded_vectors.json) so the falsifiability ordering
+# test runs in CI with zero network. Regenerate against a live embed gear with
+# scripts/refresh_meaning_vectors.py after changing anchors or fixtures.

{coherence_cli-0.4.1 → coherence_cli-0.5.0}/.markdownlint-cli2.yaml

@@ -16,6 +16,9 @@ config:
 
 ignores:
   - "node_modules/**"
+  # The virtualenv holds third-party package LICENSE.md files (numpy, httpx, …)
+  # that trip markdownlint; it is created by `uv sync` in CI. Never our source.
+  - ".venv/**"
   - ".local/**"
   - ".afi/**"
   - ".teken/**"

{coherence_cli-0.4.1 → coherence_cli-0.5.0}/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-07-04
+
+### Added
+
+- **Meaning Gradient coherence dimension** — a `coherence meaning` noun with `score <file>`, `compare <before> <after>`, and `trend <f1> <f2> …` verbs (all `--json`, exit codes 0/1/2). Measures a global `meaning_score` plus five subdimensions (consequence, agency, causality, affordance, future_constraint) via anchor-axis projection, with rule-based diagnostics (missing_consequence / missing_owner / missing_next_action). Implements issue #4 phases 1-2 + the trend extension (issue #6).
+- Anchor-axis scoring engine (`coherence/meaning/`): env-configured OpenAI-compatible embedding client (`COHERENCE_EMBED_URL` / `COHERENCE_EMBED_MODEL`, EmbedUnavailable → exit 2 with a hint; diagnostics still run offline), in-repo plain-text anchor fixtures, score/compare/trend engines, and an open `subdimensions` map.
+- `trend` trajectory signals — per-step first (f', velocity) and second (f'', acceleration) differences of the score signals and of embedding drift over an ordered measurement-point series (2+ points → f', 3+ → f'').
+- Example phase-3 experiment config `examples/experiments/issue-priority.yaml` and a README "Meaning Gradient" section (anchor-axis method, JSON contract, steward/eidetic/taskmaster consumer map, scope boundary).
+- Offline integration tests + recorded-vector fixture mechanism (`scripts/refresh_meaning_vectors.py`) so CI runs with zero network access; the high>low falsifiability ordering test is gated on committed recorded vectors.
+- `numpy` and `httpx` as the package's first runtime dependencies.
+
 ## [0.4.1] - 2026-07-04
 
 ### Added

coherence_cli-0.5.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: coherence-cli
+Version: 0.5.0
+Summary: Maintains information quality for agentic workflows — assesses the freshness, provenance, fidelity, and task-specific validity of claims, then refreshes or repairs degraded ones before agents consume them.
+Project-URL: Homepage, https://github.com/agentculture/coherence-cli
+Project-URL: Issues, https://github.com/agentculture/coherence-cli/issues
+Author: Ori Nachum
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy>=1.26
+Description-Content-Type: text/markdown
+
+# coherence-cli
+
+Maintains information quality for agentic workflows — assesses the freshness, provenance, fidelity, and task-specific validity of claims, then refreshes or repairs degraded ones before agents consume them.
+
+## What you get
+
+- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
+  (`afi-cli`) — the runtime package has no third-party dependencies.
+- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
+  prompt file (`CLAUDE.md` for `backend: claude`).
+- **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
+  vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
+- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
+  PyPI Trusted Publishing wired into GitHub Actions.
+
+## Quickstart
+
+```bash
+uv sync
+uv run pytest -n auto                 # run the test suite
+uv run coherence-cli whoami  # identity from culture.yaml
+uv run coherence-cli learn   # self-teaching prompt (add --json)
+uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
+```
+
+## CLI
+
+| Verb | What it does |
+|------|--------------|
+| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
+| `learn` | Print a structured self-teaching prompt. |
+| `explain <path>` | Markdown docs for any noun/verb path. |
+| `overview` | Read-only descriptive snapshot of the agent. |
+| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `cli overview` | Describe the CLI surface itself. |
+
+Every command supports `--json`. Results go to stdout, errors/diagnostics to
+stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
+error, `3+` reserved.
+
+## Meaning Gradient
+
+**Meaning Gradient is a coherence dimension of coherence-cli, not a separate
+CLI.** It ships as the `coherence meaning` noun — same binary, same `--json`
+and exit-code conventions as every other verb. It asks one question: *how
+strongly does this artifact constrain future interpretation and action?*
+
+### How it scores — the anchor axis
+
+Scoring is anchor-axis projection over sentence embeddings, with the anchor
+sets shipped in-repo as editable fixtures so the whole claim stays falsifiable:
+
+```text
+axis  = mean(high-anchor embeddings) - mean(low-anchor embeddings)
+score = cosine(embedding(artifact), axis), rescaled from [-1, 1] to [0, 1]
+```
+
+A parallel artifact scores `1.0`, orthogonal `0.5`, anti-parallel `0.0`. The
+global `meaning` axis yields the scalar `meaning_score`; five subdimensions
+each get their own high/low anchor pair:
+
+| Subdimension | Asks |
+|--------------|------|
+| `consequence` | Does this change what happens next? |
+| `agency` | Who can act because of this? |
+| `causality` | Does this explain why something happened? |
+| `affordance` | Does this reveal what action is possible? |
+| `future_constraint` | Does this reduce the space of valid next actions? |
+
+Alongside the embedding scores, three rule-based diagnostics run fully offline
+(no network call, so they still work when the embed endpoint is down):
+`missing_consequence`, `missing_owner`, `missing_next_action`.
+
+### The three commands
+
+| Command | What it does |
+|---------|--------------|
+| `coherence meaning score <file>` | Score one artifact → the JSON below. |
+| `coherence meaning compare <before> <after>` | Signed per-subdimension deltas across a rewrite (the 2-point case). |
+| `coherence meaning trend <f1> <f2> <f3> …` | Trajectory over an ordered series: first differences (f′, velocity) and second differences (f″, acceleration) of each score plus embedding drift. |
+
+All three support `--json` and follow the CLI exit-code policy: `0` success,
+`1` user-input error (missing file, or fewer than 2 files for `trend`), `2`
+environment error — an unreachable embedding endpoint makes `score` exit `2`
+with a hint naming `COHERENCE_EMBED_URL`, while the offline diagnostics still
+run.
+
+`coherence meaning score <file> --json` emits exactly:
+
+```json
+{
+  "meaning_score": 0.73,
+  "subdimensions": {
+    "consequence": 0.81,
+    "agency": 0.62,
+    "causality": 0.78,
+    "affordance": 0.69,
+    "future_constraint": 0.75
+  },
+  "diagnostics": [
+    {"code": "missing_owner", "message": "No responsible party named — name an owner (e.g. @name, 'owned by', 'assigned to')."}
+  ]
+}
+```
+
+Every value is in `[0, 1]`. `subdimensions` is an open map: registering a sixth
+subdimension adds a key here without breaking existing consumers.
+
+### Consumer map — which field drives which decision
+
+The score JSON is designed so a mesh consumer can act on it without human
+translation. Each field maps to a concrete routing or memory decision:
+
+| Consumer | Reads | Decision |
+|----------|-------|----------|
+| **steward** | `meaning_score` | Low `meaning_score` → route the artifact back for clarification / owner assignment before it flows downstream; high `meaning_score` with unclear ownership → ask steward to assign an owner. |
+| **eidetic** | `subdimensions.consequence`, `subdimensions.future_constraint` | Gate memory writes: high on either → store (memory-worthy); low on both → compress or drop rather than persist. |
+| **taskmaster** | `meaning_score`, `subdimensions.agency` | Prioritize the backlog: high `meaning_score` × high `agency` (someone can act) → surface for execution; low `agency` → hold, it needs an owner first. |
+
+The `diagnostics` list is the always-available fallback: even with no embedding
+endpoint, a fired `missing_consequence` / `missing_owner` / `missing_next_action`
+is enough for a consumer to ask for clarification before acting.
+
+### Scope boundary
+
+This MVP ships scoring, comparison, and trend only. **The experiment runner,
+the LLM-judge fallback, and doctor/certify integration are tracked follow-ups
+with no code paths in this repo.** The committed
+[`examples/experiments/issue-priority.yaml`](examples/experiments/issue-priority.yaml)
+is the config *contract* for the deferred phase-3 experiment — every meaning
+feature it names is already emitted by `coherence meaning score`, but nothing
+executes it yet.
+
+## Make it your own
+
+1. Rename the package `coherence/` and the `coherence-cli`
+   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
+   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
+   ~100 places, so list every occurrence first — see the `git grep` discovery
+   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
+2. Edit `culture.yaml` with your `suffix` and `backend`.
+3. Rewrite `CLAUDE.md` for your agent and run `/init`.
+4. Re-vendor only the skills you need from guildmaster (see
+   [`docs/skill-sources.md`](docs/skill-sources.md)).
+
+See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
+the `cicd` PR lane, deploy setup).
+
+## License
+
+Apache 2.0 — see [`LICENSE`](LICENSE).

coherence_cli-0.5.0/README.md

@@ -0,0 +1,151 @@
+# coherence-cli
+
+Maintains information quality for agentic workflows — assesses the freshness, provenance, fidelity, and task-specific validity of claims, then refreshes or repairs degraded ones before agents consume them.
+
+## What you get
+
+- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
+  (`afi-cli`) — the runtime package has no third-party dependencies.
+- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
+  prompt file (`CLAUDE.md` for `backend: claude`).
+- **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
+  vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
+- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
+  PyPI Trusted Publishing wired into GitHub Actions.
+
+## Quickstart
+
+```bash
+uv sync
+uv run pytest -n auto                 # run the test suite
+uv run coherence-cli whoami  # identity from culture.yaml
+uv run coherence-cli learn   # self-teaching prompt (add --json)
+uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
+```
+
+## CLI
+
+| Verb | What it does |
+|------|--------------|
+| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
+| `learn` | Print a structured self-teaching prompt. |
+| `explain <path>` | Markdown docs for any noun/verb path. |
+| `overview` | Read-only descriptive snapshot of the agent. |
+| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `cli overview` | Describe the CLI surface itself. |
+
+Every command supports `--json`. Results go to stdout, errors/diagnostics to
+stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
+error, `3+` reserved.
+
+## Meaning Gradient
+
+**Meaning Gradient is a coherence dimension of coherence-cli, not a separate
+CLI.** It ships as the `coherence meaning` noun — same binary, same `--json`
+and exit-code conventions as every other verb. It asks one question: *how
+strongly does this artifact constrain future interpretation and action?*
+
+### How it scores — the anchor axis
+
+Scoring is anchor-axis projection over sentence embeddings, with the anchor
+sets shipped in-repo as editable fixtures so the whole claim stays falsifiable:
+
+```text
+axis  = mean(high-anchor embeddings) - mean(low-anchor embeddings)
+score = cosine(embedding(artifact), axis), rescaled from [-1, 1] to [0, 1]
+```
+
+A parallel artifact scores `1.0`, orthogonal `0.5`, anti-parallel `0.0`. The
+global `meaning` axis yields the scalar `meaning_score`; five subdimensions
+each get their own high/low anchor pair:
+
+| Subdimension | Asks |
+|--------------|------|
+| `consequence` | Does this change what happens next? |
+| `agency` | Who can act because of this? |
+| `causality` | Does this explain why something happened? |
+| `affordance` | Does this reveal what action is possible? |
+| `future_constraint` | Does this reduce the space of valid next actions? |
+
+Alongside the embedding scores, three rule-based diagnostics run fully offline
+(no network call, so they still work when the embed endpoint is down):
+`missing_consequence`, `missing_owner`, `missing_next_action`.
+
+### The three commands
+
+| Command | What it does |
+|---------|--------------|
+| `coherence meaning score <file>` | Score one artifact → the JSON below. |
+| `coherence meaning compare <before> <after>` | Signed per-subdimension deltas across a rewrite (the 2-point case). |
+| `coherence meaning trend <f1> <f2> <f3> …` | Trajectory over an ordered series: first differences (f′, velocity) and second differences (f″, acceleration) of each score plus embedding drift. |
+
+All three support `--json` and follow the CLI exit-code policy: `0` success,
+`1` user-input error (missing file, or fewer than 2 files for `trend`), `2`
+environment error — an unreachable embedding endpoint makes `score` exit `2`
+with a hint naming `COHERENCE_EMBED_URL`, while the offline diagnostics still
+run.
+
+`coherence meaning score <file> --json` emits exactly:
+
+```json
+{
+  "meaning_score": 0.73,
+  "subdimensions": {
+    "consequence": 0.81,
+    "agency": 0.62,
+    "causality": 0.78,
+    "affordance": 0.69,
+    "future_constraint": 0.75
+  },
+  "diagnostics": [
+    {"code": "missing_owner", "message": "No responsible party named — name an owner (e.g. @name, 'owned by', 'assigned to')."}
+  ]
+}
+```
+
+Every value is in `[0, 1]`. `subdimensions` is an open map: registering a sixth
+subdimension adds a key here without breaking existing consumers.
+
+### Consumer map — which field drives which decision
+
+The score JSON is designed so a mesh consumer can act on it without human
+translation. Each field maps to a concrete routing or memory decision:
+
+| Consumer | Reads | Decision |
+|----------|-------|----------|
+| **steward** | `meaning_score` | Low `meaning_score` → route the artifact back for clarification / owner assignment before it flows downstream; high `meaning_score` with unclear ownership → ask steward to assign an owner. |
+| **eidetic** | `subdimensions.consequence`, `subdimensions.future_constraint` | Gate memory writes: high on either → store (memory-worthy); low on both → compress or drop rather than persist. |
+| **taskmaster** | `meaning_score`, `subdimensions.agency` | Prioritize the backlog: high `meaning_score` × high `agency` (someone can act) → surface for execution; low `agency` → hold, it needs an owner first. |
+
+The `diagnostics` list is the always-available fallback: even with no embedding
+endpoint, a fired `missing_consequence` / `missing_owner` / `missing_next_action`
+is enough for a consumer to ask for clarification before acting.
+
+### Scope boundary
+
+This MVP ships scoring, comparison, and trend only. **The experiment runner,
+the LLM-judge fallback, and doctor/certify integration are tracked follow-ups
+with no code paths in this repo.** The committed
+[`examples/experiments/issue-priority.yaml`](examples/experiments/issue-priority.yaml)
+is the config *contract* for the deferred phase-3 experiment — every meaning
+feature it names is already emitted by `coherence meaning score`, but nothing
+executes it yet.
+
+## Make it your own
+
+1. Rename the package `coherence/` and the `coherence-cli`
+   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
+   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
+   ~100 places, so list every occurrence first — see the `git grep` discovery
+   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
+2. Edit `culture.yaml` with your `suffix` and `backend`.
+3. Rewrite `CLAUDE.md` for your agent and run `/init`.
+4. Re-vendor only the skills you need from guildmaster (see
+   [`docs/skill-sources.md`](docs/skill-sources.md)).
+
+See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
+the `cicd` PR lane, deploy setup).
+
+## License
+
+Apache 2.0 — see [`LICENSE`](LICENSE).

{coherence_cli-0.4.1 → coherence_cli-0.5.0}/coherence/cli/__init__.py

@@ -66,6 +66,7 @@ def _build_parser() -> argparse.ArgumentParser:
     from coherence.cli._commands import doctor as _doctor_cmd
     from coherence.cli._commands import explain as _explain_cmd
     from coherence.cli._commands import learn as _learn_cmd
+    from coherence.cli._commands import meaning as _meaning_cmd
     from coherence.cli._commands import overview as _overview_cmd
     from coherence.cli._commands import whoami as _whoami_cmd
 
@@ -88,6 +89,7 @@ def _build_parser() -> argparse.ArgumentParser:
     _overview_cmd.register(sub)
     _doctor_cmd.register(sub)
     _cli_group.register(sub)
+    _meaning_cmd.register(sub)
     # Register your own noun groups here:
     #   from coherence.cli._commands import my_noun as _my_noun_group
     #   _my_noun_group.register(sub)

{coherence_cli-0.4.1 → coherence_cli-0.5.0}/coherence/cli/_commands/learn.py

@@ -29,6 +29,9 @@ Commands
   coherence-cli overview           Descriptive snapshot of the agent.
   coherence-cli doctor             Check the agent-identity invariants.
   coherence-cli cli overview       Describe the CLI surface itself.
+  coherence meaning score <file>   Score an artifact's meaning gradient.
+  coherence meaning compare <a> <b>  Signed before/after meaning delta.
+  coherence meaning trend <f>...   Per-step f'/f'' across a series.
 
 Machine-readable output
 -----------------------
@@ -60,6 +63,9 @@ def _as_json_payload() -> dict[str, object]:
             {"path": ["overview"], "summary": "Descriptive snapshot of the agent."},
             {"path": ["doctor"], "summary": "Check the agent-identity invariants."},
             {"path": ["cli", "overview"], "summary": "Describe the CLI surface."},
+            {"path": ["meaning", "score"], "summary": "Score an artifact's meaning gradient."},
+            {"path": ["meaning", "compare"], "summary": "Signed before/after meaning delta."},
+            {"path": ["meaning", "trend"], "summary": "Per-step f'/f'' across a series."},
         ],
         "exit_codes": {
             "0": "success",