spec+plan: five-domain coherence engine — quality, meaning, signal, investiture, frames (issues #8-#11)

[OriNachum]

What

The scoping leg for the five-domain restructure: a converged devague spec and a build plan (18 tasks, 7 file-disjoint waves) covering issues #8, #9, #10, and #11 in one architecture, plus user-confirmed additions. No behavior changes in this PR — docs, frame state, and a patch version bump only (same shape as the meaning-gradient scoping PR #5).

• Spec: docs/specs/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md — 19 confirmed claims, 20 confirmed honesty conditions, 6 parked follow-ups.
• Plan: docs/plans/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md — 18 tasks with TDD acceptance criteria covering all 38 spec targets; devague plan waves verifies 7 waves, file-disjoint within each wave.
• Frame/plan state: .devague/ (committed) — the evidence trail for every confirmed decision.

Scope decisions on record

1. Five domains: quality, meaning, signal, investiture, frames — meaning (shipped in 0.5.0) becomes one domain of five; the restructure adds the other four per Restructure coherence-cli around coherence domains: quality, meaning, signal, investiture, and frames #11.
2. Quality is greenfield: Restructure coherence-cli around coherence domains: quality, meaning, signal, investiture, and frames #11's "preserve existing claim-quality code" premise is corrected — no such code exists (the tagline promised it; nothing implements it). The plan ships an offline rule-based quality score + quality compare MVP with honest can't-verify diagnostics.
3. Two-speed envelope: new nouns emit the full shared envelope (domain, score_type, scores, frame, diagnostics) from day one; existing meaning verbs gain only additive top-level keys — colleague's pinned meaning score --json fixture stays valid (verification against colleague#291/#294 is a merge gate, task t18 / risk r1).
4. User-confirmed additions beyond the issues: signal forecast (the "predict" surface), assess (one-verb multi-domain report), signed resonance (interference pairs for free, pulling Add reusable signal analysis layer for trend, pattern, harmonic, wave, resonance, and decay #9's interference family into the MVP), frames inspect/frames diff + a mixed-frame guard (blocks silent cross-gauge comparison), signal collect (score JSONs → series glue).
5. meaning trend delegates its difference math to coherence.signal.trend, gated by a byte-identical golden-output test on the recorded fixtures.

Wave map

Wave	Tasks
0	t1 shared envelope
1	t2 frame provenance ‖ t3 signal schema ‖ t11 quality engine
2	t4 trend ‖ t6 pattern ‖ t7 resonance± ‖ t9 collect ‖ t10 meaning+frame ‖ t12 quality compare ‖ t14 frames noun
3	t5 meaning-trend delegation ‖ t8 forecast ‖ t13 investiture
4	t15 assess
5	t16 CLI wiring + explain catalog ‖ t17 README/docs
6	t18 offline fixtures + integration verification

Refs

• Closes nothing yet — implementation follows per the plan. Tracks Restructure coherence-cli around coherence domains: quality, meaning, signal, investiture, and frames #11 (restructure), Add reusable signal analysis layer for trend, pattern, harmonic, wave, resonance, and decay #9 (signal), Add investiture CLI noun for meaning-as-causal-imprint measurement #8 (investiture), Add semantic frame provenance and gauge-robust measurement concepts #10 (frames); Add Meaning Gradient as a measurable coherence dimension #4/Implement Meaning Gradient MVP per converged plan — 10 tasks, 6 waves (continuation of #4) #6 roadmap items stay parked as follow-ups.
• Risks on record: colleague fixture additive-tolerance (r1, merge gate), unvalidated quality heuristics (r2), recorded-vector/model-version coupling now spanning more test surfaces (r3).

🤖 Generated with Claude Code

https://claude.ai/code/session_01SmwUt5WBBbrUc1vt2RdQYk

• coherence-cli (Claude)

[OriNachum]

/agentic_review

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[qodo-code-review]

PR Summary by Qodo

Spec+plan five-domain coherence engine restructure (issues #8-#11)

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Add converged spec + build plan for five-domain restructure
 (quality/meaning/signal/investiture/frames).
• Commit devague frame/plan exports and eidetic memory record as the decision evidence trail.
• Bump patch version to 0.5.1 and document the release in CHANGELOG.

Diagram

graph TD
  A["This PR"] --> B["Spec + Plan (docs)"] --> C["Devague exports"] --> D["Implementation waves"] --> E["Five domains"] --> F["Shared JSON envelope"]
  E --> G["CLI nouns/verbs"]
  F --> H["Downstream consumers"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Split into four separate spec/plan PRs (one per issue)

• ➕ Smaller diffs and shorter review cycles per topic
• ➕ Clearer ownership boundaries per domain/issue
• ➖ Harder to guarantee cross-domain coherence (envelope + frames + compatibility rules span all domains)
• ➖ Higher chance of mismatched terminology and duplicated decisions

2. Keep only Markdown docs; do not commit .devague JSON exports

• ➕ Less repository noise and smaller diffs
• ➕ Avoids committing tool-generated artifacts
• ➖ Loses the auditable decision trail (confirmed claims/honesty conditions/risks) that the plan references
• ➖ Makes later disputes/regressions harder to resolve (no canonical exported state)

3. Track plan exclusively in GitHub Issues/Projects instead of docs/plans

• ➕ Native assignment/status tracking
• ➕ Easier progress visibility for contributors
• ➖ Acceptance criteria + wave/file-disjoint constraints are less durable and harder to keep in sync
• ➖ Plan becomes less reviewable as a single coherent artifact

Recommendation: Keep the unified spec+plan in-repo and commit the devague exports as done here, because the central risk/compatibility constraints (two-speed envelope, additive meaning JSON, mixed-frame guard, delegation of meaning trend) are cross-cutting and benefit from a single converged architecture. If repo noise becomes an issue later, consider adding tooling/CI conventions around devague export updates rather than removing the evidence trail.

Files changed (9) +1243 / -9

Documentation (6) +1240 / -6

coherence-cli-ships-as-a-five-domain-coherence-eng.jsonAdd exported devague frame (claims + honesty conditions) +418/-0

Add exported devague frame (claims + honesty conditions)

• Adds the exported devague frame JSON capturing confirmed claims, honesty conditions, decisions, and follow-ups for the five-domain restructure scope.

.devague/frames/coherence-cli-ships-as-a-five-domain-coherence-eng.json

coherence-cli-ships-as-a-five-domain-coherence-eng.jsonAdd exported devague plan (18 tasks / 7 waves / risks) +556/-0

Add exported devague plan (18 tasks / 7 waves / risks)

• Adds the exported devague plan JSON enumerating targets, tasks with TDD acceptance criteria, dependencies, and recorded risks for implementing the five-domain restructure.

.devague/plans/coherence-cli-ships-as-a-five-domain-coherence-eng.json

coherence-cli__public.jsonlRecord five-domain spec+plan memory and update recall metadata +7/-6

Record five-domain spec+plan memory and update recall metadata

• Appends a new eidetic memory record summarizing the five-domain spec+plan decisions and merge gates, and updates recall timestamps/counts for existing operational notes.

.eidetic/memory/coherence-cli__public.jsonl

CHANGELOG.mdAdd 0.5.1 changelog entry for spec+plan release +8/-0

Add 0.5.1 changelog entry for spec+plan release

• Documents the 0.5.1 release as a documentation/planning milestone, including spec/plan locations and key recorded decisions (two-speed envelope, frame provenance, delegation intent).

CHANGELOG.md

2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.mdPublish the five-domain implementation plan (18 tasks) +166/-0

Publish the five-domain implementation plan (18 tasks)

• Adds a build plan with 18 tasks, acceptance criteria, and risks, organized into waves intended to be file-disjoint within each wave.

docs/plans/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md

2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.mdPublish the five-domain converge spec (scope + requirements) +85/-0

Publish the five-domain converge spec (scope + requirements)

• Adds the converged spec defining the five domains, backward-compatibility constraints (additive-only meaning JSON), planned commands, and non-goals/follow-ups.

docs/specs/2026-07-06-coherence-cli-ships-as-a-five-domain-coherence-eng.md

Other (3) +3 / -3

currentPoint devague to the new five-domain frame +1/-1

Point devague to the new five-domain frame

• Updates the devague current frame pointer to the five-domain coherence engine slug.

.devague/current

current_planPoint devague to the new five-domain plan +1/-1

Point devague to the new five-domain plan

• Updates the devague current plan pointer to the five-domain coherence engine slug.

.devague/current_plan

pyproject.tomlBump project version to 0.5.1 +1/-1

Bump project version to 0.5.1

• Updates the package version from 0.5.0 to 0.5.1 to reflect the spec+plan milestone.

pyproject.toml