Add Meaning Gradient as a measurable coherence dimension

[OriNachum]

Goal

Add Meaning Gradient / Dimension of Meaning support to coherence-cli as a first-class coherence dimension.

Core thesis:

Meaning is the degree to which an artifact constrains future interpretation and action within a context.

This should not start as metaphysics. It should start as an empirical, falsifiable, operational system inside coherence-cli:

1. measure meaning-like signals in artifacts,
2. compare artifacts before/after rewrites,
3. run experiments proving predictive value,
4. use the signal for agent routing, memory, compression, and certification.

Why this belongs in coherence-cli

Do not create a separate meaning-cli yet.

coherence-cli should be the home because meaning is one dimension of coherence:

• Coherence asks: does this artifact hold together and remain useful for future action?
• Meaning Gradient asks: how strongly does this artifact constrain future action?

Meaning should be treated as a subdimension alongside other coherence checks such as contradiction, drift, stale truth, missing intent, missing owner, degraded context, and unclear next action.

Suggested conceptual stack:

coherence-cli      = top-level quality / validity / convergence system
coherence meaning  = Dimension of Meaning experiments and scoring
eidetic-cli        = memory storage and serving
rollout-cli        = propagation / distribution
coherence-cli      = verifies the propagated state converged and still makes sense

Proposed command surface

coherence assess artifact.md
coherence gauge artifact.md

coherence meaning score artifact.md
coherence meaning compare before.md after.md
coherence meaning axis build anchors/high.txt anchors/low.txt
coherence meaning experiment run experiments/issue-priority.yaml
coherence meaning report results/

coherence doctor --dimension meaning
coherence refresh --dimension meaning
coherence certify --dimension meaning

Core model

For any artifact:

x = text, code, issue, decision, story, agent trace, UI, function, PR, task
c = context
o = observer, human or agent

M(x, c, o) = measurable meaning signal

Initial scalar approximation:

M(x) = cosine_similarity(embedding(x), meaning_axis)

Where:

meaning_axis = mean(embeddings(high-meaning anchors)) - mean(embeddings(low-meaning anchors))

High-meaning anchors:

this changes what happens next
this matters to someone
this reveals intention
this creates consequence
this explains why
this gives purpose
this affects identity
this resolves uncertainty
this constrains future action

Low-meaning anchors:

this is incidental
this has no consequence
this is decorative
this is random
this changes nothing
this has no stake
this is mechanical noise
this does not affect what happens next

Preferred multidimensional output

The scalar score is useful, but the real value is in subdimensions:

Meaning = f(
  consequence,
  agency,
  causality,
  value,
  identity,
  coherence,
  novelty,
  affordance,
  emotional_weight,
  future_constraint
)

Most important for Culture.dev / agent orchestration:

1. Consequence — does this change what happens next?
2. Agency — who can act because of this?
3. Causality — does this explain why something happened?
4. Affordance — does this reveal what action is possible?
5. Memory-worthiness — should this be preserved?
6. Routing force — does this imply a responsible owner or agent?
7. Coherence contribution — does this make surrounding context more intelligible?
8. Future constraint — does this reduce the space of valid next actions?

Expected JSON output

{
  "meaning_score": 0.73,
  "subdimensions": {
    "consequence": 0.81,
    "agency": 0.62,
    "causality": 0.78,
    "identity": 0.44,
    "affordance": 0.69,
    "coherence": 0.88,
    "future_constraint": 0.75
  },
  "recommendation": {
    "memory_candidate": true,
    "route_to": "steward",
    "needs_clarification": false
  }
}

Implementation phases

Phase 1: scoring

Add:

coherence meaning score <file>

Responsibilities:

• read an artifact,
• compute a meaning score,
• compute subdimension scores,
• emit structured JSON,
• optionally emit human-readable diagnostics.

Initial implementation can use:

• embeddings,
• anchor-axis projection,
• local LLM judge fallback,
• rule-based diagnostics for missing consequence / owner / next action.

Phase 2: comparison

