Implement Meaning Gradient MVP per converged plan — 10 tasks, 6 waves (continuation of #4)

[OriNachum]

Implementation tracker for the Meaning Gradient MVP. The scoping leg of #4 is done: PR #5 is merged, so the converged spec, the build plan, and the devague frame state are all on main. This issue carries the guidance to resume implementation cold — in a fresh session, by another agent, or via workforce fan-out.

What's on main (the contract)

• Spec: docs/specs/2026-07-04-coherence-cli-ships-meaning-gradient-as-a-measurab.md — Add Meaning Gradient as a measurable coherence dimension #4 phases 1–2 (score + compare) plus the trajectory extension: 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 moved in embedding space between measurement points). 2+ points → f′, 3+ → f″; per-step unitless differences (time-normalization parked).
• Plan: docs/plans/2026-07-04-coherence-cli-ships-meaning-gradient-as-a-measurab.md — 10 confirmed tasks covering all 30 spec targets (every confirmed claim + honesty condition), TDD acceptance criteria on each. The criteria are the merge contract — build test-first against them.
• Frame/plan state: .devague/ — parked vagueness v1–v9 and risks r1–r3. Query with devague show, devague plan show, devague plan waves.
• Memory: recall before starting — bash .claude/skills/recall/scripts/recall.sh "meaning gradient" surfaces the continuation pointer and the paid-for gotchas.

Confirmed decisions (don't relitigate)

1. Meaning is a coherence dimension — a coherence meaning noun, never a separate CLI.
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 (anchors are plain-text fixtures; the JSON subdimensions map is open, so adding a sixth is non-breaking).
3. numpy + httpx become the package's first runtime dependencies (user-confirmed over stdlib-only; 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). Endpoint down ⇒ exit 2 with an actionable hint; rule-based diagnostics (missing_consequence / missing_owner / missing_next_action) still run offline.
5. CI stays offline: integration tests run from committed recorded-vector fixtures (real embeddings precomputed once, refresh script to regenerate). Mind risks r1–r3: anchors changed without refreshing vectors silently test stale axes; vectors are tied to the embed model version; anchor quality is unvalidated until real scores exist.

Task graph (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

Serial path

1. Branch feat/meaning-gradient off main; work waves 0→5 in order (within a wave, order is free).
2. TDD per task: write the acceptance-criteria tests first, implement, run uv run pytest -x -q (or the run-tests skill).
3. The new noun follows scaffold conventions: exit codes 0/1/2, --json on every verb, explain-catalog entries, cli overview/learn updated (t8's criteria enumerate these).
4. Before each PR: /version-bump minor (new feature surface), then the cicd lane (workflow.sh lint → open → await). One PR per wave, or waves 0–2 + 3–5 as two PRs — keep them reviewable.

/assign-to-workforce path

1. From a session in this repo, invoke /assign-to-workforce. It reads devague plan waves (scheduling metadata only — devague never orchestrates) and proposes the implementation split plan: task map + per-task agent/model pairing. Human gates: the split plan go/no-go before fan-out, and the final PR.
2. Suggested model split: cheaper 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 (f′/f″ semantics), t10 (recorded-vector fixture design).
3. One agent per task per wave, isolated git worktrees. File-disjointness per wave is verified (table above) — keep it true if tasks get re-scoped.
4. The main agent TDD-gates every merge: the task's acceptance tests plus the full suite pass before and after each merge, wave by wave.

Roadmap after the MVP

1. Tune anchors against real artifacts (data change, not code); refresh recorded vectors via the t10 script.
2. Phase 3 (parked v4): coherence meaning experiment run + the 100–300 human-rated issue dataset; examples/experiments/issue-priority.yaml is the config contract; Add Meaning Gradient as a measurable coherence dimension #4's falsifiability checklist is the rubric (especially: is the score just length/sentiment in disguise?).
3. Phases 4–5 (v5): coherence doctor --dimension meaning, coherence certify --dimension meaning once base scores are trusted.
4. Stretch (v6–v7): LLM-judge fallback, pluggable embedding providers, machine-readable routing policy output (route_to, memory_candidate) for steward / eidetic / taskmaster.

Gotchas already paid for

• devague's converge gate needs a confirmed honesty condition on every frame claim, not just requirements; devague plan confirm takes one task id per call.
• devague exports trip markdownlint MD033 — docs/specs/**, docs/plans/**, .devague/** are lint-ignored as generated artifacts since 0.4.1. Don't hand-edit exports; the frame JSON is the source.
• Qodo reads spec-only PRs as "requirement gaps" — pushback with plan-task references (see the four resolved threads on PR spec+plan: Meaning Gradient coherence dimension (issue #4, phases 1-2 + trend) #5).

Full session context: the continuation comment on #4 (#4 (comment)) — superseded by this issue where they differ (that comment predates the merge).

• coherence-cli (Claude)