dialectical-framework 1.6.8__tar.gz → 1.7.1__tar.gz

{dialectical_framework-1.6.8 → dialectical_framework-1.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dialectical-framework
-Version: 1.6.8
+Version: 1.7.1
 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.8 → dialectical_framework-1.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dialectical-framework"
-version = "1.6.8"
+version = "1.7.1"
 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.8 → dialectical_framework-1.7.1}/src/dialectical_framework/agents/advisor/advisor.py

@@ -20,6 +20,7 @@ from pydantic import BaseModel, Field
 from dialectical_framework.agents.advisor.system_prompts import \
     system_prompt
 from dialectical_framework.agents.agent_context import agent_scope
+from dialectical_framework.graph.scope_context import require_current_sid
 from dialectical_framework.agents.conversation_facilitator import \
     ConversationFacilitator
 from dialectical_framework.agents.app_spec import AppSpec, resolve_app_layer
@@ -57,18 +58,18 @@ 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):
@@ -79,7 +80,7 @@ class Advisor:
         # rules in the app preamble, where domain vocabulary lives.
         with scope(case.sid):
             advisor = Advisor(
-                app_preamble=ASTRO_COUNSELOR_APP,  # explains when to consult the chart
+                app_preamble=ASTRO_COUNSELOR_PERSONA,  # explains when to consult the chart
                 app_tools=[lookup_natal_chart],   # @llm.tool from the app
             )
 
@@ -90,7 +91,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,
             )
@@ -120,11 +121,19 @@ class Advisor:
         nexus_hash: Optional[str] = None,
         app_tools: Optional[list] = None,
         app: Optional[AppSpec] = None,
+        principal: str = "human",
     ) -> None:
+        # principal: WHO confirms decisions in this conversation — a host
+        # attestation, fixed for the session (the counterpart doesn't change
+        # mid-conversation). "human" = an actual person; a delegated driver
+        # (agent-to-agent runs) must pass its own identity ("agent:<name>"
+        # or <provider>/<model>) so recorded decisions never claim human
+        # confirmation they didn't get. Closed over by record_decision —
+        # never an LLM-visible parameter.
         self._nexus_hash = nexus_hash
         # app: declarative app definition — composition depends on the mode:
         # counsel toggle (nexus_hash set) keeps the Navigator contract
-        # (EXPLORATION_ADVISOR_APP + voicing + tool_guide); standalone uses
+        # (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,
@@ -134,9 +143,9 @@ class Advisor:
         )
         if nexus_hash:
             self._validate_nexus(nexus_hash)
-            self._tools = _build_scoped_tools(nexus_hash)
+            self._tools = _build_scoped_tools(nexus_hash, principal)
         else:
-            self._tools = _build_tools()
+            self._tools = _build_tools(principal)
         # 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)
@@ -185,12 +194,14 @@ class Advisor:
         return "\n\n".join(parts)
 
     async def chat(self, user_message: str) -> str:
+        require_current_sid()  # unscoped turns silently drop all work
         with agent_scope(self.AGENT_NAME):
             await self._render_pending_context()
             result = await self._conversation.submit(ChatResponse, user_message)
             return result.message
 
     async def chat_stream(self, user_message: str) -> AsyncGenerator[StreamEvent, None]:
+        require_current_sid()  # unscoped turns silently drop all work
         with agent_scope(self.AGENT_NAME):
             await self._render_pending_context()
             async for event in self._conversation.submit_stream(
@@ -233,11 +244,13 @@ class Advisor:
         return self._conversation._messages
 
 
-def _build_tools() -> list:
+def _build_tools(principal: str = "human") -> list:
     from dialectical_framework.agents.advisor.tools.anchor import anchor
     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 \
+        build_record_decision
     from dialectical_framework.agents.advisor.tools.sync import sync
     from dialectical_framework.agents.orchestrator.tools.inspect_node import \
         inspect_node
@@ -251,6 +264,7 @@ def _build_tools() -> list:
         anchor,
         explore,
         deepen,
+        build_record_decision(principal),
         sync,
         inspect_node,
         read_digest,
@@ -258,8 +272,8 @@ def _build_tools() -> list:
     ]
 
 
