dialectical-framework 1.6.7__tar.gz → 1.7.0__tar.gz

{dialectical_framework-1.6.7 → dialectical_framework-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dialectical-framework
-Version: 1.6.7
+Version: 1.7.0
 Summary: A dialectical framework for augmented intelligence. AI reasoning powered with dialectics supports humans in: system optimization (psychology, engineering, business, politics, etc.); dispute resolution (mediation, conflicts, negotiations, etc.); decision-making (dilemmas, challenging situations, win-win, etc.).
 License: MIT
 Keywords: dialectics,dialectical-reasoning,synthesis,thesis-antithesis,ai,artificial-intelligence,llm,reasoning-framework,philosophy,logic,argumentation,conflict-resolution,decision-making,critical-thinking,semantic-graph,mirascope,pydantic,perspectives,polarity-reasoning

{dialectical_framework-1.6.7 → dialectical_framework-1.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dialectical-framework"
-version = "1.6.7"
+version = "1.7.0"
 description = "A dialectical framework for augmented intelligence. AI reasoning powered with dialectics supports humans in: system optimization (psychology, engineering, business, politics, etc.); dispute resolution (mediation, conflicts, negotiations, etc.); decision-making (dilemmas, challenging situations, win-win, etc.)."
 authors = ["Evaldas Taroza <evaldas@dialexity.com>"]
 readme = "README.md"

{dialectical_framework-1.6.7 → dialectical_framework-1.7.0}/src/dialectical_framework/agents/advisor/advisor.py

@@ -22,7 +22,9 @@ from dialectical_framework.agents.advisor.system_prompts import \
 from dialectical_framework.agents.agent_context import agent_scope
 from dialectical_framework.agents.conversation_facilitator import \
     ConversationFacilitator
+from dialectical_framework.agents.app_spec import AppSpec, resolve_app_layer
 from dialectical_framework.agents.stream_events import StreamEvent
+from dialectical_framework.agents.toolsets import merge_app_tools
 
 logger = logging.getLogger(__name__)
 
@@ -55,20 +57,32 @@ class Advisor:
 
     Usage (fresh start):
         with scope(case.sid):
-            advisor = Advisor(app_preamble=COUNSELOR_APP)
+            advisor = Advisor(app_preamble=COUNSELOR_PERSONA)
             response = await advisor.chat("My son started smoking...")
 
     Usage (post-analysis, rich graph exists):
         with scope(case.sid):
             context = await DialecticalContext().resolve()
-            advisor = Advisor(app_preamble=COUNSELOR_APP, dialectical_context=context)
+            advisor = Advisor(app_preamble=COUNSELOR_PERSONA, dialectical_context=context)
             response = await advisor.chat("I want to talk through what we found...")
 
     Usage (resuming conversation):
         with scope(case.sid):
-            advisor = Advisor(app_preamble=COUNSELOR_APP, messages=saved_messages)
+            advisor = Advisor(app_preamble=COUNSELOR_PERSONA, messages=saved_messages)
             response = await advisor.chat("What about the other angle?")
 
+    Usage (app-provided domain tools):
+        # The app brings field knowledge two ways: prose in the preamble,
+        # and callable resources as app @llm.tool functions. The engine
+        # prompt carries no docs for app tools (their tool-schema docstrings
+        # travel to the LLM automatically) — introduce them and their usage
+        # rules in the app preamble, where domain vocabulary lives.
+        with scope(case.sid):
+            advisor = Advisor(
+                app_preamble=ASTRO_COUNSELOR_PERSONA,  # explains when to consult the chart
+                app_tools=[lookup_natal_chart],   # @llm.tool from the app
+            )
+
     Usage (Advisor mode of an exploration session — Explorer handover):
         # User was chatting in Explorer (operator mode) and asks "what does
         # this all mean for me?" — the host toggles to counsel mode by
@@ -76,7 +90,7 @@ class Advisor:
         # exploration:
         with scope(case.sid):
             advisor = Advisor(
-                app_preamble=EXPLORATION_ADVISOR_APP,
+                app_preamble=NAVIGATOR_APP_EXPLORER_AGENT_COUNSELOR_REGISTER,
                 nexus_hash=explorer.nexus_hash,
                 messages=explorer.messages,
             )
@@ -104,13 +118,28 @@ class Advisor:
         dialectical_context: Optional[str] = None,
         messages: Optional[list] = None,
         nexus_hash: Optional[str] = None,
+        app_tools: Optional[list] = None,
+        app: Optional[AppSpec] = None,
     ) -> None:
         self._nexus_hash = nexus_hash
+        # app: declarative app definition — composition depends on the mode:
+        # counsel toggle (nexus_hash set) keeps the Navigator contract
+        # (NAVIGATOR_APP_EXPLORER_AGENT_COUNSELOR_REGISTER + voicing + tool_guide); standalone uses
+        # the spec's advisor_persona (machinery hidden). See AppSpec.
+        app_preamble, app_tools = resolve_app_layer(
+            app,
+            app_preamble,
+            app_tools,
+            preamble_for="advisor_scoped" if nexus_hash else "advisor_unscoped",
+        )
         if nexus_hash:
             self._validate_nexus(nexus_hash)
             self._tools = _build_scoped_tools(nexus_hash)
         else:
             self._tools = _build_tools()
+        # App-provided @llm.tool functions (domain resources: chart lookups,
+        # methodology references, ...) — see toolsets.merge_app_tools.
+        self._tools = merge_app_tools(self._tools, app_tools)
         self._conversation = ConversationFacilitator(tools=self._tools)
         if messages:
             self._conversation._messages = list(messages)
@@ -209,6 +238,8 @@ def _build_tools() -> list:
     from dialectical_framework.agents.advisor.tools.deepen import deepen
     from dialectical_framework.agents.advisor.tools.explore import explore
     from dialectical_framework.agents.advisor.tools.ingest import ingest
+    from dialectical_framework.agents.advisor.tools.record_decision import \
+        record_decision
     from dialectical_framework.agents.advisor.tools.sync import sync
     from dialectical_framework.agents.orchestrator.tools.inspect_node import \
         inspect_node
@@ -222,6 +253,7 @@ def _build_tools() -> list:
         anchor,
         explore,
         deepen,
+        record_decision,
         sync,
         inspect_node,
         read_digest,

{dialectical_framework-1.6.7 → dialectical_framework-1.7.0}/src/dialectical_framework/agents/advisor/system_prompts.py

@@ -125,7 +125,7 @@ understanding you've built.
 The narrow exceptions where no analysis is called for: greetings and small
 talk, logistics ("can you repeat that?"), pure information requests, and
 moments of grief or crisis where presence matters more than analysis.
-
+{decision_filter_note}
 Your response to the person never waits on the machinery — speak from what
 you have. Analysis deepens your next turn; it never delays or deforms this one."""
 
@@ -255,6 +255,101 @@ You now have the integration vision. Use it to:
 - Frame synthesis as something they GROW INTO, not something they implement
   in one move. It emerges from sustained Ac+ and Re+ working together."""
 
+_DECISION_READINESS = """## Decision Readiness (Convergence)
+
+Much of your counsel serves a decision the person must actually make. Mapping
+tensions opens the space; a decision needs the space to CLOSE. These rules
+govern the closing — they apply whenever the conversation is decision-shaped
+(the person is choosing, not just understanding):
+
+**The decision bounds the search.** In decision mode, run the search backward
+from the choice: "what would have to be true for this option to be wrong?" —
+not forward from the material. Options are finite; each has a finite set of
+load-bearing assumptions.
+
+**Named options (when the choice arrives as "X or Y").** Anchor the pair as
+it comes — the person's own framing is the map they'll recognize. But an
+option-pair is usually a bundle: the options differ along several tensions
+at once, and one tetrad captures one of them. So ask which pull matters most
+before mapping deeper — the person enumerates cheaply what the machinery
+maps expensively — and anchor the same pair again (identical wording) for an
+alternative tetrad only when their reactions show the mapped dimension isn't
+the one the choice turns on. Alternative tetrads are readings of the choice
+itself, not new candidate tensions — the discrimination test below governs
+those. Each perspective names its reading (the dimension its aspects oppose
+along); when a reading strongly resonates — the person keeps returning to
+that dimension — it is itself an anchor candidate: anchor it as its own
+tension (its two poles as thesis and antithesis) to give the root its full
+structure. When weaving, take the reading that resonates plus the tensions
+beyond the fork; sibling readings of one pair only shift the angle. And read
+the anchor result at call time: options that merely differ rather than
+oppose show up as weak opposition (low HS) or a low mode (drifting/absence
+rather than negation) — then the fork is not where the tension is. Keep the
+pair as the person's frame, but also anchor each option alone to discover
+what genuinely opposes it, instead of forcing the menu into a tension it
+doesn't contain.
+
+**Discrimination test (when NOT to map).** Before anchoring a new candidate
+tension, ask: if this tension resolved either way, would the person lean
+differently? If not, acknowledge it in conversation but do not map it —
+mapping that cannot change the choice is noise dressed as diligence. But if
+the person wants it mapped anyway, map it: their lived reality outranks the
+test, and what feels load-bearing to them often is.
+
+**Saturation.** Surface framings are endless; deep structure is not. When new
+tensions keep landing in already-mapped opposition families (when
+correspondence lines appear in your understanding they are this signal;
+otherwise judge whether the new framing's deep structure matches a mapped
+tension), say so plainly: new framings are collapsing into tensions already
+mapped. Never claim "we found all tensions"; completeness belongs only to
+causal arrangements, which are enumerated systematically for the tensions
+woven in. Tensions saturate; they are never exhausted.
+
+**Pre-commit ritual (earned confidence, soft).** Before proposing to record,
+have the choice face its strongest test: name what the unchosen side offers —
+its genuine contribution — and ask whether they can say what choosing costs
+them. Name the trap version of the choice (the resolution that is actually
+one side dominating). A decision that has faced both is earned; record that
+confrontation in the rationale. If the person says "just record it," record
+it — their wish outranks the ritual — and note in the rationale that the cost
+went unconfronted.
+
+**Readiness → propose-and-confirm ceremony.** Signals: a leaning is expressed
+and stable, options stopped shifting, recent candidate tensions failed the
+discrimination test. Then — after the ritual above, and only with the
+person's engagement — offer to record the decision. Read the record back in
+their own words: the question, the stance, the why, the accepted cost. Record
+ONLY on their explicit confirmation. A decision is a speech act — it exists
+because they declared it, never because you inferred it. Decisions are NEVER
+recorded silently — whatever else stays behind the scenes, the record is the
+person's artifact, and they must know it exists. Speak of it plainly, in
+their vocabulary — "want me to note this down as your decision, so we can
+hold to it later?" — the record is named in plain words, never as a tool; its
+reference (hash) follows the same disclosure rules as any other node
+reference.
+
+**The replacement rule.** Before proposing, check the distilled record
+against the Decisions section of your understanding (and any decisions
+recorded earlier in this conversation): a conflict with a standing decision
+is counsel material, not a silent recording detail — "this would sit against
+what you decided earlier — does it replace that?" If it does, record the new
+decision and, with their consent, retire the old with a reason naming its
+replacement.
+
+**After recording — the re-audit.** When a recorded decision exists and a new
+tension or a wobble appears, first ask: does this discriminate against what
+was decided? When it is the already-accepted cost resurfacing, or a framing
+that collapses into what was mapped, reassure FROM the record: they accepted
+this knowingly, here is the recipe they adopted for living with it. That
+reassurance is the record's whole value — but treat the wobble as data
+first, dismissal never: circumstances may genuinely have changed even when
+the wording resembles the accepted cost. If the new tension genuinely
+discriminates — it could change the choice — say so honestly: this reopens
+the decision. Counsel it through, and if a new stance emerges, record it and
+retire the old per the replacement rule above. If a ground of the decision
+has since been discarded, surface that: the record stands, but one of its
+supports moved."""
+
 _TOOLS_INTRO = """## Internal Tools
 
 Your internal tools — how you think structurally. Use them eagerly and
@@ -283,8 +378,9 @@ _TOOL_DOCS: dict[str, str] = {
     "anchor": """- `anchor` — Plants a specific tension from the conversation. More precise
   than ingest; use when you can see at least the person's position. Two modes:
   - Thesis + antithesis: you know both sides — creates one polarity and one
-    perspective (tetrad). Call again with the same T-A for an alternative
-    tetrad on the same opposition.
+    perspective (tetrad). Call again with the same T-A (identical wording —
+    a rephrase plants a new tension instead) for an alternative tetrad on
+    the same opposition.
   - Thesis only: anchors their position and discovers what opposes it — finds
     multiple possible antitheses (each a different polarity), each expanded
     into a perspective. Richer when you want the framework to reveal
@@ -293,8 +389,9 @@ _TOOL_DOCS: dict[str, str] = {
   until woven in with `explore`). Use when you can see at least the person's
   position. Two modes:
   - Thesis + antithesis: you know both sides — creates one polarity and one
-    perspective (tetrad). Call again with the same T-A for an alternative
-    tetrad on the same opposition.
+    perspective (tetrad). Call again with the same T-A (identical wording —
+    a rephrase plants a new tension instead) for an alternative tetrad on
+    the same opposition.
   - Thesis only: anchors their position and discovers what opposes it — finds
     multiple possible antitheses (each a different polarity), each expanded
     into a perspective. Richer when you want the framework to reveal
@@ -352,9 +449,22 @@ _TOOL_DOCS: dict[str, str] = {
   them. Deepening only adds analytical depth to existing structure — it
   never changes what the exploration contains, so no consent ceremony is
   needed. Harmless on already-developed wheels.""",
+    "record_decision": """- `record_decision` — Records a decision the person has EXPLICITLY
+  confirmed, after the propose-and-confirm ceremony (see Decision Readiness).
+  Pass the confirmed wording literally: `question` (what was being decided),
+  `stance` (the position taken), `rationale` (the distilled why, including
+  reasons outside the mapped structure). Pass `grounds` as {hash, role}
+  entries: role "accepted_cost" for the unchosen side's contribution they
+  confronted, "adopted_pathway" for the pathway adopted as their ongoing
+  recipe, no role for plain grounds (tensions weighed, arrangements counseled
+  from). The result may carry a coherence verdict — if it flags a
+  contradiction, raise it with the person immediately; the record stands
+  either way. To replace or retract a recorded decision, use `discard` on it
+  (reason naming the newer decision if one replaces it).""",
     "sync": """- `sync` — Re-reads the graph state. Without arguments: the full picture —
   e.g., after multiple ingest/anchor calls, to see all perspectives with
-  scores before deciding what to group for explore. With a `nexus_hash`:
+  scores (and any standing decisions) before deciding what to group for
+  explore. With a `nexus_hash`:
   zooms into that one exploration in full depth — the overview caps wheels
   per cycle for compactness, the zoom does not. Zoom when counsel settles on
   one exploration and you need arrangements the overview truncated. NOT
@@ -364,19 +474,24 @@ _TOOL_DOCS: dict[str, str] = {
     "sync_scoped": """- `sync` — Re-reads this exploration's state. Use when you need a fresh
   picture after changes. NOT needed at conversation start — the exploration
   is already in your context.""",
-    "discard": """- `discard` — Silently retracts something the user rejects. Works on either a
-  perspective (a whole framing — the tension and its aspects) or a statement
-  (a single claim). Pass the hash from the anchor/ingest result. Uncommitted
-  nodes are removed; committed ones are soft-discarded and filtered from future
-  reasoning. To drop a tension entirely, discard the perspective first, then
-  its underlying statement if it's no longer wanted (discarding a perspective
-  leaves its shared statements intact, and a statement still used by a live
-  perspective won't discard). A perspective already woven into pathways
-  (cycles/wheels) won't discard — re-anchor the corrected framing instead.""",
+    "discard": """- `discard` — Silently retracts something the user rejects. Works on a
+  perspective (a whole framing — the tension and its aspects), a statement
+  (a single claim), or a recorded decision. Pass the hash from the
+  anchor/ingest result. Uncommitted nodes are removed; committed ones are
+  soft-discarded and filtered from future reasoning. To drop a tension
+  entirely, discard the perspective first, then its underlying statement if
+  it's no longer wanted (discarding a perspective leaves its shared
+  statements intact, and a statement still used by a live perspective won't
+  discard). A perspective already woven into pathways (cycles/wheels) won't
+  discard — re-anchor the corrected framing instead. Recorded decisions are
+  the exception to silence: retire one only after the person explicitly
+  confirms, with a reason naming the replacement if one exists.""",
     "discard_scoped": """- `discard` — Retracts something the person no longer stands behind, per the
   consent rules above (confirm for exploration members; a framing you just
-  anchored needs no ceremony). Works on either a perspective (a whole framing)
-  or a statement (a single claim). Pass the hash from the anchor result.
+  anchored needs no ceremony). Works on a perspective (a whole framing), a
+  statement (a single claim), or a recorded decision (always confirmed with
+  the person first, with a reason naming the replacement if one exists).
+  Pass the hash from the anchor result.
   Uncommitted nodes are removed; committed ones are soft-discarded and
   filtered from future reasoning. Members of OTHER explorations refuse.
   A perspective already woven into pathways (cycles/wheels) won't discard —
@@ -428,7 +543,7 @@ calls for it. It is a compass, not a script:
 3. Continue conversation, possibly `anchor` again for new tensions
 4. `explore` → respond with specific paired pathways
 5. Continue with full depth, offer integration vision when they're ready
-
+{decision_arc_step}
 Counsel grounded in pathways is stronger than counsel from a single tension;
 counsel from a tension is stronger than counsel from nothing — keep moving the
 understanding deeper as the conversation allows.
@@ -449,7 +564,7 @@ present findings as structural tables or labeled positions. Do not use
 framework terminology (thesis, antithesis, polarity, perspective, nexus,
 wheel, transformation, T+, T-, A+, A-, S+, S-, Ac+, Re+) — unless the app
 preamble above explicitly grants terminology disclosure, in which case the
-preamble's vocabulary rules override this one.
+preamble's vocabulary rules override this one.{decision_speech_note}
 
 Speak in the person's own vocabulary about their situation. Statement text
 from the graph is raw material — rephrase it freely into their language;
@@ -527,6 +642,20 @@ Use `inspect_node` when you want to understand the reasoning behind a score,
 explain WHY a specific blindspot exists, or ground a pathway recommendation
 in the actual analytical logic rather than restating the dump.
 
+**Decisions:** The dump may contain a Decisions section — the person's
+standing decisions, each recorded with their explicit confirmation: the
+question, the stance in their confirmed words, the why, and grounds (the
+tensions, statements, arrangements, and pathways it rests on; "accepted cost" marks the
+unchosen side's contribution they confronted, "adopted pathway" the recipe
+they committed to). Treat these as the person's own declared positions —
+counsel that contradicts a standing decision must name that openly. A
+ground flagged "since discarded" means a support
+moved after the decision — worth surfacing, not silently ignoring. A
+`Validation` line carries the machine coherence verdict: "failed" means a
+flagged contradiction — do not build reassurance on that record; revisit it
+with the person. Absence of an accepted-cost ground means the choice never
+confronted what it gave up — relevant when a wobble arrives.
+
 **Cross-exploration correspondences.** When several explorations coexist,
 some perspectives carry correspondence lines — machine-stated facts, not
 suggestions: "Also woven into Nexus [[x]]" (literally the same tension in
@@ -675,6 +804,7 @@ DEFAULT_TOOL_NAMES = [
     "anchor",
     "explore",
     "deepen",
+    "record_decision",
     "sync",
     "inspect_node",
     "read_digest",
@@ -709,6 +839,44 @@ def system_prompt(
                 )
             tool_docs.append(doc)
 
+    decisions_wired = "record_decision" in names
+
+    def _decision_note(template: str, placeholder: str, note: str) -> str:
+        """Render a Decision Readiness cross-reference only when the section
+        itself renders (tool wired) — a reference to an absent section would
+        dangle. The placeholder sits on its own line: wired → the note set
+        off by blank lines, unwired → the line collapses to a paragraph
+        break."""
+        if placeholder not in template:
+            return template
+        return template.replace(
+            placeholder, f"\n{note}\n" if decisions_wired else ""
+        )
+
+    eager = _decision_note(
+        _EAGER_SCOPED if scoped else _EAGER,
+        "{decision_filter_note}",
+        "In decision-shaped conversations, the Decision Readiness section "
+        "below adds one more filter: a candidate tension that could not "
+        "change the choice is acknowledged, not mapped.",
+    )
+    default_arc = _decision_note(
+        _DEFAULT_ARC,
+        "{decision_arc_step}",
+        "6. When the conversation is decision-shaped and readiness signals "
+        "appear, close it: the propose-and-confirm ceremony (see Decision "
+        "Readiness above), then counsel FROM the record.",
+    )
+    how_you_speak = _HOW_YOU_SPEAK_SCOPED if scoped else _HOW_YOU_SPEAK
+    if "{decision_speech_note}" in how_you_speak:
+        speech_note = (
+            "\n\nOne exception: the decision record (see Decision Readiness) "
+            "is named openly, in plain words — never as a tool or node."
+            if decisions_wired
+            else ""
+        )
+        how_you_speak = how_you_speak.replace("{decision_speech_note}", speech_note)
+
     conversation_use = _CONVERSATION_USE
     if scoped and "ingest" not in names:
         # Don't reference a tool that isn't wired in this mode.
@@ -720,19 +888,20 @@ def system_prompt(
     sections = [
         _ROLE_SCOPED if scoped else _ROLE,
         _scope_section(scoped_nexus_hash) if scoped else None,
-        _EAGER_SCOPED if scoped else _EAGER,
+        eager,
         _INTERNAL_MODEL,
         conversation_use,
+        _DECISION_READINESS if decisions_wired else None,
         _TOOLS_INTRO_SCOPED if scoped else _TOOLS_INTRO,
         "\n\n".join(tool_docs),
         _REJECTION_HANDLING_SCOPED if scoped else _REJECTION_HANDLING,
-        None if scoped else _DEFAULT_ARC,
-        _HOW_YOU_SPEAK_SCOPED if scoped else _HOW_YOU_SPEAK,
+        None if scoped else default_arc,
+        how_you_speak,
         _SCORE_READING,
         _CONTEXT_SLOT,
     ]
     return "\n\n".join(s for s in sections if s)
 
 
-# Backward-compatible default render (unscoped, all seven tools).
+# Backward-compatible default render (unscoped, all default tools).
 SYSTEM_PROMPT = system_prompt()

dialectical_framework-1.7.0/src/dialectical_framework/agents/advisor/tools/record_decision.py

@@ -0,0 +1,62 @@
+"""
+record_decision tool: persist a decision the person explicitly confirmed.
+
+The ceremony lives in conversation (propose → read back → confirm) — this
+tool is called only AFTER the person's explicit yes, with the confirmed
+wording passed literally. Retracting or replacing a recorded decision goes
+through the standard `discard` tool (reason referencing the new decision).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from mirascope import llm
+from pydantic import Field
+
+from dialectical_framework.concerns.record_decision import GroundLink
+
+
+@llm.tool
+async def record_decision(
+    question: Annotated[
+        str,
+        Field(description="The question that was being decided, in the person's confirmed words"),
+    ],
+    stance: Annotated[
+        str,
+        Field(description="The stance the person committed to, in their confirmed words"),
+    ],
+    rationale: Annotated[
+        str,
+        Field(
+            description="The distilled why behind the decision as the person confirmed it, "
+            "including reasons that live outside the mapped structure (deadlines, "
+            "people, external facts)"
+        ),
+    ],
+    grounds: Annotated[
+        list[GroundLink] | None,
+        Field(
+            description="Nodes this decision rests on: {hash, role?} each. "
+            "role='accepted_cost' for the unchosen side's contribution the person "
+            "confronted and accepted; role='adopted_pathway' for the pathway adopted "
+            "as the ongoing recipe; omit role for a plain ground (tensions weighed, "
+            "arrangements counseled from)."
+        ),
+    ] = None,
+) -> str:
+    """Record a decision the person has EXPLICITLY confirmed in conversation. Never call this silently or speculatively — propose the distilled record first, read it back, and record only on their clear yes. Links the decision to the graph nodes that grounded it and attaches the confirmed rationale. To replace or retract a recorded decision, use `discard` on it (with a reason naming the newer decision if one replaces it)."""
+    from dialectical_framework.concerns.record_decision import RecordDecision
+
+    # Mirascope passes json.loads'd kwargs without coercing nested models, so
+    # `grounds` arrives as raw dicts — RecordDecision.resolve normalizes them
+    # (single owner of that normalization) and refuses in-band on bad input.
+    concern = RecordDecision()
+    await concern.resolve(
+        question=question,
+        stance=stance,
+        rationale=rationale,
+        grounds=grounds,
+    )
+    return str(concern.report)

{dialectical_framework-1.6.7 → dialectical_framework-1.7.0}/src/dialectical_framework/agents/advisor/tools/scoped.py

@@ -18,8 +18,10 @@ the pinned explore weaves them into the exploration, deepen develops an
 alternative arrangement of the pinned exploration on demand (guarded by
 wheel-membership), sync/inspect_node/read_digest read, discard retracts
 (members of the pinned nexus and standalone perspectives — e.g. its own
-rejected anchors — but never members of OTHER explorations). Only `ingest`
-is excluded — bulk extraction belongs to the unscoped flow.
+rejected anchors — but never members of OTHER explorations), and
+record_decision persists confirmed decisions (Case-level, unguarded by the
+pin). Only `ingest` is excluded — bulk extraction belongs to the unscoped
+flow.
 """
 
 from __future__ import annotations
@@ -40,6 +42,8 @@ def build_scoped_tools(nexus_hash: str) -> list:
     DB-free for signature tests).
     """
     from dialectical_framework.agents.advisor.tools.anchor import anchor
+    from dialectical_framework.agents.advisor.tools.record_decision import \
+        record_decision
     from dialectical_framework.agents.orchestrator.tools.inspect_node import \
         inspect_node
     from dialectical_framework.agents.orchestrator.tools.read_digest import \
@@ -58,10 +62,10 @@ def build_scoped_tools(nexus_hash: str) -> list:
 
     @llm.tool
     async def discard(
-        hash: Annotated[str, Field(description="Hash (or prefix) of the Statement or Perspective to discard")],
+        hash: Annotated[str, Field(description="Hash (or prefix) of the Statement, Perspective, or Decision to discard")],
         reason: Annotated[str, Field(description="Why it's being discarded")] = "discarded",
     ) -> str:
-        """Mark a Statement or Perspective as discarded when the user disagrees with it or finds it irrelevant. Works on members of this exploration and on standalone perspectives (e.g. a freshly anchored framing the user rejected); refuses members of other explorations. Will refuse if the target participates in existing Cycles/Wheels."""
+        """Mark a Statement, Perspective, or Decision as discarded when the user disagrees with it or finds it irrelevant. Works on members of this exploration, on standalone perspectives (e.g. a freshly anchored framing the user rejected), and on recorded decisions the person retracts or replaces; refuses members of other explorations. Will refuse if the target participates in existing Cycles/Wheels."""
         from dialectical_framework.concerns.discard import Discard
 
         refusal = _outside_scope_refusal(pinned_hash, hash)
@@ -107,7 +111,10 @@ def build_scoped_tools(nexus_hash: str) -> list:
 
         return await run_deepen(wheel_hash)
 
-    return [anchor, sync, inspect_node, read_digest, discard, explore, deepen]
+    # record_decision is appended as-is: decisions are Case-level facts, not
+    # exploration members — no nexus-scope guard applies (grounds may be
+    # exploration members; grounding is read-only w.r.t. the exploration).
+    return [anchor, sync, inspect_node, read_digest, discard, explore, deepen, record_decision]
 
 
 def _outside_scope_refusal(nexus_hash: str, target_hash: str) -> str | None:
@@ -132,8 +139,8 @@ def _outside_scope_refusal(nexus_hash: str, target_hash: str) -> str | None:
 
     node = NodeRepository().find_by_hash(target_hash)
     if not isinstance(node, Perspective):
-        # Not a perspective (likely a statement) — let Discard's own
-        # guards handle it.
+        # Not a perspective (a statement or a decision) — let Discard's own
+        # guards handle it; decisions are Case-level, so no nexus pin applies.
         return None
     pp = node
 

{dialectical_framework-1.6.7 → dialectical_framework-1.7.0}/src/dialectical_framework/agents/analyst/analyst.py

@@ -20,7 +20,9 @@ from dialectical_framework.agents.analyst.system_prompts import SYSTEM_PROMPT
 from dialectical_framework.agents.conversation_facilitator import \
     ConversationFacilitator
 from dialectical_framework.agents.reasonable_concern import ReasonableConcern
+from dialectical_framework.agents.app_spec import AppSpec, resolve_app_layer
 from dialectical_framework.agents.stream_events import StreamEvent
+from dialectical_framework.agents.toolsets import merge_app_tools
 
 if TYPE_CHECKING:
     pass
@@ -48,13 +50,17 @@ class Analyst:
 
     Usage:
         with scope(case.sid):
-            analyst = Analyst(app_preamble="You are a counselor...")
+            analyst = Analyst(app=MY_APP_SPEC)  # declarative (see AppSpec)
             response = await analyst.chat("I'm struggling with work-life balance")
 
         # Resuming with history:
         with scope(case.sid):
             analyst = Analyst(messages=loaded_messages)
             response = await analyst.chat("What about the second tension?")
+
+        # Manual preamble control (app_preamble replaces AppSpec composition):
+        with scope(case.sid):
+            analyst = Analyst(app_preamble="You are a counselor...")
     """
 
     AGENT_NAME = "analyst"
@@ -63,8 +69,17 @@ class Analyst:
         self,
         app_preamble: Optional[str] = None,
         messages: Optional[list] = None,
+        app_tools: Optional[list] = None,
+        app: Optional[AppSpec] = None,
     ) -> None:
-        self._tools = _build_tools()
+        # app: declarative app definition — the framework composes the
+        # Navigator preamble (NAVIGATOR_APP + voicing + tool_guide) and tool
+        # set from it. app_preamble/app_tools remain for manual control;
+        # mixing them with app= raises (see app_spec.resolve_app_layer).
+        app_preamble, app_tools = resolve_app_layer(
+            app, app_preamble, app_tools, preamble_for="navigator"
+        )
+        self._tools = merge_app_tools(_build_tools(), app_tools)
         self._conversation = ConversationFacilitator(tools=self._tools)
         if messages:
             self._conversation._messages = list(messages)

{dialectical_framework-1.6.7 → dialectical_framework-1.7.0}/src/dialectical_framework/agents/analyst/skills/edit_perspective.py

@@ -128,6 +128,10 @@ class EditPerspective(ReasonableConcern[EditPerspectiveResult]):
         # Prepare working PP (clone if committed)
         if self._was_committed:
             working_pp = pp.clone()
+            # Drop the inherited reading (intent): the axis was named for the
+            # ORIGINAL aspects — after a user edit it may no longer describe
+            # this tetrad, and a stale reading is worse than none.
+            working_pp.intent = None
             working_pp.save()
             self._report.node_created(working_pp)
         else:

{dialectical_framework-1.6.7 → dialectical_framework-1.7.0}/src/dialectical_framework/agents/analyst/skills/expand_polarities.py

@@ -143,6 +143,17 @@ class ExpandPolarity(ReasonableConcern[list[Perspective]]):
                 )
                 continue
 
+            # Name this reading of the tension: the generation already made
+            # the LLM name the axis of each diagonal pair (TetradDto) —
+            # persist it as the perspective's intent (the guiding question
+            # of THIS tetrad). Sibling tetrads on one polarity differ by
+            # exactly this. Set BEFORE commit: intent participates in the
+            # hash, so distinct readings are structurally distinct nodes.
+            if pp.intent is None:
+                reading = self._compose_reading(generator.axes)
+                if reading:
+                    pp.intent = reading
+
             pp.commit()
             self._report.node_committed(pp)
             completed_pps.append(pp)
@@ -284,6 +295,8 @@ class ExpandPolarity(ReasonableConcern[list[Perspective]]):
             POSITION_A_MINUS,
         ]
         state: dict[str, str | None] = {"hash": pp.short_hash}
+        if pp.intent:
+            state["reading"] = pp.intent
         for pos in positions:
             manager = pp.get_relationship_manager_by_position(pos)
             pairs = manager.all()
@@ -356,6 +369,20 @@ class ExpandPolarity(ReasonableConcern[list[Perspective]]):
                 return existing
         return None
 
+    @staticmethod
+    def _compose_reading(axes: dict[str, str]) -> Optional[str]:
+        """Compose AspectGeneration's captured axes into the perspective's
+        reading (intent). Both axes when they name different dimensions,
+        one when they agree or only one survived the disclaimer filter."""
+        constructive = axes.get("t_plus_vs_a_minus")
+        reflective = axes.get("a_plus_vs_t_minus")
+        named = [a for a in (constructive, reflective) if a]
+        if not named:
+            return None
+        if len(named) == 2 and named[0].lower() != named[1].lower():
+            return f"Reading along: {named[0]} / {named[1]}"
+        return f"Reading along: {named[0]}"
+
     @inject
     async def _get_input_text(
         self,