From a59926ad57243a3fb7227586a17219dbb6b5b0fc Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Mon, 6 Jul 2026 23:31:25 +0300 Subject: [PATCH 1/4] =?UTF-8?q?spec:=20five-domain=20coherence=20engine=20?= =?UTF-8?q?=E2=80=94=20quality,=20meaning,=20signal,=20investiture,=20fram?= =?UTF-8?q?es=20(issues=20#8-#11,=20devague=20/think)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SmwUt5WBBbrUc1vt2RdQYk --- .devague/current | 2 +- ...-ships-as-a-five-domain-coherence-eng.json | 418 ++++++++++++++++++ ...li-ships-as-a-five-domain-coherence-eng.md | 85 ++++ 3 files changed, 504 insertions(+), 1 deletion(-) create mode 100644 .devague/frames/coherence-cli-ships-as-a-five-domain-coherence-eng.json create mode 100644 docs/specs/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md diff --git a/.devague/current b/.devague/current index 6c8cae2..800c3a2 100644 --- a/.devague/current +++ b/.devague/current @@ -1 +1 @@ -coherence-cli-ships-meaning-gradient-as-a-measurab +coherence-cli-ships-as-a-five-domain-coherence-eng diff --git a/.devague/frames/coherence-cli-ships-as-a-five-domain-coherence-eng.json b/.devague/frames/coherence-cli-ships-as-a-five-domain-coherence-eng.json new file mode 100644 index 0000000..aebf81f --- /dev/null +++ b/.devague/frames/coherence-cli-ships-as-a-five-domain-coherence-eng.json @@ -0,0 +1,418 @@ +{ + "slug": "coherence-cli-ships-as-a-five-domain-coherence-eng", + "title": "coherence-cli ships as a five-domain coherence engine \u2014 quality, meaning, signal, investiture, and frames \u2014 so agents can measure, analyze, assess, and predict the coherence of content before acting on it", + "schema_version": 1, + "status": "exported", + "created": "2026-07-06T18:34:01Z", + "updated": "2026-07-06T20:30:52Z", + "claims": [ + { + "id": "c1", + "kind": "announcement", + "text": "coherence-cli ships as a five-domain coherence engine \u2014 quality, meaning, signal, investiture, and frames \u2014 so agents can measure, analyze, assess, and predict the coherence of content before acting on it", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h16", + "text": "the announcement is honest only if all five domains are real at ship time: each has a package home, docs, and at least one working measurement path (meaning already shipped; quality/signal/investiture ship verbs; frames ships as provenance on every embedding-derived output) \u2014 'measure, analyze, assess, predict' each maps to a concrete command", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c2", + "kind": "audience", + "text": "Agentic-mesh consumers of score JSON \u2014 colleague's post-loop coherence gate (first wired consumer), steward, eidetic, taskmaster \u2014 plus the humans operating coherence-cli directly", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h1", + "text": "colleague's coherence gate validates against the restructured meaning JSON without editing its pinned fixture (additive keys only), and the steward/eidetic/taskmaster consumer-map rows in README remain accurate after repositioning", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c3", + "kind": "before_state", + "text": "meaning is the only implemented domain (score/compare/trend, v0.5.0); the README tagline promises claim-quality (freshness/provenance/fidelity) that has NO code behind it; no signal, investiture, or frames code exists; score JSON carries no provenance of the embedding frame that produced it", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h2", + "text": "verifiable by inspection at branch point: no quality/signal/investiture/frames packages exist under coherence/, and the README tagline promises freshness/provenance/fidelity behavior git grep cannot find an implementation for", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c4", + "kind": "after_state", + "text": "coherence-cli is positioned and structured as a five-domain coherence engine: quality, meaning, signal, investiture, frames each have a package home and docs; signal and investiture ship as new CLI nouns; every measurement JSON gains an additive frame/provenance block and a shared envelope direction (domain, score_type, scores, frame, diagnostics); existing meaning commands keep their exact JSON shape modulo additive keys", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h3", + "text": "on the merged result, a fresh checkout shows a package home per domain, signal+investiture registered as CLI nouns, and a diff of 'meaning score --json' output vs v0.5.0 that is purely additive (no key removed, renamed, or retyped)", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c5", + "kind": "why_it_matters", + "text": "The one-domain tagline is now false in both directions (promises unbuilt quality checks, hides shipped meaning measurement); frame provenance makes scores falsifiable (model-relative, anchor-defined, declared gauge) instead of pretending universal meaning; a reusable signal layer means every current and future dimension gets trend/pattern/resonance analysis without reimplementation", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h4", + "text": "after the change, every emitted embedding-derived score JSON names the frame that produced it (model, endpoint, anchor set, projection method), so a consumer can distinguish measurements from different gauges", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c6", + "kind": "success_signal", + "text": "All existing tests keep passing and colleague's pinned 'meaning score --json' fixture still validates (only additive keys); each new noun ships with --json, exit codes 0/1/2, explain-catalog entries, and offline tests; README leads with the five-domain positioning and names claim quality as the first practical domain, not the whole product", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h5", + "text": "CI passes with the pre-existing meaning test assertions unmodified except where they gain additive-key tolerance; every new-noun test runs offline from committed fixtures; 'coherence explain' resolves every new noun/verb path", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c7", + "kind": "boundary", + "text": "No breaking CLI changes: existing meaning commands and their JSON stay valid; renames arrive as aliases or a documented versioned migration, never silently", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h6", + "text": "a pre/post diff of every pre-existing command's output shows only added keys \u2014 no verb, flag, key, or exit-code semantic is removed or renamed in this restructure", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c8", + "kind": "non_goal", + "text": "No FFT / physical wave modeling, no LLM-judge dependency, no cross-model embedding transformations, no gauge-invariant scoring, no proof of long-term behavioral causality \u2014 all documented as planned extensions, not built", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [], + "hard_questions": [], + "links": [] + }, + { + "id": "c9", + "kind": "non_goal", + "text": "No mystical language in CLI output or docs: no literal physics, no literal souls, no universal-meaning claims \u2014 scores are described as model-relative, anchor-defined semantic measurements", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [], + "hard_questions": [], + "links": [] + }, + { + "id": "c10", + "kind": "non_goal", + "text": "No full rewrite: the shipped meaning engine is preserved and reframed as one domain of five, not reimplemented", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [], + "hard_questions": [], + "links": [] + }, + { + "id": "c11", + "kind": "requirement", + "text": "signal noun (#9 MVP): documented source-agnostic series input schema; 'coherence signal trend' (first/second differences + monotonicity/volatility diagnostics), 'coherence signal pattern' (motifs: increasing, decreasing, plateau, spike, reversal, stair-step), 'coherence signal resonance' (pairwise alignment/correlation between numeric fields); harmonic/wave/decay/interference documented as planned; handles n=1, n=2, n=3+ and missing/null/non-numeric values without crashing", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h7", + "text": "the same signal verb accepts a series converted from meaning trend output AND a hand-written series with arbitrary numeric value names (proving source-agnosticism), and tests cover n=1, n=2, n=3+, plus missing/null/non-numeric values without crashing", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c12", + "kind": "requirement", + "text": "investiture noun (#8 MVP): 'coherence investiture score' returns investiture_score, mode, components, evidence, diagnostics \u2014 computed from existing Meaning Gradient subdimensions in mode:estimated, explicitly reporting that persistence/behavioral effect were NOT measured; 'coherence investiture compare' returns before/after scores and signed deltas; trace deferred; calls into coherence.meaning rather than duplicating embedding/axis logic", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h8", + "text": "artifact-only investiture output always carries mode:estimated plus a diagnostic stating persistence/behavioral effect were not measured; with the embed endpoint down it exits 2 with the same actionable hint as meaning (it reuses coherence.meaning, not a duplicate embed path)", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c13", + "kind": "requirement", + "text": "frames domain (#10 MVP): meaning score/compare/trend JSON gains an additive frame block (embedding_model, embedding_endpoint, anchor_set, axis/axes, projection_method, score_type); investiture and signal outputs carry or pass through frame provenance where the source has it; missing provenance is handled explicitly, not silently; explain catalog gains: semantic frame, frame provenance, model-relative score, anchor-relative score, gauge-robust score, field sample, trajectory, signal", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h9", + "text": "the frame block reports the endpoint/model actually used at runtime (resolved env config, not hardcoded defaults); when a signal input lacks provenance the output says so explicitly (null frame + diagnostic) rather than omitting the key", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c14", + "kind": "requirement", + "text": "restructure (#11): package gains clear domain boundaries (quality/, meaning/, signal/, investiture/, frames/ as applicable); README leads with the five-domain coherence-engine positioning and a domains section; measurement JSON documents the shared-envelope direction (domain, score_type, scores, frame, diagnostics) with backward compatibility for existing consumers", + "origin": "user", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h10", + "text": "README + explain catalog present all five domains with claim quality named as the first practical domain; the shared envelope is documented with its two-speed adoption rule; all pre-existing tests still pass", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c15", + "kind": "requirement", + "text": "meaning trend delegates its difference math to the signal layer (coherence.signal.trend) so 'meaning trend' becomes a dimension-specific wrapper and behavior stays identical", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h11", + "text": "meaning trend --json output on the recorded-vector fixtures is byte-identical before and after the delegation refactor", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c16", + "kind": "requirement", + "text": "quality domain MVP (greenfield, replaces #11's 'preserve existing code' premise): 'coherence quality score ' \u2014 fully offline, rule-based first cut scoring freshness (dateable statements present/absent, age when derivable), provenance (source attribution present/absent), fidelity (quoted-vs-paraphrased signals), task validity hooks \u2014 emitting the shared envelope with domain:quality and honest diagnostics for what a heuristic cannot measure", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h12", + "text": "quality score runs with zero network access; its diagnostics name what the heuristics could NOT verify (e.g. source liveness, actual publication date) instead of inflating scores; absence of dateable statements lowers confidence, never fabricates freshness", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c17", + "kind": "requirement", + "text": "predict surface: 'coherence signal forecast ' \u2014 naive next-point extrapolation (linear trend + recent-delta blend) with explicit confidence caveats and a minimum-points guard; documented as extrapolation of a declared frame's signal, not prophecy", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h13", + "text": "forecast exits 1 with a hint below the minimum-points threshold; output is labeled as extrapolation and names the window/method used; a constant series forecasts the constant and a linear series extends the line", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c18", + "kind": "requirement", + "text": "assess surface: 'coherence assess ' \u2014 one verb that runs every applicable domain measurement (quality heuristics, meaning scores, investiture estimate) and emits a single multi-domain report using the shared envelope, with per-domain availability honestly reported (e.g. embed endpoint down means meaning absent, quality still present)", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h14", + "text": "with the embed endpoint down, assess still returns the offline domains (quality, rule-based diagnostics) and explicitly lists meaning/investiture as unavailable \u2014 partial availability is reported, never silently dropped", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c19", + "kind": "decision", + "text": "package layout uses coherence/quality/ (not claims/) \u2014 #11's own criterion prefers quality/ when scope exceeds individual claims, and the greenfield domain is defined broader than claim checks", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [], + "hard_questions": [], + "links": [] + }, + { + "id": "c20", + "kind": "assumption", + "text": "colleague's pinned fixture tolerates additive keys in 'meaning score --json' (its #11 comment commits to passing a native frame block through verbatim), so the frame block can land without a compatibility mode", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h15", + "text": "confirmed against colleague's actual gate fixture (colleague#291/#294): its assertion style is subset/additive-tolerant, or colleague signs off on the additive frame block before this merges", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c21", + "kind": "decision", + "text": "envelope adoption is two-speed: NEW nouns (quality, signal, investiture, assess) emit the full shared envelope (domain, score_type, scores, frame, diagnostics) from day one; EXISTING meaning verbs keep their pinned shape and gain only additive top-level keys (domain, score_type, frame) \u2014 nesting meaning_score/subdimensions under scores is deferred to an explicitly versioned future migration", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [], + "hard_questions": [], + "links": [] + }, + { + "id": "c22", + "kind": "requirement", + "text": "signal resonance reports SIGNED alignment: positively aligned pairs (resonance) and negatively aligned pairs (interference) from the same computation \u2014 answering both 'do these streams reinforce?' and 'do these streams conflict?' in the MVP instead of deferring interference", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h17", + "text": "resonance output on a series where two fields rise together yields a positive pair, and where one rises while another falls yields a negative (interference) pair; both come from one signed metric, not two code paths", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c23", + "kind": "requirement", + "text": "frames becomes a real noun, not just metadata: 'coherence frames inspect ' reports the frame that produced a measurement and whether provenance is complete; 'coherence frames diff ' answers whether two measurements are frame-comparable (same gauge) \u2014 and meaning trend / signal verbs WARN when fed measurements from mixed frames, guarding the silent cross-gauge comparison error", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h18", + "text": "frames inspect on a v0.5.0-era JSON (no frame block) reports missing provenance explicitly instead of erroring; frames diff on two measurements from different embed models reports not-comparable; feeding mixed-frame inputs to trend produces a visible warning, never a silent number", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c24", + "kind": "requirement", + "text": "'coherence signal collect ...' builds a series file (the documented signal input schema) from N envelope-bearing measurement JSONs of any domain \u2014 the glue that turns per-artifact measurements into analyzable/forecastable signals without hand-authoring series files", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h19", + "text": "collect accepts meaning, quality, and investiture score JSONs alike (envelope-driven, no per-domain code), preserves input ordering, carries frame provenance through to the series, and its output validates against the same series schema signal verbs consume", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + }, + { + "id": "c25", + "kind": "requirement", + "text": "'coherence quality compare ' ships alongside quality score \u2014 uniform verb grammar (score/compare) across measuring domains, so rewrites can be evaluated for quality deltas exactly like meaning deltas", + "origin": "llm", + "status": "confirmed", + "honesty_conditions": [ + { + "id": "h20", + "text": "quality compare emits signed per-component deltas mirroring meaning compare's shape, and runs fully offline like quality score", + "status": "confirmed" + } + ], + "hard_questions": [], + "links": [] + } + ], + "open_vagueness": [ + { + "id": "v1", + "text": "harmonic, wave, decay, interference signal analyses \u2014 documented as planned families, built only after real series data exists", + "kind": "follow_up", + "claim_id": null + }, + { + "id": "v2", + "text": "gauge-robustness checks (meaning robustness / signal robustness across models and anchor sets) \u2014 documented as planned extension per #10, needs multiple embed frames available", + "kind": "follow_up", + "claim_id": null + }, + { + "id": "v3", + "text": "investiture trace verb \u2014 needs history/outcome evidence sources (git survival, recall events, downstream references) that do not exist as inputs yet", + "kind": "follow_up", + "claim_id": null + }, + { + "id": "v4", + "text": "meaning experiment runner, doctor --dimension, certify --dimension, LLM-judge fallback, routing-policy output \u2014 already-tracked #4/#6 roadmap, untouched by this restructure", + "kind": "follow_up", + "claim_id": null + }, + { + "id": "v5", + "text": "how far quality heuristics can honestly go without live source fetching (real freshness verification needs network access to sources) \u2014 MVP stays offline-rule-based; depth is unknown until used", + "kind": "unknown_nonblocking", + "claim_id": null + }, + { + "id": "v6", + "text": "freshness half-life / staleness-date prediction (quality x time decay model) \u2014 a real 'predict coherence' direction but needs longitudinal data before a model is honest", + "kind": "follow_up", + "claim_id": null + } + ] +} diff --git a/docs/specs/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md b/docs/specs/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md new file mode 100644 index 0000000..2c6d90e --- /dev/null +++ b/docs/specs/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md @@ -0,0 +1,85 @@ +# coherence-cli ships as a five-domain coherence engine — quality, meaning, signal, investiture, and frames — so agents can measure, analyze, assess, and predict the coherence of content before acting on it + +> coherence-cli ships as a five-domain coherence engine — quality, meaning, signal, investiture, and frames — so agents can measure, analyze, assess, and predict the coherence of content before acting on it + +## Audience + +- Agentic-mesh consumers of score JSON — colleague's post-loop coherence gate (first wired consumer), steward, eidetic, taskmaster — plus the humans operating coherence-cli directly + +## Before → After + +- Before: meaning is the only implemented domain (score/compare/trend, v0.5.0); the README tagline promises claim-quality (freshness/provenance/fidelity) that has NO code behind it; no signal, investiture, or frames code exists; score JSON carries no provenance of the embedding frame that produced it +- After: coherence-cli is positioned and structured as a five-domain coherence engine: quality, meaning, signal, investiture, frames each have a package home and docs; signal and investiture ship as new CLI nouns; every measurement JSON gains an additive frame/provenance block and a shared envelope direction (domain, score_type, scores, frame, diagnostics); existing meaning commands keep their exact JSON shape modulo additive keys + +## Why it matters + +- The one-domain tagline is now false in both directions (promises unbuilt quality checks, hides shipped meaning measurement); frame provenance makes scores falsifiable (model-relative, anchor-defined, declared gauge) instead of pretending universal meaning; a reusable signal layer means every current and future dimension gets trend/pattern/resonance analysis without reimplementation + +## Requirements + +- signal noun (#9 MVP): documented source-agnostic series input schema; 'coherence signal trend' (first/second differences + monotonicity/volatility diagnostics), 'coherence signal pattern' (motifs: increasing, decreasing, plateau, spike, reversal, stair-step), 'coherence signal resonance' (pairwise alignment/correlation between numeric fields); harmonic/wave/decay/interference documented as planned; handles n=1, n=2, n=3+ and missing/null/non-numeric values without crashing + - honesty: the same signal verb accepts a series converted from meaning trend output AND a hand-written series with arbitrary numeric value names (proving source-agnosticism), and tests cover n=1, n=2, n=3+, plus missing/null/non-numeric values without crashing +- investiture noun (#8 MVP): 'coherence investiture score' returns investiture_score, mode, components, evidence, diagnostics — computed from existing Meaning Gradient subdimensions in mode:estimated, explicitly reporting that persistence/behavioral effect were NOT measured; 'coherence investiture compare' returns before/after scores and signed deltas; trace deferred; calls into coherence.meaning rather than duplicating embedding/axis logic + - honesty: artifact-only investiture output always carries mode:estimated plus a diagnostic stating persistence/behavioral effect were not measured; with the embed endpoint down it exits 2 with the same actionable hint as meaning (it reuses coherence.meaning, not a duplicate embed path) +- frames domain (#10 MVP): meaning score/compare/trend JSON gains an additive frame block (embedding_model, embedding_endpoint, anchor_set, axis/axes, projection_method, score_type); investiture and signal outputs carry or pass through frame provenance where the source has it; missing provenance is handled explicitly, not silently; explain catalog gains: semantic frame, frame provenance, model-relative score, anchor-relative score, gauge-robust score, field sample, trajectory, signal + - honesty: the frame block reports the endpoint/model actually used at runtime (resolved env config, not hardcoded defaults); when a signal input lacks provenance the output says so explicitly (null frame + diagnostic) rather than omitting the key +- restructure (#11): package gains clear domain boundaries (quality/, meaning/, signal/, investiture/, frames/ as applicable); README leads with the five-domain coherence-engine positioning and a domains section; measurement JSON documents the shared-envelope direction (domain, score_type, scores, frame, diagnostics) with backward compatibility for existing consumers + - honesty: README + explain catalog present all five domains with claim quality named as the first practical domain; the shared envelope is documented with its two-speed adoption rule; all pre-existing tests still pass +- meaning trend delegates its difference math to the signal layer (coherence.signal.trend) so 'meaning trend' becomes a dimension-specific wrapper and behavior stays identical + - honesty: meaning trend --json output on the recorded-vector fixtures is byte-identical before and after the delegation refactor +- quality domain MVP (greenfield, replaces #11's 'preserve existing code' premise): 'coherence quality score ' — fully offline, rule-based first cut scoring freshness (dateable statements present/absent, age when derivable), provenance (source attribution present/absent), fidelity (quoted-vs-paraphrased signals), task validity hooks — emitting the shared envelope with domain:quality and honest diagnostics for what a heuristic cannot measure + - honesty: quality score runs with zero network access; its diagnostics name what the heuristics could NOT verify (e.g. source liveness, actual publication date) instead of inflating scores; absence of dateable statements lowers confidence, never fabricates freshness +- predict surface: 'coherence signal forecast ' — naive next-point extrapolation (linear trend + recent-delta blend) with explicit confidence caveats and a minimum-points guard; documented as extrapolation of a declared frame's signal, not prophecy + - honesty: forecast exits 1 with a hint below the minimum-points threshold; output is labeled as extrapolation and names the window/method used; a constant series forecasts the constant and a linear series extends the line +- assess surface: 'coherence assess ' — one verb that runs every applicable domain measurement (quality heuristics, meaning scores, investiture estimate) and emits a single multi-domain report using the shared envelope, with per-domain availability honestly reported (e.g. embed endpoint down means meaning absent, quality still present) + - honesty: with the embed endpoint down, assess still returns the offline domains (quality, rule-based diagnostics) and explicitly lists meaning/investiture as unavailable — partial availability is reported, never silently dropped +- signal resonance reports SIGNED alignment: positively aligned pairs (resonance) and negatively aligned pairs (interference) from the same computation — answering both 'do these streams reinforce?' and 'do these streams conflict?' in the MVP instead of deferring interference + - honesty: resonance output on a series where two fields rise together yields a positive pair, and where one rises while another falls yields a negative (interference) pair; both come from one signed metric, not two code paths +- frames becomes a real noun, not just metadata: 'coherence frames inspect ' reports the frame that produced a measurement and whether provenance is complete; 'coherence frames diff ' answers whether two measurements are frame-comparable (same gauge) — and meaning trend / signal verbs WARN when fed measurements from mixed frames, guarding the silent cross-gauge comparison error + - honesty: frames inspect on a v0.5.0-era JSON (no frame block) reports missing provenance explicitly instead of erroring; frames diff on two measurements from different embed models reports not-comparable; feeding mixed-frame inputs to trend produces a visible warning, never a silent number +- 'coherence signal collect ...' builds a series file (the documented signal input schema) from N envelope-bearing measurement JSONs of any domain — the glue that turns per-artifact measurements into analyzable/forecastable signals without hand-authoring series files + - honesty: collect accepts meaning, quality, and investiture score JSONs alike (envelope-driven, no per-domain code), preserves input ordering, carries frame provenance through to the series, and its output validates against the same series schema signal verbs consume +- 'coherence quality compare ' ships alongside quality score — uniform verb grammar (score/compare) across measuring domains, so rewrites can be evaluated for quality deltas exactly like meaning deltas + - honesty: quality compare emits signed per-component deltas mirroring meaning compare's shape, and runs fully offline like quality score + +## Honesty conditions + +- the announcement is honest only if all five domains are real at ship time: each has a package home, docs, and at least one working measurement path (meaning already shipped; quality/signal/investiture ship verbs; frames ships as provenance on every embedding-derived output) — 'measure, analyze, assess, predict' each maps to a concrete command +- colleague's coherence gate validates against the restructured meaning JSON without editing its pinned fixture (additive keys only), and the steward/eidetic/taskmaster consumer-map rows in README remain accurate after repositioning +- verifiable by inspection at branch point: no quality/signal/investiture/frames packages exist under coherence/, and the README tagline promises freshness/provenance/fidelity behavior git grep cannot find an implementation for +- on the merged result, a fresh checkout shows a package home per domain, signal+investiture registered as CLI nouns, and a diff of 'meaning score --json' output vs v0.5.0 that is purely additive (no key removed, renamed, or retyped) +- after the change, every emitted embedding-derived score JSON names the frame that produced it (model, endpoint, anchor set, projection method), so a consumer can distinguish measurements from different gauges +- CI passes with the pre-existing meaning test assertions unmodified except where they gain additive-key tolerance; every new-noun test runs offline from committed fixtures; 'coherence explain' resolves every new noun/verb path +- a pre/post diff of every pre-existing command's output shows only added keys — no verb, flag, key, or exit-code semantic is removed or renamed in this restructure +- confirmed against colleague's actual gate fixture (colleague#291/#294): its assertion style is subset/additive-tolerant, or colleague signs off on the additive frame block before this merges + +## Success signals + +- All existing tests keep passing and colleague's pinned 'meaning score --json' fixture still validates (only additive keys); each new noun ships with --json, exit codes 0/1/2, explain-catalog entries, and offline tests; README leads with the five-domain positioning and names claim quality as the first practical domain, not the whole product + +## Scope / boundaries + +- No breaking CLI changes: existing meaning commands and their JSON stay valid; renames arrive as aliases or a documented versioned migration, never silently + +## Non-goals + +- No FFT / physical wave modeling, no LLM-judge dependency, no cross-model embedding transformations, no gauge-invariant scoring, no proof of long-term behavioral causality — all documented as planned extensions, not built +- No mystical language in CLI output or docs: no literal physics, no literal souls, no universal-meaning claims — scores are described as model-relative, anchor-defined semantic measurements +- No full rewrite: the shipped meaning engine is preserved and reframed as one domain of five, not reimplemented + +## Assumptions + +- colleague's pinned fixture tolerates additive keys in 'meaning score --json' (its #11 comment commits to passing a native frame block through verbatim), so the frame block can land without a compatibility mode + +## Decisions + +- package layout uses coherence/quality/ (not claims/) — #11's own criterion prefers quality/ when scope exceeds individual claims, and the greenfield domain is defined broader than claim checks +- envelope adoption is two-speed: NEW nouns (quality, signal, investiture, assess) emit the full shared envelope (domain, score_type, scores, frame, diagnostics) from day one; EXISTING meaning verbs keep their pinned shape and gain only additive top-level keys (domain, score_type, frame) — nesting meaning_score/subdimensions under scores is deferred to an explicitly versioned future migration + +## Open / follow-up + +- harmonic, wave, decay, interference signal analyses — documented as planned families, built only after real series data exists +- gauge-robustness checks (meaning robustness / signal robustness across models and anchor sets) — documented as planned extension per #10, needs multiple embed frames available +- investiture trace verb — needs history/outcome evidence sources (git survival, recall events, downstream references) that do not exist as inputs yet +- meaning experiment runner, doctor --dimension, certify --dimension, LLM-judge fallback, routing-policy output — already-tracked #4/#6 roadmap, untouched by this restructure +- freshness half-life / staleness-date prediction (quality x time decay model) — a real 'predict coherence' direction but needs longitudinal data before a model is honest From dcb14eb75a2caeb2238ac8e184acf463fb9993eb Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Mon, 6 Jul 2026 23:36:39 +0300 Subject: [PATCH 2/4] =?UTF-8?q?plan:=20five-domain=20restructure=20?= =?UTF-8?q?=E2=80=94=2018=20tasks,=207=20waves=20(devague=20/spec-to-plan)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SmwUt5WBBbrUc1vt2RdQYk --- .devague/current_plan | 2 +- ...-ships-as-a-five-domain-coherence-eng.json | 556 ++++++++++++++++++ ...li-ships-as-a-five-domain-coherence-eng.md | 166 ++++++ 3 files changed, 723 insertions(+), 1 deletion(-) create mode 100644 .devague/plans/coherence-cli-ships-as-a-five-domain-coherence-eng.json create mode 100644 docs/plans/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md diff --git a/.devague/current_plan b/.devague/current_plan index 6c8cae2..800c3a2 100644 --- a/.devague/current_plan +++ b/.devague/current_plan @@ -1 +1 @@ -coherence-cli-ships-meaning-gradient-as-a-measurab +coherence-cli-ships-as-a-five-domain-coherence-eng diff --git a/.devague/plans/coherence-cli-ships-as-a-five-domain-coherence-eng.json b/.devague/plans/coherence-cli-ships-as-a-five-domain-coherence-eng.json new file mode 100644 index 0000000..bc72fe4 --- /dev/null +++ b/.devague/plans/coherence-cli-ships-as-a-five-domain-coherence-eng.json @@ -0,0 +1,556 @@ +{ + "slug": "coherence-cli-ships-as-a-five-domain-coherence-eng", + "title": "coherence-cli ships as a five-domain coherence engine \u2014 quality, meaning, signal, investiture, and frames \u2014 so agents can measure, analyze, assess, and predict the coherence of content before acting on it", + "frame_slug": "coherence-cli-ships-as-a-five-domain-coherence-eng", + "schema_version": 1, + "status": "exported", + "created": "2026-07-06T20:31:49Z", + "updated": "2026-07-06T20:36:20Z", + "targets": [ + { + "id": "c1", + "kind": "announcement", + "text": "coherence-cli ships as a five-domain coherence engine \u2014 quality, meaning, signal, investiture, and frames \u2014 so agents can measure, analyze, assess, and predict the coherence of content before acting on it" + }, + { + "id": "h16", + "kind": "honesty", + "text": "the announcement is honest only if all five domains are real at ship time: each has a package home, docs, and at least one working measurement path (meaning already shipped; quality/signal/investiture ship verbs; frames ships as provenance on every embedding-derived output) \u2014 'measure, analyze, assess, predict' each maps to a concrete command" + }, + { + "id": "c2", + "kind": "audience", + "text": "Agentic-mesh consumers of score JSON \u2014 colleague's post-loop coherence gate (first wired consumer), steward, eidetic, taskmaster \u2014 plus the humans operating coherence-cli directly" + }, + { + "id": "h1", + "kind": "honesty", + "text": "colleague's coherence gate validates against the restructured meaning JSON without editing its pinned fixture (additive keys only), and the steward/eidetic/taskmaster consumer-map rows in README remain accurate after repositioning" + }, + { + "id": "c3", + "kind": "before_state", + "text": "meaning is the only implemented domain (score/compare/trend, v0.5.0); the README tagline promises claim-quality (freshness/provenance/fidelity) that has NO code behind it; no signal, investiture, or frames code exists; score JSON carries no provenance of the embedding frame that produced it" + }, + { + "id": "h2", + "kind": "honesty", + "text": "verifiable by inspection at branch point: no quality/signal/investiture/frames packages exist under coherence/, and the README tagline promises freshness/provenance/fidelity behavior git grep cannot find an implementation for" + }, + { + "id": "c4", + "kind": "after_state", + "text": "coherence-cli is positioned and structured as a five-domain coherence engine: quality, meaning, signal, investiture, frames each have a package home and docs; signal and investiture ship as new CLI nouns; every measurement JSON gains an additive frame/provenance block and a shared envelope direction (domain, score_type, scores, frame, diagnostics); existing meaning commands keep their exact JSON shape modulo additive keys" + }, + { + "id": "h3", + "kind": "honesty", + "text": "on the merged result, a fresh checkout shows a package home per domain, signal+investiture registered as CLI nouns, and a diff of 'meaning score --json' output vs v0.5.0 that is purely additive (no key removed, renamed, or retyped)" + }, + { + "id": "c5", + "kind": "why_it_matters", + "text": "The one-domain tagline is now false in both directions (promises unbuilt quality checks, hides shipped meaning measurement); frame provenance makes scores falsifiable (model-relative, anchor-defined, declared gauge) instead of pretending universal meaning; a reusable signal layer means every current and future dimension gets trend/pattern/resonance analysis without reimplementation" + }, + { + "id": "h4", + "kind": "honesty", + "text": "after the change, every emitted embedding-derived score JSON names the frame that produced it (model, endpoint, anchor set, projection method), so a consumer can distinguish measurements from different gauges" + }, + { + "id": "c6", + "kind": "success_signal", + "text": "All existing tests keep passing and colleague's pinned 'meaning score --json' fixture still validates (only additive keys); each new noun ships with --json, exit codes 0/1/2, explain-catalog entries, and offline tests; README leads with the five-domain positioning and names claim quality as the first practical domain, not the whole product" + }, + { + "id": "h5", + "kind": "honesty", + "text": "CI passes with the pre-existing meaning test assertions unmodified except where they gain additive-key tolerance; every new-noun test runs offline from committed fixtures; 'coherence explain' resolves every new noun/verb path" + }, + { + "id": "c7", + "kind": "boundary", + "text": "No breaking CLI changes: existing meaning commands and their JSON stay valid; renames arrive as aliases or a documented versioned migration, never silently" + }, + { + "id": "h6", + "kind": "honesty", + "text": "a pre/post diff of every pre-existing command's output shows only added keys \u2014 no verb, flag, key, or exit-code semantic is removed or renamed in this restructure" + }, + { + "id": "c11", + "kind": "requirement", + "text": "signal noun (#9 MVP): documented source-agnostic series input schema; 'coherence signal trend' (first/second differences + monotonicity/volatility diagnostics), 'coherence signal pattern' (motifs: increasing, decreasing, plateau, spike, reversal, stair-step), 'coherence signal resonance' (pairwise alignment/correlation between numeric fields); harmonic/wave/decay/interference documented as planned; handles n=1, n=2, n=3+ and missing/null/non-numeric values without crashing" + }, + { + "id": "h7", + "kind": "honesty", + "text": "the same signal verb accepts a series converted from meaning trend output AND a hand-written series with arbitrary numeric value names (proving source-agnosticism), and tests cover n=1, n=2, n=3+, plus missing/null/non-numeric values without crashing" + }, + { + "id": "c12", + "kind": "requirement", + "text": "investiture noun (#8 MVP): 'coherence investiture score' returns investiture_score, mode, components, evidence, diagnostics \u2014 computed from existing Meaning Gradient subdimensions in mode:estimated, explicitly reporting that persistence/behavioral effect were NOT measured; 'coherence investiture compare' returns before/after scores and signed deltas; trace deferred; calls into coherence.meaning rather than duplicating embedding/axis logic" + }, + { + "id": "h8", + "kind": "honesty", + "text": "artifact-only investiture output always carries mode:estimated plus a diagnostic stating persistence/behavioral effect were not measured; with the embed endpoint down it exits 2 with the same actionable hint as meaning (it reuses coherence.meaning, not a duplicate embed path)" + }, + { + "id": "c13", + "kind": "requirement", + "text": "frames domain (#10 MVP): meaning score/compare/trend JSON gains an additive frame block (embedding_model, embedding_endpoint, anchor_set, axis/axes, projection_method, score_type); investiture and signal outputs carry or pass through frame provenance where the source has it; missing provenance is handled explicitly, not silently; explain catalog gains: semantic frame, frame provenance, model-relative score, anchor-relative score, gauge-robust score, field sample, trajectory, signal" + }, + { + "id": "h9", + "kind": "honesty", + "text": "the frame block reports the endpoint/model actually used at runtime (resolved env config, not hardcoded defaults); when a signal input lacks provenance the output says so explicitly (null frame + diagnostic) rather than omitting the key" + }, + { + "id": "c14", + "kind": "requirement", + "text": "restructure (#11): package gains clear domain boundaries (quality/, meaning/, signal/, investiture/, frames/ as applicable); README leads with the five-domain coherence-engine positioning and a domains section; measurement JSON documents the shared-envelope direction (domain, score_type, scores, frame, diagnostics) with backward compatibility for existing consumers" + }, + { + "id": "h10", + "kind": "honesty", + "text": "README + explain catalog present all five domains with claim quality named as the first practical domain; the shared envelope is documented with its two-speed adoption rule; all pre-existing tests still pass" + }, + { + "id": "c15", + "kind": "requirement", + "text": "meaning trend delegates its difference math to the signal layer (coherence.signal.trend) so 'meaning trend' becomes a dimension-specific wrapper and behavior stays identical" + }, + { + "id": "h11", + "kind": "honesty", + "text": "meaning trend --json output on the recorded-vector fixtures is byte-identical before and after the delegation refactor" + }, + { + "id": "c16", + "kind": "requirement", + "text": "quality domain MVP (greenfield, replaces #11's 'preserve existing code' premise): 'coherence quality score ' \u2014 fully offline, rule-based first cut scoring freshness (dateable statements present/absent, age when derivable), provenance (source attribution present/absent), fidelity (quoted-vs-paraphrased signals), task validity hooks \u2014 emitting the shared envelope with domain:quality and honest diagnostics for what a heuristic cannot measure" + }, + { + "id": "h12", + "kind": "honesty", + "text": "quality score runs with zero network access; its diagnostics name what the heuristics could NOT verify (e.g. source liveness, actual publication date) instead of inflating scores; absence of dateable statements lowers confidence, never fabricates freshness" + }, + { + "id": "c17", + "kind": "requirement", + "text": "predict surface: 'coherence signal forecast ' \u2014 naive next-point extrapolation (linear trend + recent-delta blend) with explicit confidence caveats and a minimum-points guard; documented as extrapolation of a declared frame's signal, not prophecy" + }, + { + "id": "h13", + "kind": "honesty", + "text": "forecast exits 1 with a hint below the minimum-points threshold; output is labeled as extrapolation and names the window/method used; a constant series forecasts the constant and a linear series extends the line" + }, + { + "id": "c18", + "kind": "requirement", + "text": "assess surface: 'coherence assess ' \u2014 one verb that runs every applicable domain measurement (quality heuristics, meaning scores, investiture estimate) and emits a single multi-domain report using the shared envelope, with per-domain availability honestly reported (e.g. embed endpoint down means meaning absent, quality still present)" + }, + { + "id": "h14", + "kind": "honesty", + "text": "with the embed endpoint down, assess still returns the offline domains (quality, rule-based diagnostics) and explicitly lists meaning/investiture as unavailable \u2014 partial availability is reported, never silently dropped" + }, + { + "id": "c22", + "kind": "requirement", + "text": "signal resonance reports SIGNED alignment: positively aligned pairs (resonance) and negatively aligned pairs (interference) from the same computation \u2014 answering both 'do these streams reinforce?' and 'do these streams conflict?' in the MVP instead of deferring interference" + }, + { + "id": "h17", + "kind": "honesty", + "text": "resonance output on a series where two fields rise together yields a positive pair, and where one rises while another falls yields a negative (interference) pair; both come from one signed metric, not two code paths" + }, + { + "id": "c23", + "kind": "requirement", + "text": "frames becomes a real noun, not just metadata: 'coherence frames inspect ' reports the frame that produced a measurement and whether provenance is complete; 'coherence frames diff ' answers whether two measurements are frame-comparable (same gauge) \u2014 and meaning trend / signal verbs WARN when fed measurements from mixed frames, guarding the silent cross-gauge comparison error" + }, + { + "id": "h18", + "kind": "honesty", + "text": "frames inspect on a v0.5.0-era JSON (no frame block) reports missing provenance explicitly instead of erroring; frames diff on two measurements from different embed models reports not-comparable; feeding mixed-frame inputs to trend produces a visible warning, never a silent number" + }, + { + "id": "c24", + "kind": "requirement", + "text": "'coherence signal collect ...' builds a series file (the documented signal input schema) from N envelope-bearing measurement JSONs of any domain \u2014 the glue that turns per-artifact measurements into analyzable/forecastable signals without hand-authoring series files" + }, + { + "id": "h19", + "kind": "honesty", + "text": "collect accepts meaning, quality, and investiture score JSONs alike (envelope-driven, no per-domain code), preserves input ordering, carries frame provenance through to the series, and its output validates against the same series schema signal verbs consume" + }, + { + "id": "c25", + "kind": "requirement", + "text": "'coherence quality compare ' ships alongside quality score \u2014 uniform verb grammar (score/compare) across measuring domains, so rewrites can be evaluated for quality deltas exactly like meaning deltas" + }, + { + "id": "h20", + "kind": "honesty", + "text": "quality compare emits signed per-component deltas mirroring meaning compare's shape, and runs fully offline like quality score" + } + ], + "tasks": [ + { + "id": "t1", + "summary": "t1 Shared measurement envelope: coherence/schema.py defining the envelope (domain, score_type, scores, frame, diagnostics) with build/validate helpers + docs/envelope.md documenting the two-speed adoption rule", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "coherence.schema exposes a build_envelope/validate_envelope pair; a valid envelope round-trips and a missing 'domain' or non-dict 'scores' is rejected with a named error", + "docs/envelope.md documents all five envelope fields and states the two-speed rule: new nouns emit full envelope, existing meaning verbs gain only additive top-level keys" + ], + "deps": [], + "covers": [ + "c14" + ] + }, + { + "id": "t2", + "summary": "t2 Frame provenance core: coherence/frames/provenance.py builds the frame block (embedding_model, embedding_endpoint, anchor_set, axis/axes, projection_method, score_type) from the RESOLVED runtime embed config; explicit absent-provenance representation", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "frame block reflects COHERENCE_EMBED_URL/COHERENCE_EMBED_MODEL as resolved at call time (monkeypatched env changes the emitted block; defaults appear only when env is unset)", + "absent provenance is representable as an explicit null-frame with a machine-readable reason, never a missing key" + ], + "deps": [ + "t1" + ], + "covers": [ + "c13" + ] + }, + { + "id": "t3", + "summary": "t3 Signal series schema: coherence/signal/schema.py \u2014 documented source-agnostic series input schema (per-point id/index/timestamp/values + optional per-point frame), robust loader", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "loader accepts a hand-written series with arbitrary numeric value names AND a series converted from meaning trend output (source-agnosticism proven by test)", + "n=1, n=2, n=3+ series load; missing/null/non-numeric values are skipped-with-diagnostic, never a crash", + "the series schema is documented (docs or module docstring referenced from docs) including the optional per-point frame field" + ], + "deps": [ + "t1" + ], + "covers": [ + "c11", + "h7" + ] + }, + { + "id": "t4", + "summary": "t4 signal trend engine: coherence/signal/trend.py \u2014 first/second differences, monotonicity, volatility diagnostics over any numeric series field", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "2 points yield f-prime, 3+ points yield f-double-prime, per field; 1 point yields an explicit too-short diagnostic and no differences", + "monotonicity (increasing/decreasing/mixed) and a simple volatility measure are reported per field" + ], + "deps": [ + "t3" + ], + "covers": [ + "c11" + ] + }, + { + "id": "t5", + "summary": "t5 meaning trend delegation: coherence/meaning/trend.py difference math replaced by calls into coherence.signal.trend; meaning trend becomes a dimension-specific wrapper; mixed-frame warning arrives via the shared path", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "meaning trend --json output on the recorded-vector fixtures is byte-identical before and after the refactor (guarded by a golden-output test)", + "no difference math remains in coherence/meaning/trend.py (only orchestration, output assembly, and meaning-specific labeling)" + ], + "deps": [ + "t4", + "t10" + ], + "covers": [ + "c15", + "h11" + ] + }, + { + "id": "t6", + "summary": "t6 signal pattern engine: coherence/signal/pattern.py \u2014 motif detection: increasing, decreasing, plateau, spike, reversal, stair_step", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "each of the six motifs is detected on a synthetic series constructed to exhibit it, and not detected on a counterexample series", + "short series (n<3) return an explicit insufficient-points diagnostic instead of motifs" + ], + "deps": [ + "t3" + ], + "covers": [ + "c11" + ] + }, + { + "id": "t7", + "summary": "t7 signal resonance engine with SIGNED alignment: coherence/signal/resonance.py \u2014 pairwise correlation between numeric fields; positive pairs reported as resonance, negative pairs as interference, one signed metric", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "two fields rising together yield a positive-alignment pair; one rising while the other falls yields a negative (interference) pair \u2014 from the same code path (test asserts sign symmetry)", + "constant or too-short fields are excluded with a diagnostic, not NaN correlations" + ], + "deps": [ + "t3" + ], + "covers": [ + "c11", + "c22", + "h17" + ] + }, + { + "id": "t8", + "summary": "t8 signal forecast engine: coherence/signal/forecast.py \u2014 naive next-point extrapolation (linear trend + recent-delta blend), minimum-points guard, output labeled as extrapolation naming window/method", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "below the minimum-points threshold the engine raises the user-error path that the CLI maps to exit 1 with a hint", + "a constant series forecasts the constant; a strictly linear series extends the line (both asserted numerically)", + "output includes method name, window used, and an explicit extrapolation label" + ], + "deps": [ + "t4" + ], + "covers": [ + "c17", + "h13" + ] + }, + { + "id": "t9", + "summary": "t9 signal collect: coherence/signal/collect.py \u2014 build a valid series file from N envelope-bearing measurement JSONs of any domain, preserving order and carrying per-point frame provenance", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "collect accepts meaning, quality, and investiture score JSONs in one call (envelope-driven, no per-domain branches) and emits a series that the signal loader validates", + "input ordering is preserved and each point carries the source measurement's frame block (or explicit null-frame)" + ], + "deps": [ + "t3" + ], + "covers": [ + "c24", + "h19" + ] + }, + { + "id": "t10", + "summary": "t10 meaning outputs gain additive envelope keys: score/compare/trend JSON gains top-level domain, score_type, and frame (from coherence.frames.provenance); existing keys untouched", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "meaning score --json contains domain=meaning, a score_type string, and a frame block reporting the runtime-resolved endpoint/model/anchor-set/projection", + "every pre-existing key of score/compare/trend output is byte-identical to v0.5.0 on the recorded fixtures (additive-only proven by golden subset test)", + "with the embed endpoint unreachable, the offline-diagnostics path still emits an explicit null-frame with reason rather than a fabricated frame" + ], + "deps": [ + "t2" + ], + "covers": [ + "c13", + "c7", + "h9" + ] + }, + { + "id": "t11", + "summary": "t11 quality domain engine (greenfield): coherence/quality/heuristics.py + score.py \u2014 offline rule-based freshness (dateable statements, derivable age), provenance (source attribution), fidelity (quote-vs-paraphrase signals); emits full envelope with domain=quality", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "quality score runs with zero network access (test blocks sockets) and emits the shared envelope with domain=quality", + "diagnostics name what heuristics could NOT verify (source liveness, actual publication date) \u2014 asserted present on an artifact with citations", + "an artifact with no dateable statements gets lowered confidence with a diagnostic, never a fabricated freshness score" + ], + "deps": [ + "t1" + ], + "covers": [ + "c16", + "h12" + ] + }, + { + "id": "t12", + "summary": "t12 quality compare: coherence/quality/compare.py \u2014 before/after quality with signed per-component deltas mirroring meaning compare's shape", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "compare emits before/after envelopes plus a delta map whose keys mirror the quality components, all signed", + "runs fully offline like quality score (same socket-blocked test harness)" + ], + "deps": [ + "t11" + ], + "covers": [ + "c25", + "h20" + ] + }, + { + "id": "t13", + "summary": "t13 investiture noun engine: coherence/investiture/score.py + compare.py \u2014 estimated micro-investiture from meaning subdimensions via coherence.meaning (no duplicate embed path); mode, components, evidence, diagnostics; compare with signed deltas", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "score output carries investiture_score, mode=estimated, components (with persistence_signal/integration_signal/behavioral_effect explicitly null), evidence flags, and the missing-behavioral-outcome diagnostic", + "with the embed endpoint unreachable, score surfaces the same exit-2 hint as meaning (proving reuse of coherence.meaning, asserted via shared error type)", + "compare emits before/after scores and signed component deltas; investiture output uses the full shared envelope and passes through the meaning frame block" + ], + "deps": [ + "t10" + ], + "covers": [ + "c12", + "h8" + ] + }, + { + "id": "t14", + "summary": "t14 frames noun: coherence/frames/inspect.py + diff.py + compat.py \u2014 inspect provenance completeness of any measurement JSON; diff two measurements for frame-comparability; mixed-frame guard callable wired into the signal series loader", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "inspect on a v0.5.0-era JSON (no frame block) reports missing provenance explicitly with exit 0 and a diagnostic, not an error", + "diff on two measurements with different embedding_model reports not-comparable with the differing fields named", + "a series with mixed per-point frames produces a visible mixed-frame warning diagnostic when loaded (exercised via the signal loader test), never a silent number" + ], + "deps": [ + "t2", + "t3" + ], + "covers": [ + "c23", + "h18" + ] + }, + { + "id": "t15", + "summary": "t15 assess engine: coherence/assess.py \u2014 run every applicable domain (quality heuristics, meaning scores, investiture estimate) into one multi-domain report using the shared envelope, with per-domain availability honestly reported", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "with the embed endpoint mocked down, assess returns quality + offline diagnostics and lists meaning/investiture as unavailable with reasons (partial availability, exit 0)", + "with the endpoint up (recorded vectors), the report contains one envelope per available domain keyed by domain name" + ], + "deps": [ + "t11", + "t13" + ], + "covers": [ + "c18", + "h14" + ] + }, + { + "id": "t16", + "summary": "t16 CLI wiring for all new nouns: cli/_commands/quality.py, signal.py, investiture.py, frames.py, assess.py + explain catalog entries (incl. semantic frame, frame provenance, model-relative score, anchor-relative score, gauge-robust score, field sample, trajectory, signal) + cli overview/learn updates", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "every new verb (quality score/compare, signal trend/pattern/resonance/forecast/collect, investiture score/compare, frames inspect/diff, assess) supports --json and exit codes 0/1/2 per scaffold conventions", + "coherence explain resolves every new noun/verb path and the eight frame-vocabulary terms; cli overview and learn list all five domains", + "measure/analyze/assess/predict each maps to at least one working command (score verbs / signal verbs / assess / forecast) \u2014 asserted by an explain-catalog or help-surface test" + ], + "deps": [ + "t5", + "t6", + "t7", + "t8", + "t9", + "t12", + "t13", + "t14", + "t15" + ], + "covers": [ + "c1", + "h16" + ] + }, + { + "id": "t17", + "summary": "t17 README + docs restructure: five-domain positioning replaces the tagline, domains section, claim quality named first practical domain, envelope + two-speed rule documented, model-relative anchor-defined language, planned-extensions list (harmonic/wave/decay, robustness, trace, experiment runner)", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "README leads with the five-domain coherence-engine positioning and names claim quality as the first practical domain, not the whole product", + "docs describe scores as model-relative, anchor-defined semantic measurements and anchors as axes/observables; no mystical or universal-meaning language (grep-able banned-terms check)", + "the consumer map (steward/eidetic/taskmaster/colleague) remains present and accurate; deferred work is listed as planned extensions with issue links" + ], + "deps": [ + "t15" + ], + "covers": [ + "c3", + "h2", + "c5", + "h4", + "c14", + "h10" + ] + }, + { + "id": "t18", + "summary": "t18 offline fixtures + integration verification: recorded-vector reuse for investiture/assess, quality/signal fixtures, additive-only pre/post output diff proof, colleague fixture additive-tolerance verification (h15 guard), full suite green", + "origin": "llm", + "status": "confirmed", + "acceptance_criteria": [ + "all new-noun tests run offline from committed fixtures (CI has no embed endpoint); pre-existing meaning assertions unmodified except additive-key tolerance", + "a pre/post diff test proves every pre-existing command's output gained only added keys (no key removed, renamed, or retyped)", + "colleague's gate fixture (colleague#291/#294) is verified additive-tolerant or colleague's sign-off is recorded on the PR before merge", + "a fresh-checkout test asserts a package home per domain and signal+investiture+quality+frames+assess registered as CLI nouns" + ], + "deps": [ + "t16", + "t17" + ], + "covers": [ + "c2", + "h1", + "c4", + "h3", + "c6", + "h5", + "h6" + ] + } + ], + "risks": [ + { + "id": "r1", + "text": "colleague's gate fixture may not be additive-tolerant in practice \u2014 h15 guard requires verification against colleague#291/#294 or colleague sign-off before merge", + "kind": "unknown_nonblocking", + "task_id": "t18" + }, + { + "id": "r2", + "text": "quality heuristics (freshness/provenance/fidelity rules) are unvalidated until run against real artifacts \u2014 scores may need retuning; the honest-diagnostics contract is the mitigation", + "kind": "unknown_nonblocking", + "task_id": "t11" + }, + { + "id": "r3", + "text": "recorded-vector fixtures are tied to the embed model version (inherited meaning-gradient risk r2); investiture/assess reuse them, so an anchor or model change requires the refresh script across MORE test surfaces", + "kind": "unknown_nonblocking", + "task_id": "t18" + } + ] +} diff --git a/docs/plans/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md b/docs/plans/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md new file mode 100644 index 0000000..72f6065 --- /dev/null +++ b/docs/plans/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md @@ -0,0 +1,166 @@ +# Build Plan — coherence-cli ships as a five-domain coherence engine — quality, meaning, signal, investiture, and frames — so agents can measure, analyze, assess, and predict the coherence of content before acting on it + +slug: `coherence-cli-ships-as-a-five-domain-coherence-eng` · status: `exported` · from frame: `coherence-cli-ships-as-a-five-domain-coherence-eng` + +> coherence-cli ships as a five-domain coherence engine — quality, meaning, signal, investiture, and frames — so agents can measure, analyze, assess, and predict the coherence of content before acting on it + +## Tasks + +### t1 — t1 Shared measurement envelope: coherence/schema.py defining the envelope (domain, score_type, scores, frame, diagnostics) with build/validate helpers + docs/envelope.md documenting the two-speed adoption rule + +- covers: c14 +- acceptance: + - coherence.schema exposes a build_envelope/validate_envelope pair; a valid envelope round-trips and a missing 'domain' or non-dict 'scores' is rejected with a named error + - docs/envelope.md documents all five envelope fields and states the two-speed rule: new nouns emit full envelope, existing meaning verbs gain only additive top-level keys + +### t2 — t2 Frame provenance core: coherence/frames/provenance.py builds the frame block (embedding_model, embedding_endpoint, anchor_set, axis/axes, projection_method, score_type) from the RESOLVED runtime embed config; explicit absent-provenance representation + +- depends on: t1 +- covers: c13 +- acceptance: + - frame block reflects COHERENCE_EMBED_URL/COHERENCE_EMBED_MODEL as resolved at call time (monkeypatched env changes the emitted block; defaults appear only when env is unset) + - absent provenance is representable as an explicit null-frame with a machine-readable reason, never a missing key + +### t3 — t3 Signal series schema: coherence/signal/schema.py — documented source-agnostic series input schema (per-point id/index/timestamp/values + optional per-point frame), robust loader + +- depends on: t1 +- covers: c11, h7 +- acceptance: + - loader accepts a hand-written series with arbitrary numeric value names AND a series converted from meaning trend output (source-agnosticism proven by test) + - n=1, n=2, n=3+ series load; missing/null/non-numeric values are skipped-with-diagnostic, never a crash + - the series schema is documented (docs or module docstring referenced from docs) including the optional per-point frame field + +### t4 — t4 signal trend engine: coherence/signal/trend.py — first/second differences, monotonicity, volatility diagnostics over any numeric series field + +- depends on: t3 +- covers: c11 +- acceptance: + - 2 points yield f-prime, 3+ points yield f-double-prime, per field; 1 point yields an explicit too-short diagnostic and no differences + - monotonicity (increasing/decreasing/mixed) and a simple volatility measure are reported per field + +### t6 — t6 signal pattern engine: coherence/signal/pattern.py — motif detection: increasing, decreasing, plateau, spike, reversal, stair_step + +- depends on: t3 +- covers: c11 +- acceptance: + - each of the six motifs is detected on a synthetic series constructed to exhibit it, and not detected on a counterexample series + - short series (n<3) return an explicit insufficient-points diagnostic instead of motifs + +### t7 — t7 signal resonance engine with SIGNED alignment: coherence/signal/resonance.py — pairwise correlation between numeric fields; positive pairs reported as resonance, negative pairs as interference, one signed metric + +- depends on: t3 +- covers: c11, c22, h17 +- acceptance: + - two fields rising together yield a positive-alignment pair; one rising while the other falls yields a negative (interference) pair — from the same code path (test asserts sign symmetry) + - constant or too-short fields are excluded with a diagnostic, not NaN correlations + +### t8 — t8 signal forecast engine: coherence/signal/forecast.py — naive next-point extrapolation (linear trend + recent-delta blend), minimum-points guard, output labeled as extrapolation naming window/method + +- depends on: t4 +- covers: c17, h13 +- acceptance: + - below the minimum-points threshold the engine raises the user-error path that the CLI maps to exit 1 with a hint + - a constant series forecasts the constant; a strictly linear series extends the line (both asserted numerically) + - output includes method name, window used, and an explicit extrapolation label + +### t9 — t9 signal collect: coherence/signal/collect.py — build a valid series file from N envelope-bearing measurement JSONs of any domain, preserving order and carrying per-point frame provenance + +- depends on: t3 +- covers: c24, h19 +- acceptance: + - collect accepts meaning, quality, and investiture score JSONs in one call (envelope-driven, no per-domain branches) and emits a series that the signal loader validates + - input ordering is preserved and each point carries the source measurement's frame block (or explicit null-frame) + +### t10 — t10 meaning outputs gain additive envelope keys: score/compare/trend JSON gains top-level domain, score_type, and frame (from coherence.frames.provenance); existing keys untouched + +- depends on: t2 +- covers: c13, c7, h9 +- acceptance: + - meaning score --json contains domain=meaning, a score_type string, and a frame block reporting the runtime-resolved endpoint/model/anchor-set/projection + - every pre-existing key of score/compare/trend output is byte-identical to v0.5.0 on the recorded fixtures (additive-only proven by golden subset test) + - with the embed endpoint unreachable, the offline-diagnostics path still emits an explicit null-frame with reason rather than a fabricated frame + +### t11 — t11 quality domain engine (greenfield): coherence/quality/heuristics.py + score.py — offline rule-based freshness (dateable statements, derivable age), provenance (source attribution), fidelity (quote-vs-paraphrase signals); emits full envelope with domain=quality + +- depends on: t1 +- covers: c16, h12 +- acceptance: + - quality score runs with zero network access (test blocks sockets) and emits the shared envelope with domain=quality + - diagnostics name what heuristics could NOT verify (source liveness, actual publication date) — asserted present on an artifact with citations + - an artifact with no dateable statements gets lowered confidence with a diagnostic, never a fabricated freshness score + +### t12 — t12 quality compare: coherence/quality/compare.py — before/after quality with signed per-component deltas mirroring meaning compare's shape + +- depends on: t11 +- covers: c25, h20 +- acceptance: + - compare emits before/after envelopes plus a delta map whose keys mirror the quality components, all signed + - runs fully offline like quality score (same socket-blocked test harness) + +### t13 — t13 investiture noun engine: coherence/investiture/score.py + compare.py — estimated micro-investiture from meaning subdimensions via coherence.meaning (no duplicate embed path); mode, components, evidence, diagnostics; compare with signed deltas + +- depends on: t10 +- covers: c12, h8 +- acceptance: + - score output carries investiture_score, mode=estimated, components (with persistence_signal/integration_signal/behavioral_effect explicitly null), evidence flags, and the missing-behavioral-outcome diagnostic + - with the embed endpoint unreachable, score surfaces the same exit-2 hint as meaning (proving reuse of coherence.meaning, asserted via shared error type) + - compare emits before/after scores and signed component deltas; investiture output uses the full shared envelope and passes through the meaning frame block + +### t14 — t14 frames noun: coherence/frames/inspect.py + diff.py + compat.py — inspect provenance completeness of any measurement JSON; diff two measurements for frame-comparability; mixed-frame guard callable wired into the signal series loader + +- depends on: t2, t3 +- covers: c23, h18 +- acceptance: + - inspect on a v0.5.0-era JSON (no frame block) reports missing provenance explicitly with exit 0 and a diagnostic, not an error + - diff on two measurements with different embedding_model reports not-comparable with the differing fields named + - a series with mixed per-point frames produces a visible mixed-frame warning diagnostic when loaded (exercised via the signal loader test), never a silent number + +### t15 — t15 assess engine: coherence/assess.py — run every applicable domain (quality heuristics, meaning scores, investiture estimate) into one multi-domain report using the shared envelope, with per-domain availability honestly reported + +- depends on: t11, t13 +- covers: c18, h14 +- acceptance: + - with the embed endpoint mocked down, assess returns quality + offline diagnostics and lists meaning/investiture as unavailable with reasons (partial availability, exit 0) + - with the endpoint up (recorded vectors), the report contains one envelope per available domain keyed by domain name + +### t17 — t17 README + docs restructure: five-domain positioning replaces the tagline, domains section, claim quality named first practical domain, envelope + two-speed rule documented, model-relative anchor-defined language, planned-extensions list (harmonic/wave/decay, robustness, trace, experiment runner) + +- depends on: t15 +- covers: c3, h2, c5, h4, c14, h10 +- acceptance: + - README leads with the five-domain coherence-engine positioning and names claim quality as the first practical domain, not the whole product + - docs describe scores as model-relative, anchor-defined semantic measurements and anchors as axes/observables; no mystical or universal-meaning language (grep-able banned-terms check) + - the consumer map (steward/eidetic/taskmaster/colleague) remains present and accurate; deferred work is listed as planned extensions with issue links + +### t5 — t5 meaning trend delegation: coherence/meaning/trend.py difference math replaced by calls into coherence.signal.trend; meaning trend becomes a dimension-specific wrapper; mixed-frame warning arrives via the shared path + +- depends on: t4, t10 +- covers: c15, h11 +- acceptance: + - meaning trend --json output on the recorded-vector fixtures is byte-identical before and after the refactor (guarded by a golden-output test) + - no difference math remains in coherence/meaning/trend.py (only orchestration, output assembly, and meaning-specific labeling) + +### t16 — t16 CLI wiring for all new nouns: cli/_commands/quality.py, signal.py, investiture.py, frames.py, assess.py + explain catalog entries (incl. semantic frame, frame provenance, model-relative score, anchor-relative score, gauge-robust score, field sample, trajectory, signal) + cli overview/learn updates + +- depends on: t5, t6, t7, t8, t9, t12, t13, t14, t15 +- covers: c1, h16 +- acceptance: + - every new verb (quality score/compare, signal trend/pattern/resonance/forecast/collect, investiture score/compare, frames inspect/diff, assess) supports --json and exit codes 0/1/2 per scaffold conventions + - coherence explain resolves every new noun/verb path and the eight frame-vocabulary terms; cli overview and learn list all five domains + - measure/analyze/assess/predict each maps to at least one working command (score verbs / signal verbs / assess / forecast) — asserted by an explain-catalog or help-surface test + +### t18 — t18 offline fixtures + integration verification: recorded-vector reuse for investiture/assess, quality/signal fixtures, additive-only pre/post output diff proof, colleague fixture additive-tolerance verification (h15 guard), full suite green + +- depends on: t16, t17 +- covers: c2, h1, c4, h3, c6, h5, h6 +- acceptance: + - all new-noun tests run offline from committed fixtures (CI has no embed endpoint); pre-existing meaning assertions unmodified except additive-key tolerance + - a pre/post diff test proves every pre-existing command's output gained only added keys (no key removed, renamed, or retyped) + - colleague's gate fixture (colleague#291/#294) is verified additive-tolerant or colleague's sign-off is recorded on the PR before merge + - a fresh-checkout test asserts a package home per domain and signal+investiture+quality+frames+assess registered as CLI nouns + +## Risks + +- [unknown_nonblocking] colleague's gate fixture may not be additive-tolerant in practice — h15 guard requires verification against colleague#291/#294 or colleague sign-off before merge (task t18) +- [unknown_nonblocking] quality heuristics (freshness/provenance/fidelity rules) are unvalidated until run against real artifacts — scores may need retuning; the honest-diagnostics contract is the mitigation (task t11) +- [unknown_nonblocking] recorded-vector fixtures are tied to the embed model version (inherited meaning-gradient risk r2); investiture/assess reuse them, so an anchor or model change requires the refresh script across MORE test surfaces (task t18) From 924ab7c74ba042350cd867842ed5f918f0b8f735 Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Mon, 6 Jul 2026 23:37:06 +0300 Subject: [PATCH 3/4] chore: bump version to 0.5.1 (spec+plan for five-domain restructure) Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SmwUt5WBBbrUc1vt2RdQYk --- CHANGELOG.md | 8 ++++++++ pyproject.toml | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4906851..0c1fbbf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ 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.1] - 2026-07-06 + +### Added + +- Converged devague spec for the five-domain coherence engine restructure — quality, meaning, signal, investiture, frames (issues #8/#9/#10/#11 plus confirmed additions: quality score/compare MVP, signal forecast, assess verb, signed resonance/interference, frames inspect/diff with mixed-frame guard, signal collect): docs/specs/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md +- Build plan (18 tasks, 7 file-disjoint waves) covering all 38 spec targets with TDD acceptance criteria: docs/plans/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md +- Frame decisions on record: two-speed envelope adoption (new nouns emit full domain/score_type/scores/frame/diagnostics envelope; existing meaning verbs gain only additive keys), coherence/quality/ layout over claims/, meaning trend delegating to the signal layer byte-identically + ## [0.5.0] - 2026-07-04 ### Added diff --git a/pyproject.toml b/pyproject.toml index 8be00b9..fb1c072 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "coherence-cli" -version = "0.5.0" +version = "0.5.1" description = "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." readme = "README.md" license = "Apache-2.0" From 4e3ff54024060abfd4d4e069e9dfacb6cdcdb422 Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Mon, 6 Jul 2026 23:39:22 +0300 Subject: [PATCH 4/4] chore: uv.lock version sync + eidetic memory (spec-session record, recall reinforcement) Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SmwUt5WBBbrUc1vt2RdQYk --- .eidetic/memory/coherence-cli__public.jsonl | 13 +++++++------ uv.lock | 2 +- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/.eidetic/memory/coherence-cli__public.jsonl b/.eidetic/memory/coherence-cli__public.jsonl index 08c949c..d6d44f2 100644 --- a/.eidetic/memory/coherence-cli__public.jsonl +++ b/.eidetic/memory/coherence-cli__public.jsonl @@ -1,7 +1,8 @@ -{"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": "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": "2026-07-06T18:32:32.537944+00:00", "recall_count": 1, "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 ``` fences or `{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=\"`, and PR bugs: `.../api/issues/search?componentKeys=...&pullRequest=&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}} +{"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 ``` fences or `{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": "2026-07-06T18:32:32.697837+00:00", "recall_count": 2, "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": "2026-07-06T18:32:32.697837+00:00", "recall_count": 3, "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": "2026-07-06T17:57:02.889118+00:00", "recall_count": 1, "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=\"`, and PR bugs: `.../api/issues/search?componentKeys=...&pullRequest=&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": "2026-07-06T18:32:32.537944+00:00", "recall_count": 2, "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": "2026-07-06T18:32:32.697837+00:00", "recall_count": 3, "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}} +{"id": "five-domain-spec-plan-2026-07-06", "hash": "1f20c10063196eb77f5e2e3b8f2f35a0f7fdf4edb7cf5d32e7025b6f1a2f3381", "content": "Five-domain restructure SPEC+PLAN converged and PR-ed (branch spec/five-domains-issues-8-11, v0.5.1): frame coherence-cli-ships-as-a-five-domain-coherence-eng covers issues #8/#9/#10/#11 in one architecture. Key decisions ON RECORD (do not relitigate): (1) quality domain is GREENFIELD \u2014 #11 premise of preserving existing claim-quality code was false, nothing implements the tagline; MVP = offline rule-based quality score+compare with honest cant-verify diagnostics. (2) TWO-SPEED ENVELOPE: new nouns (quality/signal/investiture/assess) emit full envelope {domain, score_type, scores, frame, diagnostics} from day one; existing meaning verbs gain ONLY additive top-level keys (domain, score_type, frame) \u2014 colleague pinned fixture must stay valid, verify additive-tolerance vs colleague#291/#294 before merging implementation (plan risk r1, task t18 gate). (3) meaning trend delegates difference math to coherence.signal.trend, gated by byte-identical golden test on recorded fixtures. (4) User-approved additions beyond issues: signal forecast (the predict surface), assess verb, SIGNED resonance (interference = negative pairs, same code path), frames inspect/diff + mixed-frame guard, signal collect (score JSONs to series glue). (5) coherence/quality/ layout, not claims/. Plan = 18 tasks / 7 file-disjoint waves covering all 38 targets; implement via /assign-to-workforce or serial waves 0-6.", "scope": {"name": "coherence-cli", "visibility": "public"}, "metadata": {"type": "project", "record_metadata": {"topic": "five-domain restructure", "issues": "#8 #9 #10 #11", "date": "2026-07-06", "source": "spec session (think + spec-to-plan)"}, "created": "2026-07-06T20:39:08.742388+00:00", "last_recall": null, "recall_count": 0, "links": [], "supersedes": null, "lifecycle": "active", "added_by": null}} diff --git a/uv.lock b/uv.lock index 0664e89..4671cb6 100644 --- a/uv.lock +++ b/uv.lock @@ -85,7 +85,7 @@ wheels = [ [[package]] name = "coherence-cli" -version = "0.4.1" +version = "0.5.1" source = { editable = "." } dependencies = [ { name = "httpx" },