-def _build_scoped_tools(nexus_hash: str) -> list:
+def _build_scoped_tools(nexus_hash: str, principal: str = "human") -> list:
     from dialectical_framework.agents.advisor.tools.scoped import \
         build_scoped_tools
 
-    return build_scoped_tools(nexus_hash)
+    return build_scoped_tools(nexus_hash, principal)

{dialectical_framework-1.6.8 → dialectical_framework-1.7.1}/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.1/src/dialectical_framework/agents/advisor/tools/record_decision.py

@@ -0,0 +1,85 @@
+"""
+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).
+
+Provenance: WHO confirmed is a host-attested fact, closed over at tool
+construction (Advisor(principal=...)) — never an LLM-supplied parameter.
+"human" (the default) means an actual person confirmed the wording; a
+delegated driver (agent-to-agent runs) must be constructed with its own
+identity, else the ledger and inspect_node would present machine-authored
+rationales as the person's own confirmed "why".
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from mirascope import llm
+from pydantic import Field
+
+from dialectical_framework.concerns.record_decision import GroundLink
+
+
+def build_record_decision(principal: str = "human"):
+    """Build the record_decision tool with the confirming principal
+    closed over (same code-not-prompt enforcement as the nexus pin in
+    scoped.py)."""
+
+    attested_principal = principal
+
+    @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,
+            principal=attested_principal,
+        )
+        return str(concern.report)
+
+    return record_decision
+
+
+# Default build: a human principal. Kept module-level so existing imports
+# (toolset builders, tests) stay valid; hosts with a non-human driver pass
+# principal= at Advisor construction instead of importing this.
+record_decision = build_record_decision()

{dialectical_framework-1.6.8 → dialectical_framework-1.7.1}/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
@@ -30,21 +32,26 @@ from mirascope import llm
 from pydantic import Field
 
 
-def build_scoped_tools(nexus_hash: str) -> list:
+def build_scoped_tools(nexus_hash: str, principal: str = "human") -> list:
     """
     Build the tool set for an exploration-pinned Advisor (counsel mode).
 
     The nexus_hash is captured by closure — the LLM cannot redirect any of
     these tools to another nexus or create a new one. Validation that the
     nexus exists happens in Advisor.__init__, not here (keeps the factory
-    DB-free for signature tests).
+    DB-free for signature tests). `principal` (host-attested confirmer
+    identity, closed over the same way) reaches record_decision — see
+    tools/record_decision.py.
     """
     from dialectical_framework.agents.advisor.tools.anchor import anchor
+    from dialectical_framework.agents.advisor.tools.record_decision import \
+        build_record_decision
     from dialectical_framework.agents.orchestrator.tools.inspect_node import \
         inspect_node
     from dialectical_framework.agents.orchestrator.tools.read_digest import \
         read_digest
 
+    record_decision = build_record_decision(principal)
     pinned_hash = nexus_hash
 
     @llm.tool
@@ -58,10 +65,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 +114,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 +142,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.8 → dialectical_framework-1.7.1}/src/dialectical_framework/agents/analyst/analyst.py

@@ -16,6 +16,7 @@ from mirascope import llm
 from pydantic import BaseModel, Field
 
 from dialectical_framework.agents.agent_context import agent_scope
+from dialectical_framework.graph.scope_context import require_current_sid
 from dialectical_framework.agents.analyst.system_prompts import SYSTEM_PROMPT
 from dialectical_framework.agents.conversation_facilitator import \
     ConversationFacilitator
@@ -93,11 +94,13 @@ class Analyst:
         return "\n\n".join(parts)
 
     async def chat(self, user_message: str) -> str:
+        require_current_sid()  # unscoped turns silently drop all work
         with agent_scope(self.AGENT_NAME):
             result = await self._conversation.submit(ChatResponse, user_message)
             return result.message
 
     async def chat_stream(self, user_message: str) -> AsyncGenerator[StreamEvent, None]:
+        require_current_sid()  # unscoped turns silently drop all work
         with agent_scope(self.AGENT_NAME):
             async for event in self._conversation.submit_stream(
                 ChatResponse, user_message

{dialectical_framework-1.6.8 → dialectical_framework-1.7.1}/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: