docs/current-project-state.md

@@ -102,9 +102,9 @@ First document to read: `docs/current-project-state.md`. Then consult `.claude/a
 
 Nothing has been archived, moved or deleted. Before changing the documentation structure, review whether the new entry point reliably replaces the large log section and whether any historical documents should be formally archived.
 
-### Return-to-Work Note (updated Experiment 29)
+### Return-to-Work Note (updated Experiment 30)
 
-The current-state briefing was checked against source code via targeted code inspection of API routes, orchestrator imports/calls, and cross-module traces for each passive classifier. Five active capabilities are confirmed (reconstruction, graph updates, unknown selection, question formulation, turn orchestration). Seven passive capabilities remain classified as diagnostic_only (investigation-state assessment) or isolated (behaviour selection, decision-condition status, evidence direction, evidence scope, question importance, question relevance to decision, scope-aware condition status). No corrections to the current-state document were required. Knowledge-management experiments continue: selected historical documents have been archived to `docs/archive/`; nothing was deleted. The archive index explains where older evidence lives and when to consult it. Engine and UI experiments remain paused. First file to inspect when resuming: `docs/current-project-state.md`, then `.claude/architecture-guardrails.md` before any code changes, then `lib/graph/orchestrator.js` for engine-resumption work.
+The current-state briefing was checked against source code via targeted code inspection of API routes, orchestrator imports/calls, and cross-module traces for each passive classifier. Five active capabilities are confirmed (reconstruction, graph updates, unknown selection, question formulation, turn orchestration). Seven passive capabilities remain classified as diagnostic_only (investigation-state assessment) or isolated (behaviour selection, decision-condition status, evidence direction, evidence scope, question importance, question relevance to decision, scope-aware condition status). No corrections to the current-state document were required. Knowledge-management experiments continue: five historical documents have been archived to `docs/archive/` per Experiment 29; two deferred documents reviewed in Experiment 30 (architectural-principles.md kept as task-specific reference; backlog info.md retained temporarily pending revision — neither moved). Engine and UI experiments remain paused. First file to inspect when resuming: `docs/current-project-state.md`, then `.claude/architecture-guardrails.md` before any code changes, then `lib/graph/orchestrator.js` for engine-resumption work.
 
 ## Verification Marker
 

docs/design-evolution-log.md

@@ -1758,3 +1758,50 @@ These are observations, not implementation tasks.
 - Narrative testing
 - Narrative localisation
 - Multiple narrative projections
+
+## Experiment 30 — Review Deferred Project Documents
+
+**Status:** Pending Rob's review
+
+### Hypothesis
+
+Each deferred document can be classified by comparing it with the verified current project state without reopening the full experiment history or rewriting its contents. The result may be: keep as current guidance, keep as task-specific reference, archive as historical evidence, or retain temporarily pending revision. No additional categories should be invented.
+
+### Review of architectural-principles.md
+
+- **14 principles assessed against verified implementation:**
+  - **6 current (match runtime or guardrails):** P1 (layer separation), P3 (user feedback loop), P4 (reasoning/UI separation), P6 (presentation renders, does not interpret), P8 (narrative never invents facts), P14 (user as first-class input).
+  - **4 aspirational targets:** P5 (behaviour never reasons — module exists with zero callers), P10 (convergence over single signals — no mechanism), P11 (stateful assessment across turns — partially present), P12 (assessable uncertainty — absent).
+  - **4 mixed/unclear:** P2 (information flows downward — partially matches but passive layers don't fit the cascade model), P7 (assessment never generates evidence — diagnostic_only but scope-aware condition status makes interpretive judgments), P9 (assessment describes not prescribes — signals descriptive, but decision-condition evaluation borders on prescription), P13 (progress qualitative not quantitative — product direction supports; unknown selection uses node status qualitatively but not verified).
+  - **3 duplicated with guardrails:** P1 overlaps with architecture-guardrails' prohibition list. P4 overlaps with UX-task boundaries in guardrails. P8 overlaps with the explicit invariant "every question comes from a resolved graph node." Overlap adds value: guardrails state boundaries; principles explain why.
+
+- **Role assigned:** Keep as task-specific reference. Six current principles and four aspirational targets make it valuable when resuming reasoning architecture work. Three duplications reduce (but don't eliminate) its independent value — the derived-from/implication context adds what guardrails lack. project-knowledge-inventory already listed it under "Review Before Archive"; confirmed as task-specific reference.
+
+### Review of backlog info.md
+
+- **Content analysis:**
+  - **Still-relevant (≈20 lines):** Mock fixtures table — 15 scenario types with purposes and examples. Directly useful when UI work resumes.
+  - **Historical/aspirational (≈370 lines):** UX roadmap phases 1–4 with wireframe text, animation specs, loading messages. Design intent is valid; specifics may change when UI resumes. Untracked — no commit/PR linkage.
+  - **Duplicates:** Phase 4 "Mock Scenario Library" duplicates the fixtures table at top. "Deliberately Out of Scope" repeats pause decision in current-project-state and project-context.
+
+- **Role assigned:** Retain temporarily pending revision. The mock fixtures table is too useful to lose in an archive, but the document's mixed role (useful reference + deferred planning) needs resolution when UI work resumes. Splitting the file or archiving portions requires revising content — constraints forbid this now.
+
+### Practical Routing Test Result
+
+**Task:** A future Claude session is about to work on UI mocks. Should it read architectural-principles.md, backlog info.md, both, or neither?
+
+**Answer: Both.** Backlog info.md provides the mock fixtures table (direct reference). Architectural-principles.md provides boundaries (P4: reasoning never communicates directly with UI; P6: presentation never interprets) that prevent accidentally introducing reasoning logic into UI work. Three-document context (current-project-state, project-knowledge-inventory, document-role-review) is sufficient to route both documents correctly without reading the full experiment log or archive.
+
+### Files Created / Modified
+
+- `docs/document-role-review.md` — new (140 lines); classifies both candidates with evidence and routing test
+- `docs/project-knowledge-inventory.md` — updated "Review Before Archive" table (principle roles added), added "Knowledge management" section with document-role-review entry, updated Return-to-Work note
+- `docs/current-project-state.md` — updated Return-to-Work note to include Experiment 30 status
+- No files moved to archive (neither candidate qualifies as "archive as historical evidence")
+- No files deleted; no source code or tests changed
+
+### Status
+
+Pending Rob's review. Neither document moves. Both roles confirmed by evidence against verified implementation. When UI work resumes, backlog info.md's fixtures table will be the direct reference; architectural-principles.md is available for reasoning architecture context. Engine and UI experiments remain paused. Branch: `feature/user-workspace-ux-v0.7`. First file to inspect when resuming: `docs/current-project-state.md`, then Experiments 23–25B in design-evolution-log.md (lines 1218–1520).
+
+These are observations, not implementation tasks.

docs/document-role-review.md

@@ -0,0 +1,140 @@
+# Document Role Review — Experiment 30
+
+## 1. Review Method
+
+**Documents reviewed (as constrained):**
+
+- `docs/current-project-state.md` (entire file)
+- `docs/current-implementation-verification.md` (entire file)
+- `docs/project-knowledge-inventory.md` (Task-Specific References, Historical and Archive Candidates, Gaps and Duplications)
+- `docs/archive/README.md` (archive rules only)
+- `docs/architectural-principles.md` (entire file)
+- `docs/backlog info.md` (entire file)
+- `.claude/architecture-guardrails.md` (entire file)
+- `docs/design-evolution-log.md` Experiment 29 entry (lines 1703–1761)
+
+**Classification criteria:** Each candidate was assessed against current-project-state's verified active/passive capability list, implementation-verification's cross-module traces, project-knowledge-inventory's stated roles, and architecture-guardrails' current invariants. A principle is "current" if it matches a confirmed runtime pattern or guardrail. "Aspirational" if the target exists but no working implementation drives it yet. "Duplicated" if it restates content found more concisely in another document. "Unclear/outdated" if its source experiment or implication cannot be verified against current state.
+
+---
+
+## 2. Architectural Principles Review
+
+### Current principles (match verified implementation or guardrails)
+
+| Principle | Status | Evidence |
+|---|---|---|
+| P1 — Every Layer Has One Responsibility | **Current** | Passive classifiers are isolated modules; orchestrator imports them separately. Matches guardrails' separation discipline. |
+| P3 — Feedback Flows Upward Through the User | **Current** | Product is "facilitated investigation"; turn cycle confirms user-driven feedback loop. |
+| P4 — Reasoning Never Communicates Directly With the UI | **Current** | Narrative layer exists as contract; guardrails enforce separation explicitly. |
+| P6 — Presentation Never Interprets | **Current** | v0.7 UX panels driven by narrative; no panel reimplements filtering. Matches guardrails. |
+| P8 — Narrative Never Invents Facts | **Current** | Core invariant in architecture-guardrails. Traced to runtime narrative adapter. |
+| P14 — The User Is Part of the Architecture | **Current** | v0.7 UX design and product direction confirm user as first-class participant. |
+
+### Aspirational principles (target exists but not fully implemented)
+
+| Principle | Status | Evidence |
+|---|---|---|
+| P5 — Behaviour Never Reasons | **Aspirational** | behaviour-selection module exists but has zero callers outside its own file. Target is defined; runtime enforcement pending. |
+| P7 — Assessment Never Generates Evidence | **Mixed** | assessment layer is diagnostic_only (verified). However, scope-aware condition status makes interpretive judgments about evidence direction — bordering on generating new claims. |
+| P9 — Assessment Describes, Never Prescribes | **Mixed** | Signals are currently descriptive in the assessor, but decision-condition status evaluates "support/contradict/inform" which moves toward prescription. Partially implemented. |
+| P10 — Convergence Over Single Signals | **Aspirational** | Passive classifiers produce multiple dimensions but no explicit convergence logic exists. Target stated; no mechanism. |
+| P11 — Assessment Is Stateful Across Turns | **Mixed/Aspirational** | Assessor exists and tracks per-turn state, but cross-turn accumulation (deltas, trends) is not verified against the current assessor output shape. Partial at best. |
+| P12 — Uncertainty About Assessment Is Itself Assessable | **Aspirational** | No confidence-per-dimension field visible in the assessor output. Concept stated; mechanism absent. |
+| P13 — Investigation Progress Is Qualitative Not Quantitative | **Mixed/Aspirational** | Product direction states "quality over quantity." Unknown selection uses graph node status (qualitative) but is not verified to explicitly reject count-based progress. Partial match. |
+
+### Duplicated principles
+
+- **P1** overlaps with architecture-guardrails' hard boundaries (each layer one responsibility is implicit in guardrails' exhaustive prohibition list).
+- **P4** overlaps with architecture-guardrails' explicit boundary list for UX tasks (reasoning code must not be modified during UI work).
+- **P8** overlaps with the invariant "Every user-facing question comes from an explicit unresolved graph node" and narrative layer's documented purpose in project-knowledge-inventory.
+
+No principle is *wholly* duplicated — all retain value as articulated principles, but three overlap with guardrails content that is more operationally concise.
+
+### Unclear or outdated statements
+
+- **P2 — Information Flows Downward**: The principle describes an ideal data flow that partially matches (graph → narrative → ...), but the passive classifier layers (evidence direction, scope detection) operate laterally rather than in the described cascade. Documented as "unresolved" in current-project-state section 5 regarding how these layers integrate. **Not outdated — unresolved.**
+- The header line "Architecture Experiment 17" is accurate for origin but does not note that principles extend through Experiments 1–17 and have been partially validated by later experiments (18–25B). No correction needed; the header is historical provenance.
+
+### Recommended document role: **Keep as task-specific reference**
+
+### Evidence for recommendation
+
+- Six principles are current and useful when reviewing or resuming reasoning architecture work.
+- Four principles are aspirational but define clear targets — they are valuable *as goals* for future engineering.
+- Three principles overlap with architecture-guardrails but add explanatory context (derived-from, implications) that guardrails lack. Guardrails state the boundary; principles explain why.
+- The document is 306 lines of structured reasoning history — too long to load by default but valuable when a task involves reasoning architecture or design justification.
+- project-knowledge-inventory already lists it as "Review Before Archive (may have future value)." This experiment confirms that assessment: the principles are neither purely current nor purely historical — they are a reference with mixed provenance, best kept where it is but labeled clearly for future Claude sessions.
+
+---
+
+## 3. Backlog Information Review
+
+### Still-relevant content
+
+- **Mock fixtures table** (15 rows): The list of scenario types and their purposes remains valid as a UI mock development reference. These fixture categories map to actual investigation states that need testing when UI work resumes.
+- **"Deliberately Out of Scope"** section: Correctly documents the current product boundary — reasoning engine expansion is deferred while UX experience is prioritized. This matches current-project-state section 6 (both engine and UI paused) and product direction in project-context.
+
+### Historical content
+
+- **Phase 1–4 UX roadmap**: Detailed UX wireframe text (history format, understanding card, loading messages, animation specs). These are aspirational design notes from a specific development phase that is now paused. The *intent* is valid; the *specifics* may change when UI work resumes.
+- **Backlog section** (reasoning replay): A high-level feature idea without implementation specification or priority. Historical UX thinking, not actionable engineering work.
+
+### Duplicated content
+
+- Phase 4 ("Mock Scenario Library") duplicates the fixtures table at the top of the file — same scenarios listed twice with different formatting.
+- "Deliberately Out of Scope" repeats the pause decision already documented in current-project-state section 6 and project-context.md.
+
+### Unclear ownership or status
+
+- The mock fixtures table has no owner and no associated ticket. It is a reference artifact from UX development, not an active task list.
+- None of the roadmap phases are linked to commits, PRs, or experiments. They represent design intent from a paused phase, not tracked work items.
+
+### Recommended document role: **Retain temporarily pending revision**
+
+### Evidence for recommendation
+
+- The mock fixtures table (≈20 lines) is directly useful when UI work resumes and would be harder to locate if moved to archive.
+- The UX roadmap content (≈370 lines) is largely aspirational design notes from a paused phase — not current guidance, not actionable backlog, not historical evidence of decision-making. It is deferred UX planning.
+- Moving the entire document to archive would make the mock fixtures harder to find during future UI work.
+- Archiving just the roadmap portion would require splitting the file (not permitted by constraints).
+- The best immediate action is to record its mixed role and leave it in place until a future experiment handles selective revision or archival of its contents.
+
+---
+
+## 4. Recommended Actions
+
+| Document | Action | Rationale |
+|---|---|---|
+| `docs/architectural-principles.md` | **Keep as task-specific reference** | Principles are neither purely current nor purely historical. Six are verified current; four are clear targets; three overlap with guardrails but add context. Valuable when resuming reasoning work; not needed by default. project-knowledge-inventory already classified it this way. No correction needed. |
+| `docs/backlog info.md` | **Retain temporarily pending revision** | Contains a useful mock fixtures table (UI reference) mixed with deferred UX planning notes (aspirational, untracked). Splitting the file or archiving parts requires revising content (constraints forbid this). Its dual role needs resolution when UI work resumes. project-knowledge-inventory already classified it this way. No correction needed. |
+
+Neither document qualifies for "archive as historical evidence" because both contain material with potential near-term utility (principles as reasoning targets; mock fixtures as UI reference). Neither qualifies for "keep as current guidance" because significant portions are aspirational or deferred.
+
+---
+
+## 5. Questions That Remain
+
+1. Should architectural-principles.md be updated to annotate each principle as [Current]/[Aspirational] rather than leaving this classification implicit? (Requires modifying the document — deferred.)
+2. Should backlog info.md's mock fixtures table be extracted into a separate file when UI work resumes, to avoid carrying 370 lines of UX planning alongside a 15-row reference? (Deferred to UI resumption.)
+3. Does any active code path depend on content from either document? (No — verified via implementation-verification cross-module traces showing zero dependencies on architectural-principles.md or backlog info.md by any source module.)
+
+---
+
+## Practical Routing Test
+
+**Scenario:** A future Claude session is about to work on UI mocks.
+
+**Answer:** Read **both** `architectural-principles.md` and `backlog info.md`.
+
+**Why:**
+- `backlog info.md` provides the mock fixtures table (15 scenarios with purposes) — the direct reference for building mock investigations.
+- `architectural-principles.md` provides context on how reasoning and UI should interact (P4: reasoning never communicates directly with UI; P6: presentation never interprets), which guards against accidentally introducing reasoning logic into UI mock development.
+
+**Sufficiency of three-document context:** Yes. `project-knowledge-inventory.md` identifies both files as task-specific references for their respective domains (principles for architecture, backlog fixtures for UX). `current-project-state.md` confirms UI is paused but workspace layout design intent remains documented. `document-role-review.md` confirms neither file should be loaded by default but each serves a distinct reference role when the specific task domain is active. Together they answer: what exists to load, why it matters, and how to use it without reading the full experiment log or archive.
+
+---
+
+## Return-to-Work Note
+
+The two deferred documents from Experiment 29 were reviewed because their current value was uncertain — neither could be confidently archived without understanding whether their content still matched verified implementation. `architectural-principles.md` was assigned the role of **task-specific reference**: six of fourteen principles are verified current against runtime, four are clear aspirational targets, three overlap with guardrails but add valuable context. It remains in `docs/`. `backlog info.md` was assigned **retain temporarily pending revision**: it mixes a useful mock fixtures table (15 scenarios) with deferred UX planning notes (370 lines of aspirational design). Both documents stay in place; neither moved to archive because both contain material with potential near-term utility when their respective work domains resume. Future sessions working on reasoning architecture should load architectural-principles.md as reference. Future sessions working on UI mocks should load backlog info.md for fixture references. Engine and UI experiments remain paused. **Branch:** `feature/user-workspace-ux-v0.7`. **First file to inspect when resuming:** `docs/current-project-state.md`, then consult the inventory for task-specific references.
+

docs/project-knowledge-inventory.md

@@ -96,6 +96,11 @@ Grouped by task domain. Only load the group relevant to your work.
 | `docs/02_Confidence_Engine_Product_Story.md` (31 lines) | The product story, problem, idea, how it works, commercial value | When defining new features or evaluating product fit |
 | `docs/04_Rob_Thinking_Model.md` (32 lines) | Rob's thinking model — the working pattern that inspired the engine | When questioning whether a feature adds real value or just architecture |
 
+### Knowledge management
+| Document | Purpose | Loaded When |
+|---|---|---|
+| `docs/document-role-review.md` (140 lines) | Classification of deferred documents; practical routing test for UI mock and reasoning tasks | When reviewing which documents to load; when a task involves architectural guidance or mock fixture reference |
+
 ### Testing and contracts
 | Document | Purpose | Loaded When |
 |---|---|---|
@@ -126,8 +131,8 @@ Documents or sections that are primarily historical evidence from past experimen
 ### Review Before Archive (may have future value; do not load by default now)
 | Document | Size | Why review before archive |
 |---|---|---|
-| `docs/architectural-principles.md` (306 lines) | medium | 14 architectural principles derived from experiments — may be needed when re-engaging with reasoning architecture |
-| `docs/backlog info.md` (390 lines) | large | Mock fixture backlog — useful if resuming UI development; verify content is current before archiving |
+| `docs/architectural-principles.md` (306 lines) | medium | 14 architectural principles from experiments. Experiment 30 confirmed: 6 current, 4 aspirational targets, 3 overlap guardrails but add context. Role: task-specific reference for reasoning architecture work. See `docs/document-role-review.md` §2. |
+| `docs/backlog info.md` (390 lines) | large | Mix of mock fixtures table (15 scenarios — useful when UI resumes) and deferred UX planning notes (aspirational, untracked). Role: retain temporarily pending revision. See `docs/document-role-review.md` §3. |
 
 ### Do Not Move or Delete (evidence of design evolution)
 These documents document the path from Phase 1 through Experiment 25B. Archiving them separately without review would lose the rationale behind later decisions.
@@ -185,4 +190,4 @@ None. The five questions were answered accurately from the minimum context set.
 
 ## Return-to-Work Note
 
-Engine experiments paused after Experiment 25B, which established scope-aware condition status classification — distinguishing direct evidence from relevant-but-different claims by checking subject, timeframe, and claim type. Present-state evidence does not settle future-feasibility conditions. The passive classifier layers remain isolated; no active integration yet. Knowledge-management experiments continue: five historical documents have been archived to `docs/archive/` per Experiment 29 (archive index at `docs/archive/README.md`). Nothing was deleted. Two candidates (`architectural-principles.md`, `backlog info.md`) were deliberately retained in `docs/` pending review. This inventory has been updated with archive paths and provenance notes. Branch: `feature/user-workspace-ux-v0.7`. First file to inspect when resuming: `.claude/project-context.md`, then Experiments 23–25B in `docs/design-evolution-log.md` (lines 1218–1520).
+Engine experiments paused after Experiment 25B, which established scope-aware condition status classification — distinguishing direct evidence from relevant-but-different claims by checking subject, timeframe, and claim type. Present-state evidence does not settle future-feasibility conditions. The passive classifier layers remain isolated; no active integration yet. Knowledge-management experiments continue: five historical documents have been archived to `docs/archive/` per Experiment 29; two deferred documents reviewed in Experiment 30 — architectural-principles.md assigned role "keep as task-specific reference," backlog info.md assigned role "retain temporarily pending revision." Neither moved to archive (both contain material with potential near-term utility). Document-role-review.md records all classifications and a practical routing test result. First file to inspect when resuming: `.claude/project-context.md`, then Experiments 23–25B in `docs/design-evolution-log.md` (lines 1218–1520).