Add:

coherence meaning compare before.md after.md

Purpose:

Measure whether a rewrite increased consequence, agency, causality, affordance, memory-worthiness, routing force, or future constraint.

Example:

Before:
Refactor auth middleware.

After:
Refactor auth middleware because current branching hides failed authorization paths, making it harder for agents and reviewers to detect privilege escalation bugs.

Expected result:

• higher consequence,
• higher causality,
• higher future constraint,
• higher routing clarity,
• probably higher memory-worthiness.

Phase 3: experiment runner

Add:

coherence meaning experiment run experiments/issue-priority.yaml

Experiment config should support:

name: issue-priority-meaning-gradient
artifact_type: github_issue
input_path: data/issues.jsonl
output_path: results/issue-priority/

ratings:
  - human_meaning_score
  - human_priority_score
  - recall_24h

outcomes:
  - agent_routing_correct
  - agent_summary_inclusion
  - selected_for_execution

features:
  baseline:
    - length
    - sentiment
    - declared_severity
    - reading_difficulty
  semantic:
    - embedding_vector
    - embedding_similarity
  meaning:
    - meaning_score
    - consequence
    - agency
    - causality
    - affordance
    - memory_worthiness
    - routing_force
    - future_constraint

metrics:
  - pearson
  - spearman
  - mae
  - r2
  - auc
  - cross_validation

Phase 4: doctor / repair diagnostics

Add:

coherence doctor --dimension meaning

Detect artifacts that are technically coherent but low in meaning.

Examples:

• issue has task but no reason,
• memory has fact but no consequence,
• PR has changes but no intent,
• agent message has action but no ownership,
• spec has behavior but no decision boundary,
• README explains commands but not why/when to use them.

Suggested diagnostic categories:

missing_consequence
missing_owner
missing_next_action
missing_context
missing_reason
missing_decision_boundary
low_memory_worthiness
low_routing_force
ambiguous_agency

Phase 5: certification gate

Add:

coherence certify --dimension meaning

Purpose:

Gate important artifacts before agents act on them.

Certification checks:

• Is the artifact coherent?
• Is the intent explicit?
• Is the consequence visible?
• Is ownership inferable?
• Is next action constrained?
• Is memory-worthiness clear?
• Is the artifact safe to route, remember, compress, or execute?

First experiment to support

Start with GitHub issues.

Research question:

Can Meaning Gradient predict GitHub issue priority and agent routing correctness better than declared severity, length, and generic embedding similarity?

Dataset:

100-300 GitHub issues

For each issue, collect:

human_meaning_score
human_priority_score
agent_routing_correct
agent_summary_inclusion
selected_for_execution

Features:

length
sentiment
reading_difficulty
declared_severity
embedding_vector
embedding_similarity
meaning_score
consequence
agency
causality
affordance
memory_worthiness
routing_force
future_constraint

Models:

baseline = length + sentiment + severity
semantic = embedding only
meaning = Meaning Gradient only
hybrid = all features

Success criteria:

Meaning Gradient adds predictive value beyond baseline and embedding-only models.

Agent orchestration policies enabled by this

If this works, coherence-cli can provide policy signals to Steward, Guildmaster, Taskmaster, Eidetic, and Colleague agents:

high meaning + high uncertainty => route to Thinker
high meaning + high consequence => route to senior agent or human
high meaning + future relevance => store in Eidetic
high meaning + unclear ownership => ask Steward to assign owner
high meaning + repeated failure => convert to Guildmaster skill or lesson
low meaning + high redundancy => compress aggressively
low meaning + missing consequence => ask for clarification before execution

Falsifiability checklist

The hypothesis becomes weaker if:

• humans cannot rate meaning consistently,
• meaning score is only sentiment in disguise,
• meaning score is only length in disguise,
• meaning score does not predict behavior out-of-sample,
• interventions do not change behavior,
• scores fail across artifact types,
• agents cannot use the score to improve routing or execution.

The hypothesis becomes stronger if:

• humans agree on ratings,
• the score generalizes across artifact types,
• the score predicts human memory and priority,
• the score predicts agent routing and execution,
• interventions improve outcomes,
• coherence-cli can use the score to improve compression, routing, memory, and repair.

Acceptance criteria

Minimum useful version:

• coherence meaning score <file> exists.
• Command returns JSON with meaning_score and at least 4 subdimensions.
• Command detects missing consequence / missing owner / missing next action.
• coherence meaning compare before after exists.
• Example anchors exist under repo fixtures or examples.
• At least one example experiment config exists for GitHub issue priority/routing.
• README explains that Meaning Gradient is a coherence dimension, not a separate CLI.

Good version:

• coherence meaning experiment run executes a simple offline experiment.
• Report compares baseline vs meaning vs hybrid models.
• Doctor mode reports low-meaning artifacts.
• Certification mode can pass/fail important artifacts.

Stretch version:

• Supports pluggable embedding providers.
• Supports local LLM judge fallback.
• Supports Culture.dev routing recommendations.
• Produces machine-readable policy output for Steward / Eidetic / Guildmaster / Taskmaster.

Design principle

Keep the claim practical:

Meaning is measurable if it predicts what humans and agents remember, prioritize, route, trust, and execute.

This issue should implement the instrumentation needed to prove or disprove that.

[OriNachum]

Continuation brief — how to resume this feature

