architecture: define investigation turn cycle

docs/architectural-principles.md

@@ -0,0 +1,306 @@
+# Architectural Principles — Architecture Experiment 17
+
+> These principles have emerged from Experiments 1–17. They are not derived from external design frameworks. They are distilled from observed patterns across the investigation's own evolution.
+>
+> A principle is only valid until an experiment disproves it. Record contradictions, not comfort.
+
+---
+
+## Principle 1 — Every Layer Has One Responsibility
+
+### Source
+
+Emerges from Experiments 10, 12, 14, 15, 16.
+
+### Statement
+
+Each architectural layer performs exactly one type of work. It does not perform the work of adjacent layers, even when that would be convenient or efficient.
+
+### Derived From
+
+- Graph captures knowledge; narrative translates it; assessment evaluates it; behaviour decides about it; conversation executes it; workspace projects it.
+- When a layer performed two types of work (e.g., graph and narrative mixed), the architecture became fragile. Separating them made each layer independently testable and replaceable.
+
+### Implication
+
+If you can describe a layer's work with "and" in addition to "to", it is doing too much. Split it.
+
+---
+
+## Principle 2 — Information Flows Downward
+
+### Source
+
+Emerges from Experiments 12, 14, 16.
+
+### Statement
+
+Data flows unidirectionally down the architecture during a turn: graph → narrative → assessment → behaviour → conversation → workspace. Each layer transforms data for its audience but never pushes transformed data back to a previous layer during the same turn.
+
+### Derived From
+
+- The graph is the source of truth. Narrative translates it for humans. Assessment evaluates the translation. Behaviour acts on the evaluation. Conversation executes the action. Workspace displays the result.
+- Attempting to push state backward within a turn creates circular dependencies that break deterministic ordering.
+
+### Implication
+
+A layer may read its own output and lower layers' inputs, but it never writes to a lower layer during the same turn. Cross-turn feedback (user responses) enters at the top through user input, not through architectural shortcuts.
+
+---
+
+## Principle 3 — Feedback Flows Upward Through the User
+
+### Source
+
+Emerges from Experiments 9, 10, 14, 15.
+
+### Statement
+
+Information returns to lower layers only through the user. The user's next observation is the mechanism by which new information re-enters the system. No layer injects feedback directly into another layer during a turn.
+
+### Derived From
+
+- The investigation is a conversation between human and machine. The conversation loop is the only legitimate feedback mechanism.
+- Direct layer-to-layer feedback bypasses user awareness and creates hidden state mutations that are impossible to trace or audit.
+
+### Implication
+
+If you need information from layer N+1 to affect layer N-1, go through the user: present it in the workspace, have the user process it, and let their next observation carry the updated understanding back down.
+
+---
+
+## Principle 4 — Reasoning Never Communicates Directly With the UI
+
+### Source
+
+Emerges from Experiments 08, 12, 13, 14.
+
+### Statement
+
+The reasoning graph (the machine's internal representation) never directly drives UI components. All UI content passes through the investigation narrative, which provides human-appropriate translation regardless of graph schema changes.
+
+### Derived From
+
+- Graph nodes use domain-specific categories (observations, unknowns, assumptions, metrics) that are useful for reasoning but not for presentation.
+- The narrative layer proved essential: it is the only layer that understands both the graph's meaning and the user's need.
+- When UI consumed the graph directly (Experiment 10), developer statistics leaked into user-facing panels.
+
+### Implication
+
+The narrative is the contract between reasoning and presentation. Change the graph schema freely — as long as the narrative preserves its fields, the UI never breaks.
+
+---
+
+## Principle 5 — Behaviour Never Reasons
+
+### Source
+
+Emerges from Experiments 15, 16.
+
+### Statement
+
+Behaviour selection operates exclusively on investigation state (assessment), never on graph content or reasoning results. A behaviour's decision about what to do is based on *where the investigation is*, not on *what the graph says*.
+
+### Derived From
+
+- Experiment 16 proved that behaviour selection inspecting graph nodes directly couples behaviour to reasoning implementation. Graph schema changes break behaviour decisions.
+- When behaviour reads assessment instead of graph, it remains correct regardless of how the graph represents knowledge internally.
+
+### Implication
+
+If you can describe a behaviour's logic using "because the graph has node X with status Y," it is reasoning disguised as behaviour. It should read: "because the assessment shows phase F and progress P."
+
+---
+
+## Principle 6 — Presentation Never Interprets
+
+### Source
+
+Emerges from Experiments 12, 13, 14.
+
+### Statement
+
+Workspace panels render what the narrative provides. They do not re-filter, re-rank, or re-classify content. Panels control *how* things are shown (layout, emphasis, visibility), not *what* is shown.
+
+### Derived From
+
+- When each panel reimplemented its own filtering logic (Experiment 13), different panels showed contradictory information about the same investigation state.
+- A single narrative object consumed by all panels eliminates this class of inconsistency.
+
+### Implication
+
+If two panels show different facts about the same investigation, the problem is not the panels — it is that they are consuming different narratives. They must consume the same narrative and differ only in presentation choices (order, emphasis, visibility).
+
+---
+
+## Principle 7 — Assessment Never Generates Evidence
+
+### Source
+
+Emerges from Experiment 16.
+
+### Statement
+
+The assessment layer describes what the investigation has already established. It never creates new evidence, makes new inferences, or proposes new hypotheses. It only evaluates existing state.
+
+### Derived From
+
+- The assessment's role is to provide an accurate mirror of investigation state so that behaviour selection can operate on reality, not on the assessment's own judgments about what might be true.
+- When the assessment generates evidence (even implicitly by treating "unknown" as "probably false"), behaviour selection acts on invented information.
+
+### Implication
+
+Assessment signals are descriptive only: "this is unknown" not "this is probably X." The distinction between "we don't know" and "we know it's not true" must be preserved at every level.
+
+---
+
+## Principle 8 — Narrative Never Invents Facts
+
+### Source
+
+Emerges from Experiments 13, 14.
+
+### Statement
+
+Every element in the narrative must be traceable to one or more graph nodes. The narrative may reorganise, prioritise, deduplicate, and translate — but it may never include content that does not exist somewhere in the reasoning graph.
+
+### Derived From
+
+- Experiment 13 proved that semantic filtering and deduplication improve presentation without inventing content.
+- When narrative synthesis exceeded graph support (e.g., connecting two observations that were never linked by an edge), the facilitator appeared to be hallucinating connections.
+
+### Implication
+
+If you can trace a narrative statement back through the narrative structure to specific graph nodes and edges, it is valid. If not, it must be removed regardless of how useful or coherent it seems.
+
+---
+
+## Principle 9 — Assessment Describes, Never Prescribes
+
+### Source
+
+Emerges from Experiment 16, Principle: "Signals Are Descriptive, Not Prescriptive."
+
+### Statement
+
+The assessment layer reports state using neutral, descriptive language. It never says "therefore the next step should be X." It says "the investigation is in state S along dimension D." The interpretation belongs to behaviour selection.
+
+### Derived From
+
+- A prescriptive assessment becomes a decision tree in disguise, locking the architecture into one strategy for interpreting state.
+- Descriptive assessment supports multiple strategies: deterministic rules, weighted scoring, LLM-assisted reasoning — all reading the same output.
+
+### Implication
+
+Assessment language must survive replacement of the behaviour selection strategy. If the assessment says "Stalled" instead of "You should pause," it passes this test. If it says "Use Pause because progress has stopped," it fails.
+
+---
+
+## Principle 10 — Convergence Over Single Signals
+
+### Source
+
+Emerges from Experiment 16, Principle: "Convergence Matters More Than Any Single Signal."
+
+### Statement
+
+Behaviour selection should prefer actions supported by multiple independent assessment dimensions over actions supported by a single strong signal. Convergent signals are more reliable than any individual dimension's threshold.
+
+### Derived From
+
+- A single dimension reaching a threshold (e.g., Evidence Quality: Contradictory) can produce false positives in edge cases.
+- Multiple dimensions agreeing on a pattern (e.g., Stalled progress + Repetitive conversation + Confused understanding) indicates a robust state that warrants intervention regardless of any one dimension's reliability.
+
+### Implication
+
+Behaviour confidence should be proportional to the number of converging signals, not the strength of the strongest signal. High-confidence actions require multiple supporting dimensions; low-confidence actions are appropriate for single-signal triggers.
+
+---
+
+## Principle 11 — Assessment Is Stateful Across Turns
+
+### Source
+
+Emerges from Experiment 16, Principle: "Assessment Is Stateful Across Turns."
+
+### Statement
+
+The assessment accumulates state across turns. It tracks change (deltas), sequence patterns (repetition), trend direction (acceleration), and phase transitions. A turn-by-turn stateless assessment cannot detect looping, spiralling, or convergence.
+
+### Derived From
+
+- Investigation state is inherently temporal. "Stalled" means nothing without knowing what came before it.
+- The assessment must carry forward state between turns to enable pattern detection across the investigation's history.
+
+### Implication
+
+The assessment's data structure must include turn-level history (not just the current snapshot). The minimum viable history is: phase per turn, resolution count per turn, and response length per turn. Trends emerge from sequences, not snapshots.
+
+---
+
+## Principle 12 — Uncertainty About Assessment Is Itself Assessable
+
+### Source
+
+Emerges from Experiment 16, Principle: "Uncertainty About Assessment Is Itself Assessable."
+
+### Statement
+
+When the assessment cannot reliably evaluate a dimension (insufficient data, conflicting signals, rapid state changes), it should express uncertainty explicitly rather than guessing. The behaviour layer receives "Cannot determine" as a valid signal.
+
+### Derived From
+
+- False precision in assessment produces false confidence in behaviour. An overconfident but wrong assessment is worse than a transparently uncertain one.
+- User-facing confidence must match the system's actual certainty, including its uncertainty about its own certainty.
+
+### Implication
+
+Assessment outputs must include a confidence field per dimension. "Phase: Exploring (confidence: low)" is more useful than "Phase: Exploring (confidence: high)" when the data supports only weak classification. The behaviour layer should treat low-confidence assessments as invitations for conservative action.
+
+---
+
+## Principle 13 — Investigation Progress Is Qualitative Not Quantitative
+
+### Source
+
+Emerges from Experiments 10, 15, 16.
+
+### Statement
+
+Investigation progress is measured by the *quality* of understanding, not the *quantity* of resolved nodes. A single resolved critical unknown provides more investigative value than ten peripheral ones. Progress is trajectory and depth, not count.
+
+### Derived From
+
+- Early experiments focused on node counts (Experiment 10). This proved misleading: a graph can grow large while understanding remains shallow.
+- Expert investigators measure progress by "do we understand the situation better?" not "how many items do we have left?"
+
+### Implication
+
+The assessment should evaluate whether new information clarifies existing understanding or merely adds data points. Understanding compounding (new insights that reframe previous ones) is a stronger progress signal than evidence accumulation.
+
+---
+
+## Principle 14 — The User Is Part of the Architecture
+
+### Source
+
+Emerges from Experiments 9, 10, 15.
+
+### Statement
+
+The user is not an external actor who feeds data into the system. The user's cognitive state (confidence, confusion, engagement, insight) is a first-class architectural input that affects every subsequent turn. The architecture must model and respond to the user as an active investigation participant.
+
+### Derived From
+
+- Experiments consistently showed that user psychology drives investigation outcomes more than graph mechanics do.
+- A technically perfect graph on confused or disengaged data produces worthless results.
+
+### Implication
+
+Every layer should ask: "How does this affect the user's ability and willingness to continue investigating?" If a layer improves graph accuracy but degrades user engagement, it has traded investigation quality for internal elegance — and lost.
+
+---
+
+## Recording Note
+
+These principles emerged from the investigation's own evolution through 17 experiments. They are not imported from external sources. They will be validated or contradicted by future implementations. Record which principle is challenged first — it will be the most informative.

docs/design-evolution-log.md

@@ -817,7 +817,22 @@ Architectural.
 
 #### Evaluation
 
-Pending.
+Confirmed.
+
+---
+
+## What did we learn?
+
+Document observations such as:
+
+- Investigation state is distinct from behaviour.
+- Behaviour should consume assessment rather than graph structure.
+- State assessment provides a stable contract between reasoning and facilitation.
+- The architecture is becoming layered rather than procedural.
+
+Decision:
+
+Proceed to documenting the investigation turn cycle.
 
 ---
 
@@ -871,6 +886,38 @@ This architecture emerged from observation, not top-down design. It may still ch
 
 ---
 
+### Experiment 17 — Investigation Turn Cycle
+
+#### Hypothesis
+
+A complete investigation can be described as a repeating turn cycle in which every architectural layer has a single responsibility.
+
+Status
+
+Architectural.
+
+Evaluation
+
+Pending.
+
+---
+
+## Phase Transition
+
+Record that the project has moved from:
+
+Interface Design
+→
+Facilitated Investigation
+→
+Behavioural Architecture
+→
+System Architecture
+
+Future work should validate these layers rather than introduce new ones.
+
+---
+
 ## Emerging Direction — Graph as Source of Truth
 
 The first UX experiments focused on workspace structure.

docs/failure-modes.md

@@ -0,0 +1,213 @@
+# Failure Modes — Architecture Experiment 17
+
+> This is a design document only. Do not implement yet.
+> Record failures as they are identified, do not solve them here.
+> Solving these failures becomes future experimental work.
+
+---
+
+## Failure Mode 1 — Graph Incomplete at Narrative Stage
+
+### Sequence
+
+Graph incomplete → Narrative weak → Assessment unreliable → Behaviour inappropriate → Poor question → User confidence falls
+
+### Description
+
+If the reasoning graph fails to capture a critical observation (node missing, relationship not established, status incorrectly marked), the narrative produced from it will be structurally weaker than reality. The assessment will evaluate a distorted picture. The behaviour selection will deploy based on incorrect state. The conversation response will ask about something already known or miss something urgently uncertain.
+
+### Observable Signal
+
+Narrative contains gaps that the user immediately recognises. "But I already told you that" or "You're asking about X when Y was just established."
+
+### Do Not Solve Here
+
+This is a graph integrity problem, not a narrative or behaviour problem. The solution belongs in graph reasoning validation, not in these layers.
+
+---
+
+## Failure Mode 2 — Narrative Over-translates Graph
+
+### Sequence
+
+Narrative invents synthesis → Assessment receives fabricated coherence → Behaviour selects confident action → User perceives overconfidence → Trust erodes
+
+### Description
+
+The narrative layer may produce a coherent-sounding summary by connecting graph nodes that were never connected by the reasoning engine. The assessment then evaluates this artificially coherent picture. The behaviour becomes overconfident because the narrative shows strong convergence where none actually exists in the graph.
+
+### Observable Signal
+
+User feels the facilitator is "seeing patterns that aren't there" or "connecting things I didn't connect." Confidence in the system decreases.
+
+### Do Not Solve Here
+
+This is a narrative translation constraint problem. The solution belongs in the narrative composition rules (Experiment 14), specifically the "Never invent facts" principle.
+
+---
+
+## Failure Mode 3 — Assessment Reaches False Precision
+
+### Sequence
+
+Assessment assigns definitive values → Behaviour reads confidence that doesn't exist → Response over-commits to interpretation → User corrects → Investigation backtracks
+
+### Description
+
+The assessment may assign values (e.g., "Evidence Quality: Strong") that appear certain but are based on insufficient or noisy data. When the behaviour layer treats this as high-confidence input, it deploys actions that assume more certainty than actually exists. The user must then correct the facilitator's overconfidence.
+
+### Observable Signal
+
+User explicitly states uncertainty in areas where the system acts confidently. "That doesn't seem right yet" or "We're not at that stage."
+
+### Do Not Solve Here
+
+This is an assessment precision problem. Principle 6 of the state assessment architecture (Assessment Is Stateful Across Turns, Uncertainty About Assessment Is Itself Assessable) partially addresses this but does not solve it.
+
+---
+
+## Failure Mode 4 — Behaviour Selection Overlaps or Conflicts
+
+### Sequence
+
+Multiple dimensions signal different behaviours → Selection picks one → Other needs unmet → Investigation feels inconsistent → User confused about direction
+
+### Description
+
+Different assessment dimensions may converge on different behaviours (e.g., Evidence Quality: Contradictory suggests Challenge assumption, while Understanding Trajectory: Consolidating favours Refine understanding). The selection layer must choose one, leaving the other need unaddressed. Over turns this creates an inconsistent investigative personality.
+
+### Observable Signal
+
+The facilitator feels like different people on different turns — sometimes synthesising when the user needs precision, sometimes questioning when the user needs acknowledgment.
+
+### Do Not Solve Here
+
+This is a behaviour selection priority problem. The decision matrix in Experiment 16 captures some patterns but does not resolve conflicts between equally urgent signals.
+
+---
+
+## Failure Mode 5 — Conversation Response Does Not Match Selected Behaviour
+
+### Sequence
+
+Behaviour correctly selected → Response generation diverges from behaviour intent → User receives wrong type of interaction → Investigation rhythm disrupted
+
+### Description
+
+The selected behaviour may be correct (e.g., "Pause" to hold space after a significant insight), but the conversation response layer may generate an active question instead of holding space. The behavioural intention is lost in translation between abstract selection and concrete text generation.
+
+### Observable Signal
+
+User says "I was still thinking about that" or "Don't ask me another question yet." The facilitator pushes forward when it should have held.
+
+### Do Not Solve Here
+
+This is a response generation alignment problem. It requires ensuring the text generation layer respects the behavioural intention constraint — but the mechanics of that alignment are not solved here.
+
+---
+
+## Failure Mode 6 — Workspace Projects Stale State
+
+### Sequence
+
+State changes during turn → Workspace renders before update complete → User sees contradiction between conversation and panels → Cognitive dissonance
+
+### Description
+
+If the workspace projection renders from a narrative state that has not yet been fully updated (e.g., a node was just resolved but the panel still shows it as unknown), the user receives conflicting information across interface areas.
+
+### Observable Signal
+
+Facilitator says "We now know X" while the panel still lists X as an active unknown. Or vice versa.
+
+### Do Not Solve Here
+
+This is a synchronisation and rendering timing problem, not an architectural layer problem.
+
+---
+
+## Failure Mode 7 — User Withholds Information Due to Misreading Facilitator State
+
+### Sequence
+
+Facilitator appears confident → User withholds doubt → Graph receives incomplete data → Assessment evaluates distorted picture → Investigation proceeds on false foundation
+
+### Description
+
+If the workspace or conversation makes the facilitator appear more confident or certain than it should be, the user may stop providing information they think is irrelevant. The graph then operates on an incomplete picture. Subsequent turns compound the error because each new turn starts from a fundamentally wrong state.
+
+### Observable Signal
+
+User's contributions become shorter over time. They answer questions but do not volunteer context they clearly possess. "That's everything I know" when they clearly know more.
+
+### Do Not Solve Here
+
+This is a confidence signalling and user psychology problem. It touches every layer because a false sense of completeness can be communicated through narrative language, assessment presentation, or conversation tone.
+
+---
+
+## Failure Mode 8 — Assessment Accumulates Error Across Turns
+
+### Sequence
+
+Assessment slight overconfidence → Behaviour slightly wrong → Graph updates based on that wrong behaviour → Next assessment builds on wrong graph → Error compounds
+
+### Description
+
+The assessment layer (Principle 5: Assessment Is Stateful Across Turns) accumulates state. If early turns establish an incorrect trajectory, each subsequent turn's assessment inherits and amplifies that error. The investigation enters a state where it cannot self-correct because every layer is built on the same mistaken foundation.
+
+### Observable Signal
+
+The investigation feels like it is "going in circles" but for a reason the user cannot articulate. Turns happen frequently but understanding does not advance.
+
+### Do Not Solve Here
+
+This is a systemic error accumulation problem. It may require periodic re-evaluation of earlier turns, or explicit anomaly detection when assessment signals contradict across dimensions.
+
+---
+
+## Failure Mode 9 — Behaviour Readiness Produces Conservative Paralysis
+
+### Sequence
+
+Assessment shows multiple uncertain dimensions → Readiness narrows behaviour options to safe defaults → Facilitator only acknowledges and clarifies → Investigation stalls because no new direction is ever proposed
+
+### Description
+
+When the assessment correctly identifies uncertainty across most dimensions, the behaviour readiness layer may produce a narrow set of "safe" behaviours (Acknowledge, Clarify). The facilitator becomes overly conservative, repeatedly acknowledging without advancing. The investigation stalls because no bold action was ever taken.
+
+### Observable Signal
+
+The user feels stuck in an acknowledgment loop. "I know you've heard me — what should I think about next?"
+
+### Do Not Solve Below
+
+This is a risk tolerance problem at the behaviour selection layer. The system needs permission to act with partial information — but the threshold for that permission is not defined here.
+
+---
+
+## Failure Mode 10 — Narrative Becomes Too Complex for User Cognitive Load
+
+### Sequence
+
+Graph grows dense → Narrative includes all available sections → User sees too much simultaneously → Investigation Map becomes incomprehensible → User disengages
+
+### Description
+
+As the investigation deepens, more narrative sections become populated. If all are presented simultaneously, the workspace may overwhelm rather than clarify. The user cannot find what matters because everything is equally visible.
+
+### Observable Signal
+
+User stops reading panels. They focus only on the conversation lane and ignore status, understanding, or evidence displays entirely.
+
+### Do Not Solve Here
+
+This is a presentation selection problem — not all narrative sections need to be visible at all times. Progressive disclosure should be governed by investigation phase and user state, but this is an implementation detail.
+
+---
+
+## Recording Note
+
+These failure modes are observations, not requirements for solutions. Each identifies where the architecture may fail when implemented. Which of these actually occur — and in what order — can only be determined through experimentation with working implementations.
+
+This document exists so that future experiments know what to watch for.

docs/investigation-turn-cycle.md

@@ -0,0 +1,270 @@
+# Investigation Turn Cycle — Architecture Experiment 17
+
+> This is a design document only. Do not implement yet.
+
+---
+
+## Hypothesis
+
+A complete investigation can be described as a repeating turn cycle in which every architectural layer has a single responsibility.
+
+Each turn follows a deterministic sequence of stage transitions. No stage performs the work of another. Feedback flows upward through the same layers it passes on the way down.
+
+---
+
+## The Turn Cycle
+
+```
+User submits an observation
+  ↓
+Reasoning Graph updates
+  ↓
+Investigation Narrative updates
+  ↓
+State Assessment evaluates progress
+  ↓
+Behaviour Selection determines response type
+  ↓
+Conversation generates response
+  ↓
+Workspace projects state
+  ↓
+Wait for next user observation
+```
+
+Each stage below describes its purpose, inputs, outputs, and constraints.
+
+---
+
+## Stage 1 — User Observation
+
+### Purpose
+
+The investigation begins when the user provides a new observation, confirmation, correction, or additional context.
+
+### Inputs
+
+Nothing system-generated. This stage is entirely user-driven.
+
+### Outputs
+
+A text contribution that becomes the raw material for graph reasoning.
+
+### Must Never
+
+- Anticipate what the user will say.
+- Pre-fill or suggest content before the observation arrives.
+- Treat the observation as a completed analysis — it is a starting point.
+
+---
+
+## Stage 2 — Reasoning Graph Update
+
+### Purpose
+
+Update the internal machine representation of knowledge with the new observation. Determine what changed: what was confirmed, what was contradicted, what new unknowns emerged, and how existing nodes relate to the new information.
+
+### Inputs
+
+- Current reasoning graph (all known nodes, edges, states).
+- User's observation text.
+
+### Outputs
+
+- Updated graph with new or modified nodes.
+- Status markers: resolved, confirmed, contradicted, introduced, unchanged.
+- Newly created edges representing relationships between old and new information.
+- Provenance links tracing each conclusion back to user input.
+
+### Must Never
+
+- Produce narrative language.
+- Select facilitator behaviour.
+- Decide what the user should see.
+- Skip updating when the observation contradicts existing knowledge.
+- Invent connections the evidence does not support.
+
+---
+
+## Stage 3 — Investigation Narrative Update
+
+### Purpose
+
+Translate the updated graph into a coherent human-understandable representation of investigation state. This is what the investigator currently knows, what remains uncertain, and how understanding has changed since the last turn.
+
+### Inputs
+
+- Updated reasoning graph from Stage 2.
+
+### Outputs
+
+A structured narrative containing:
+- Current understanding (what is known).
+- Active unknowns (what remains to be investigated).
+- Evidence gathered (contributions and discoveries).
+- Confidence signals (qualitative certainty indicators).
+- Reason investigation continues (why we are not complete).
+- Recent progress (what changed since last turn).
+
+### Must Never
+
+- Generate new reasoning or evidence.
+- Decide what behaviour to deploy.
+- Omit information that exists in the graph.
+- Invent facts not traceable to graph nodes.
+- Present developer-oriented graph structure to the user.
+
+---
+
+## Stage 4 — State Assessment
+
+### Purpose
+
+Evaluate where the investigation is across multiple analytical dimensions so that behaviour selection can operate on *state* rather than *implementation details*. This layer answers: "Given where we are, what kind of help is most appropriate right now?"
+
+### Inputs
+
+- Investigation Narrative from Stage 3.
+- Turn history (previous assessments and their trajectories).
+
+### Outputs
+
+A structured assessment across seven dimensions:
+1. **Current Investigation Phase** — Orienting / Exploring / Focusing / Deepening / Synthesising / Concluding
+2. **Investigation Progress** — Accelerating / Steady / Stalled / Looping / Spiralling
+3. **Evidence Quality** — Weak / Mixed / Strong / Contradictory
+4. **Understanding Trajectory** — Growing / Static / Confused / Consolidating
+5. **Uncertainty Trend** — Increasing / Reducing / Stable / Asymmetric
+6. **Conversation Health** — Healthy / Repetitive / Too broad / Too narrow / User overloaded / User under-informed
+7. **Behaviour Readiness** — Which behaviours are available, pressed for, inappropriate, or stable
+
+### Must Never
+
+- Select a behaviour directly.
+- Inspect graph nodes or edges.
+- Produce user-facing language.
+- Make decisions — only describe state.
+- Skip assessment because the turn appears "unimportant."
+
+---
+
+## Stage 5 — Behaviour Selection
+
+### Purpose
+
+Determine which expert facilitator behaviour to deploy based on the assessment from Stage 4. This is where the system moves from *describing* what is happening to *choosing* what kind of help to provide.
+
+### Inputs
+
+- State Assessment (all seven dimensions) from Stage 4.
+- Inventory of available behaviours (14 patterns documented in `facilitator-behaviour.md`).
+
+### Outputs
+
+A selected behaviour and its intended effect on the investigation:
+- The specific behaviour to deploy (Orient / Acknowledge / Observe pattern / Clarify / Validate / Connect / Challenge assumption / Refine understanding / Expose uncertainty / Decide direction / Pause / Avoid premature closure / Communicate confidence honestly / Progressively narrow focus).
+- Confidence in the selection (high when multiple dimensions converge; moderate when signals are mixed).
+
+### Must Never
+
+- Reason about the investigation's content.
+- Generate a question or response text directly.
+- Bypass assessment and inspect the graph.
+- Deploy a behaviour that the phase constrains against (e.g., Orient in Deepening phase).
+- Select more than one primary behaviour per turn.
+
+---
+
+## Stage 6 — Conversation Response
+
+### Purpose
+
+Execute the selected behaviour through natural language. This is where abstract behavioural intention becomes a concrete, user-facing interaction.
+
+### Inputs
+
+- Selected behaviour and its intended effect from Stage 5.
+- Current Narrative from Stage 3 (content to reference in the response).
+- Investigation context (situation, history, what was just learned).
+
+### Outputs
+
+A conversational response that:
+- Matches the selected behaviour's intent.
+- Acknowledges what the user contributed.
+- Advances the investigation along a coherent thread.
+- Communicates confidence proportionally to evidence quality.
+- Contains a clear next step if one is needed.
+
+### Must Never
+
+- Introduce content not supported by the narrative or graph.
+- Ask a question that does not serve the selected behaviour.
+- Overstate confidence in what is known.
+- Understate confidence where evidence is strong.
+- Respond to user input without first acknowledging it.
+
+---
+
+## Stage 7 — Workspace Projection
+
+### Purpose
+
+Render the current investigation state into visible UI panels so the user can see what is known, what remains uncertain, and how they arrived at this point. This is a passive projection — it shows but does not decide.
+
+### Inputs
+
+- Investigation Narrative from Stage 3.
+- State Assessment from Stage 4 (for display labels like phase indicators).
+- Behaviour Selection from Stage 5 (to contextualise the current interaction mode).
+
+### Outputs
+
+Panel projections including:
+- Facilitator view (current understanding, active unknowns, what matters next).
+- Investigation status (phase, progress signals, evidence quality).
+- Situation and investigation map (reference artefacts, stable across turns).
+- History (growing conversation log extending from the response).
+
+### Must Never
+
+- Generate content independently of the narrative.
+- Display information that contradicts the assessment.
+- Update based on behaviour selection — it shows state, not action intent.
+- Re-implement graph-to-narrative translation.
+
+---
+
+## Stage 8 — Wait for Next Observation
+
+### Purpose
+
+Return control to the user. The turn is complete when the user sees their response reflected in the workspace and receives a conversation prompt that invites continued investigation.
+
+### Inputs
+
+Everything produced in previous stages, now rendered for user consumption.
+
+### Outputs
+
+Nothing system-generated. The next observation originates entirely from the user.
+
+### Must Never
+
+- Proceed to the next turn before the user responds.
+- Auto-generate observations or continue without user input.
+- Change the workspace state while waiting (beyond loading indicators).
+
+---
+
+## What This Turn Cycle Proves
+
+The investigation turn cycle is not a new layer. It is an observation about how existing layers interact during a real investigation. It confirms that:
+
+1. Every layer has a single responsibility.
+2. Information flows downward through the architecture.
+3. Feedback flows upward when the user provides a new observation.
+4. No layer inspects another's implementation details.
+5. The cycle is deterministic in structure but adaptive in content.
+
+This document records what the investigation *does*, not how it is implemented.

docs/success-signals.md

@@ -0,0 +1,195 @@
+# Success Signals — Architecture Experiment 17
+
+> This is a design document only. Do not implement yet.
+> Record observations about what success looks like across the investigation turn cycle.
+
+---
+
+## Signal 1 — Narrative Becoming Simpler Over Time
+
+### Observation
+
+Early turns produce dense, broad narratives. As the investigation progresses, the narrative should become *simpler* — fewer active unknowns, tighter understanding, more resolved items. If narrative complexity increases as the investigation continues, that is a failure signal.
+
+### What It Looks Like
+
+- Early turn: "We know some things about X. We don't know Y, Z, or W. There are several possibilities for each."
+- Later turn: "We have narrowed it to two scenarios. The key question is whether A or B applies."
+- Final turn: "The evidence points to one scenario with high confidence. Two areas remain untested and do not affect the conclusion."
+
+### Why It Matters
+
+Real investigations simplify. A real expert helps you see less, not more, as understanding deepens. If the narrative gets more complex over time, the investigation is spiralling rather than converging.
+
+---
+
+## Signal 2 — Uncertainty Becomes Targeted Rather Than Diffuse
+
+### Observation
+
+Early uncertainty is broad ("I don't know much about this situation"). Successful investigations narrow uncertainty to specific, high-value questions. The user should be able to articulate exactly what remains unknown and why it matters.
+
+### What It Looks Like
+
+- Early: "There are a lot of things I'm not sure about."
+- Middle: "I need to figure out whether the revenue model is sustainable or if this is just temporary."
+- Late: "We've established the cost structure. The remaining uncertainty is about customer retention, which affects the bottom line but not the current viability."
+
+### Why It Matters
+
+Diffuse uncertainty paralyzes decision-making. Targeted uncertainty enables action. The investigation's value increases as uncertainty narrows, even if total uncertainty count remains high (one deeply uncertain critical question is more valuable than ten vaguely uncertain peripheral ones).
+
+---
+
+## Signal 3 — Questions Become Narrower and More Precise
+
+### Observation
+
+Early questions are broad and exploratory ("Tell me about the situation"). Successful investigations produce progressively narrower questions. The user should find themselves answering increasingly specific prompts rather than restating what they already know.
+
+### What It Looks Like
+
+- Turn 2: "What have you noticed about the customer base?"
+- Turn 5: "Of the three segments you identified, which has the highest lifetime value and why?"
+- Turn 8: "You said segment A has higher retention. Is that due to switching costs or product differentiation?"
+
+### Why It Matters
+
+Broad questions indicate the investigation is still in orienting mode. Precise questions indicate it has moved through exploring and focusing into deepening. The narrowing trajectory *is* progress — even if nothing has been conclusively resolved yet.
+
+---
+
+## Signal 4 — User Provides Richer Observations Over Time
+
+### Observation
+
+As the investigation continues, user contributions should become richer in structure, not just quantity. The user should begin providing evidence, distinguishing facts from assumptions, and offering connections between topics without being asked.
+
+### What It Looks Like
+
+- Turn 1: "Business is struggling."
+- Turn 4: "Revenue dropped 20% but costs stayed flat. I think the issue is customer churn, not acquisition."
+- Turn 7: "I've checked the data — churn is up 15% in Q3. The correlation with the pricing change is clear, but I haven't looked at whether it's price sensitivity or product quality."
+
+### Why It Matters
+
+This signal indicates the user is thinking *with* the facilitator, not just *for* it. The investigation has shifted from information collection to shared reasoning. This is the strongest signal that the behaviour model is working — the user is adopting investigative patterns they did not start with.
+
+---
+
+## Signal 5 — Behaviour Requires Fewer Clarifications
+
+### Observation
+
+Early turns require frequent clarification of behaviour intent ("Why are you asking me this?" "What are we trying to find out?"). Successful investigations reduce these meta-comments as the user understands the pattern of interaction.
+
+### What It Looks Like
+
+- Early: "Wait, why are you focusing on X when Y seems more important?"
+- Middle: Occasional "How does that relate?" but mostly continuing without reorienting.
+- Late: No meta-comments. The user answers directly and sometimes anticipates the next question.
+
+### Why It Matters
+
+Meta-comments indicate the user is trying to understand the *process* rather than engage with the *content*. When the process becomes transparent, meta-comments disappear naturally. This is a signal that the investigation rhythm feels natural, not mechanical.
+
+---
+
+## Signal 6 — Shared Understanding Increases Measurably
+
+### Observation
+
+The gap between what the user knows and what the system represents should shrink over time. The user should frequently recognise the workspace as an accurate reflection of their thinking.
+
+### What It Looks Like
+
+- "That's exactly how I see it."
+- "You just said what I was trying to figure out."
+- Periodic corrections that are minor ("Well, not exactly X — more like Y").
+- User starts referencing the workspace in conversation ("Looking at what we know, it seems like...").
+
+### Why It Matters
+
+Shared understanding is the core objective of the investigation. If the user treats the workspace as an externalisation of their own thinking rather than a separate system's analysis, the architecture is working as intended. The facilitator becomes a mirror, not an interrogator.
+
+---
+
+## Signal 7 — Investigation Reaches Appropriate Termination Without Force
+
+### Observation
+
+A successful investigation ends when understanding is sufficient for the user's purpose, not when every unknown is resolved. The user should signal readiness to conclude, and the facilitator should recognise and validate that readiness without pushing further.
+
+### What It Looks Like
+
+- User states they have what they need.
+- Facilitator acknowledges completion without introducing new lines of enquiry.
+- Narrative presents a coherent summary rather than a list of remaining gaps.
+- User reports feeling confident in their understanding, even with residual uncertainty.
+
+### Why It Matters
+
+An investigation that cannot end is worse than one that ends early. The ability to know when enough is enough — and to present the findings clearly — is arguably more important than finding every last answer. This signal validates that the architecture supports closure as a first-class state, not an afterthought.
+
+---
+
+## Signal 8 — Investigation Feels Like Conversation Rather Than Questionnaire
+
+### Observation
+
+The user should lose awareness of the turn structure. They should not feel like they are answering questions in a process but thinking through a situation with someone who helps them see more clearly.
+
+### What It Looks Like
+
+- User forgets to answer all parts of a question because the conversation moved on naturally.
+- Conversation contains acknowledgments, pauses, and synthesising alongside questions.
+- The facilitator sometimes says "That's interesting" without immediately asking another question.
+- Turns feel organic in length — some are short exchanges, some are long explorations.
+
+### Why It Matters
+
+This is the ultimate validation of the behavioural model (Experiment 15). If the investigation feels like a questionnaire, the behaviour selection is mechanical regardless of how sophisticated the assessment logic becomes. The architecture succeeds when the user experiences facilitated thinking, not automated investigation.
+
+---
+
+## Signal 9 — Multiple Narrative Projections Serve Different Users Equally Well
+
+### Observation
+
+The same investigation should produce useful projections for different audiences: a concise summary for executives, a detailed trace for technical reviewers, and a facilitator view for the active investigator. Each projection should be accurate but optimised for its audience's needs.
+
+### What It Looks Like
+
+- Executive sees: "Three scenarios evaluated. Recommendation: Scenario B. Confidence: substantial. Remaining uncertainty affects timeline only."
+- Technical reviewer sees: Full trace from findings back to original observations, with epistemic labels on each link.
+- Active investigator sees: Current understanding, active unknowns, confidence signals, and next action — all in one glance.
+
+### Why It Matters
+
+This validates the narrative-as-intermediate-layer architecture (Experiment 14). If a single narrative can be projected into multiple accurate but audience-appropriate views without re-implementing translation logic per view, the layer separation is architecturally sound.
+
+---
+
+## Signal 10 — Investigation Self-Corrects Without User Intervention
+
+### Observation
+
+When the user corrects the facilitator ("That's not right" or "I didn't mean X"), the investigation should recover gracefully within one or two turns. The system should acknowledge the correction, update its understanding, and reorient without requiring the user to explain themselves multiple times.
+
+### What It Looks Like
+
+- User: "Actually, that's not quite right."
+- Facilitator (next turn): "You're right — I misinterpreted your earlier point. The situation is closer to Y than X. Let me adjust our understanding accordingly."
+- Investigation continues from the corrected state without re-explaining what was already established.
+
+### Why It Matters
+
+Robustness of correction is a measure of architectural health. If every mistake requires restarting or extensive re-explanation, the layers are too tightly coupled or the graph representation lacks sufficient expressiveness. Graceful self-correction indicates healthy layer boundaries.
+
+---
+
+## Recording Note
+
+These success signals are observations about what effective facilitated investigation looks like from the user's perspective. They describe outcomes at the human-computer interface boundary — where the architecture either succeeds or fails in its purpose.
+
+Which of these actually emerge during implementation will only be known through experimentation. Some may require redefinition. All should guide evaluation of future working implementations.