Written so any future session (or another agent) can pick this up cold. Everything referenced is committed on branch spec/meaning-gradient-issue-4 (PR #5, open and green at time of writing — merge it first).

Current state

• Spec (converged): docs/specs/2026-07-04-coherence-cli-ships-meaning-gradient-as-a-measurab.md — scope is phases 1–2 of this issue plus a trajectory extension beyond the issue text: coherence meaning trend <f1> <f2> … emits per-step first differences (f′, velocity) and second differences (f″, acceleration) of both the score signals and embedding drift (cosine distance the artifact moves in embedding space between measurement points). 2+ points → f′, 3+ → f″; per-step unitless differences (time-normalization parked).
• Plan (converged): docs/plans/2026-07-04-coherence-cli-ships-meaning-gradient-as-a-measurab.md — 10 confirmed tasks, all 30 spec coverage targets covered, TDD acceptance criteria on every task.
• Frame + plan state: .devague/ (committed) — the evidence trail: every confirmed claim/honesty condition, parked vagueness v1–v9, plan risks r1–r3. Query with devague show / devague plan show / devague plan waves from the repo root.
• Memory: .eidetic/memory/coherence-cli__public.jsonl — recall with bash .claude/skills/recall/scripts/recall.sh "meaning gradient" before resuming.

Key confirmed decisions (don't relitigate)

1. Meaning is a coherence dimension, not a separate CLI (coherence meaning noun).
2. Scoring = anchor-axis projection: axis = mean(high-anchor embeddings) − mean(low-anchor embeddings), score = cosine(artifact, axis) rescaled to [0,1]. Five MVP subdimensions: consequence, agency, causality, affordance, future_constraint (each with its own anchor pair set; schema is an open map so adding more is non-breaking).
3. numpy + httpx are the package's first runtime dependencies (user-confirmed over stdlib-only, because phase 3 lands in this package next).
4. Embeddings via env-configured OpenAI-compatible endpoint: COHERENCE_EMBED_URL / COHERENCE_EMBED_MODEL, defaulting to the local embed gear eidetic uses (http://localhost:8002/v1, Qwen/Qwen3-Embedding-0.6B). Embed gear down ⇒ exit 2 with hint; rule-based diagnostics still run offline.
5. CI runs offline: integration tests use committed recorded-vector fixtures (real embeddings precomputed once + refresh script). Watch risks r1–r3: stale anchors vs recorded vectors, model-version invalidation, anchor quality unvalidated until real scores exist.

The task graph (waves from devague plan waves)

Wave	Tasks	Files (disjoint per wave)
0	t1 scaffold + deps	pyproject.toml, coherence/meaning/__init__.py
1	t2 embed client ‖ t3 axis+anchors ‖ t4 diagnostics	embed.py ‖ axis.py+anchors/ ‖ diagnostics.py
2	t5 score engine	score.py
3	t6 compare ‖ t7 trend ‖ t9 examples+README	compare.py ‖ trend.py ‖ examples/+README.md
4	t8 CLI wiring + explain catalog	coherence/cli/_commands/meaning.py, coherence/explain/catalog.py
5	t10 fixtures + offline CI tests	tests/fixtures/meaning/, tests/test_meaning_*.py

Acceptance criteria per task are in the plan doc — they are the merge contract; build test-first against them.

How to continue — serial path

1. Merge PR spec+plan: Meaning Gradient coherence dimension (issue #4, phases 1-2 + trend) #5; branch feat/meaning-gradient off fresh main.
2. Work waves 0→5 in order; within a wave, order is free. TDD per task: write the acceptance-criteria tests, implement, bash .claude/skills/run-tests/scripts/… (or uv run pytest -x -q).
3. New CLI noun follows the scaffold conventions: exit codes 0/1/2, --json everywhere, explain-catalog entry, cli overview/learn surfaces updated (t8 criteria list these).
4. Before PR: /version-bump minor (new feature surface), then the cicd skill lane (workflow.sh lint → open → await). One PR per wave is fine; one PR for waves 0–2 and another for 3–5 also works — keep PRs reviewable.

How to continue — /assign-to-workforce path

Prereq: PR #5 merged so the plan is on main. Then, from a session in this repo:

1. Invoke /assign-to-workforce. It reads devague plan waves (scheduling metadata only — devague never orchestrates) and proposes an implementation split plan: task map + per-task agent/model pairing. Human go/no-go gates: the split plan before fan-out, and the final PR.
2. Suggested model split when asked: cheaper/simpler agents for t1, t4, t6, t9 (scaffold, rule-based checks, deltas, docs); stronger agents for t3 (axis math + anchor authoring), t5 (score engine + JSON contract), t7 (trend f′/f″ semantics), t10 (recorded-vector fixture design).
3. One agent per task per wave in isolated git worktrees. File-disjointness per wave was verified at plan time (table above) — keep it true if tasks get re-scoped.
4. The main agent TDD-gates every merge: the task's acceptance-criteria tests plus the full suite must pass before and after each merge, wave by wave.

Whole-feature roadmap (after the MVP lands)

1. Tune anchors against real artifacts (risk r3) — anchors are data, not code; iterate freely, refresh recorded vectors via the t10 script.
2. Phase 3 — experiment runner (parked v4): coherence meaning experiment run + the 100–300 human-rated GitHub-issue dataset. The example config committed at examples/experiments/issue-priority.yaml (t9) is the contract; the falsifiability checklist in this issue's body is the success rubric (especially: is the score just length/sentiment in disguise?).
3. Phases 4–5 — doctor/certify (v5): coherence doctor --dimension meaning, coherence certify --dimension meaning, once base scores are trusted.
4. Stretch (v6–v7): LLM-judge fallback, pluggable embedding providers, and machine-readable routing policy output (route_to, memory_candidate) for steward / eidetic / taskmaster.

Gotchas already paid for (don't re-pay)

• devague's converge gate needs a confirmed honesty condition on every frame claim (audience/boundary/etc.), not just requirements; devague plan confirm takes one task id per call.

• devague exports trip markdownlint MD033 (<file> placeholders) — docs/specs/**, docs/plans/**, .devague/** are lint-ignored as generated artifacts (config + CI glob, since 0.4.1). Don't hand-edit exports; the frame JSON is the source.

• Qodo will flag a spec-only PR as "requirement gaps" (it reads spec docs as unimplemented contracts) — pushback with plan-task references, as done on PR spec+plan: Meaning Gradient coherence dimension (issue #4, phases 1-2 + trend) #5.

• coherence-cli (Claude)