experiment: verify current project state against implementation
This commit is contained in:
@@ -0,0 +1,110 @@
|
||||
# Current Implementation Verification
|
||||
|
||||
> Experiment 28 — Focused code inspection of `feature/user-workspace-ux-v0.7`.
|
||||
|
||||
## 1. Verification Method
|
||||
|
||||
Inspected the following runtime entry points and imports:
|
||||
|
||||
**API routes (entry points):**
|
||||
- `app/api/cases/start/route.js` → calls `startCase` from orchestrator;
|
||||
- `app/api/cases/update/route.js` → calls `updateCase` from orchestrator;
|
||||
- `app/api/analyse/route.js` → calls `analyseScenario` from analysis.js (reconstruction only).
|
||||
|
||||
**Orchestrator imports** (`lib/graph/orchestrator.js`, lines 6–32):
|
||||
- `analyseScenario` (reconstruction, not engine);
|
||||
- `buildInitialGraph`, `describeGraph` (graph builder);
|
||||
- `applyValidatedProposal`, `determineGraphBackedQuestion` (apply-proposal);
|
||||
- `assessInvestigationState` (imported, but result only placed in diagnostics field);
|
||||
- `buildReasoningState`, `formulateQuestion`, `formulateTieResolutionQuestion` (question-formulator);
|
||||
- `parseGraphUpdateProposal`;
|
||||
- `explainUnknownSelection`, `selectActiveUnknownCandidate`, `validateGraphReferences` (utils).
|
||||
|
||||
**Cross-module traces:**
|
||||
- `grep -R "selectBehaviour"` — no callers outside its own module;
|
||||
- `grep -R "assessDecisionConditionStatus\|scoreQuestionDecisionRelevance\|assessQuestionImportance"` — no callers outside decision-condition-status.js, question-decision-relevance.js, and question-importance.js respectively;
|
||||
- `import` statements in all JS files under lib/ and app/ were inspected for references to passive classifier modules.
|
||||
|
||||
Evidence is based on actual imports, call sites, and return-object placement found in source.
|
||||
|
||||
## 2. Active Capabilities
|
||||
|
||||
### 2a. Scenario Reconstruction (analyseScenario)
|
||||
- **Purpose:** LLM-based scenario analysis producing situation graph; first step of a new case.
|
||||
- **Implementation:** `lib/analysis.js` → calls provider, parses response, validates against Zod schemas.
|
||||
- **Evidence:** Called from `app/api/analyse/route.js` and imported by orchestrator's startCase flow via `buildInitialGraph`.
|
||||
|
||||
### 2b. Reasoning Graph Updates (startCase / updateCase)
|
||||
- **Purpose:** Builds initial situation graph from analysis; applies user answers to graph nodes, updates status/confidence/completeness, runs propagation.
|
||||
- **Implementation:** `lib/graph/orchestrator.js` — `startCase()` (line 376 calls `buildInitialGraph`, line 402 calls `determineGraphBackedQuestion`); `updateCaseWithDependencies()` (line 622 calls `applyValidatedProposal`).
|
||||
- **Evidence:** Orchestrator functions are called from `app/api/cases/start/route.js` and `app/api/cases/update/route.js`. `applyValidatedProposal` is the runtime caller for graph mutation; propagation, confidence cap, and completeness update happen within apply-proposal.js.
|
||||
|
||||
### 2c. Unknown Selection (atomicity + answerability)
|
||||
- **Purpose:** Selects the next unresolved node to investigate based on atomicity and answerability criteria.
|
||||
- **Implementation:** `selectActiveUnknownCandidate` in `lib/graph/utils.js`; called from orchestrator's updateCase flow via `determineGraphBackedQuestion`.
|
||||
- **Evidence:** Imported at line 30 of orchestrator.js; used in the active investigation turn cycle within `updateCaseWithDependencies()`.
|
||||
|
||||
### 2d. Question Formulation
|
||||
- **Purpose:** Generates a single user-facing question from the selected unknown node and reasoning pattern.
|
||||
- **Implementation:** `formulateQuestion`, `formulateTieResolutionQuestion` in `lib/graph/question-formulator.js`.
|
||||
- **Evidence:** Imported at lines 23–26 of orchestrator.js; called from `determineGraphBackedQuestion` within the active updateCase path.
|
||||
|
||||
### 2e. Investigation Turn Cycle Orchestration
|
||||
- **Purpose:** Coordinates the full turn: unknown selection → question formulation → user answer → graph update → propagation → next unknown.
|
||||
- **Implementation:** `lib/graph/orchestrator.js` — the complete `updateCaseWithDependencies()` function (line 581–919) and `startCase` flow (line 370–566).
|
||||
- **Evidence:** Both functions are exposed as public entry points and called from their respective API routes. This is the active runtime heart of the engine.
|
||||
|
||||
## 3. Passive or Isolated Capabilities
|
||||
|
||||
### 3a. Investigation-State Assessment
|
||||
- **Implementation:** `lib/assessment/investigation-state-assessor.js`.
|
||||
- **Called by:** `lib/graph/orchestrator.js` at lines 552, 904, 1013 (three call sites in startCase and updateCase).
|
||||
- **Where result goes:** Placed into the `assessment` field of the diagnostics object returned to the client. It is **not** used to control any engine decision or behaviour path.
|
||||
- **Classification: diagnostic_only.**
|
||||
|
||||
### 3b. Behaviour Selection
|
||||
- **Implementation:** `lib/behaviour-selection/behaviour-selector.js`.
|
||||
- **Called by:** None. No import or call found in any file under lib/ or app/.
|
||||
- **Why not active:** Entirely isolated — no caller exists anywhere in the repository.
|
||||
|
||||
### 3c. Question Importance Assessment
|
||||
- **Implementation:** `lib/graph/question-importance.js` (line 106: `assessQuestionImportance`).
|
||||
- **Called by:** None. No import found outside its own module.
|
||||
- **Why not active:** Isolated — not called by runtime, diagnostics, or any other module.
|
||||
|
||||
### 3d. Question Relevance to Decision Conditions
|
||||
- **Implementation:** `lib/graph/question-decision-relevance.js` (line 65: `assessQuestionRelevanceToDecision`).
|
||||
- **Called by:** None. No import found outside its own module.
|
||||
- **Why not active:** Isolated — same status as question-importance.js.
|
||||
|
||||
### 3e. Decision Condition Status Evaluation
|
||||
- **Implementation:** `lib/graph/decision-condition-status.js`. Exports `assessDecisionConditionStatus` (line 105). Imports and uses `assessEvidenceDirection` and `assessEvidenceConditionScope`.
|
||||
- **Called by:** None. No import found in any other module.
|
||||
- **Why not active:** Isolated at the file level — it exists as a self-contained module with no external callers.
|
||||
|
||||
### 3f. Evidence Direction Classification
|
||||
- **Implementation:** `lib/graph/evidence-direction.js` (line 134: `assessEvidenceDirection`).
|
||||
- **Called by:** Only from `decision-condition-status.js` (internal dependency). No external caller.
|
||||
- **Why not active:** Isolated — only consumed by decision-condition-status.js, which itself has no callers.
|
||||
|
||||
### 3g. Evidence Scope Detection
|
||||
- **Implementation:** `lib/graph/evidence-condition-scope.js` (line 100: `assessEvidenceConditionScope`).
|
||||
- **Called by:** Only from `decision-condition-status.js` (internal dependency). No external caller.
|
||||
- **Why not active:** Isolated — only consumed by decision-condition-status.js, which itself has no callers.
|
||||
|
||||
### 3h. Scope-Aware Condition Status (composite)
|
||||
- **Implementation:** Same as 3e — the composite `assessDecisionConditionStatus` combines evidence direction and scope detection.
|
||||
- **Classification: isolated.** No external caller.
|
||||
|
||||
## 4. Differences From the Current-State Document
|
||||
|
||||
**None found.** The current-state document's classification of active capabilities (reconstruction, graph updates, unknown selection, question formulation, turn orchestration) matches what the code shows as genuinely active in the runtime path. Its classification of passive experimental capabilities (investigation-state assessment, behaviour selection, decision-condition status, question-to-condition relevance, evidence direction, evidence scope, scope-aware condition status) also matches — all remain either diagnostic_only or isolated with no external callers.
|
||||
|
||||
## 5. Unresolved From Code Inspection
|
||||
|
||||
- The runtime output shape of `assessInvestigationState` and which assessment values it produces cannot be fully assessed without reading the assessor's internal logic (per constraints). However, its **classification** as diagnostic_only is established by tracing: imported → called at 3 sites → result placed in a diagnostics field → no if/switch/ternary branches check its output.
|
||||
- Whether `startCase` and `updateCase` API routes are the only callers of the orchestrator cannot be confirmed without searching outside this repository (e.g., external clients). The assessment is limited to code within the repo.
|
||||
|
||||
## Verification Marker
|
||||
|
||||
Implementation status last checked against source: Experiment 28.
|
||||
@@ -100,5 +100,14 @@ 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 28)
|
||||
|
||||
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 work remains active. 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
|
||||
|
||||
Implementation status last checked against source: Experiment 28.
|
||||
The current-state document was verified as accurate by focused code inspection of API routes, orchestrator imports/calls, and cross-module traces for all passive classifiers. No corrections were required.
|
||||
|
||||
**Branch:** `feature/user-workspace-ux-v0.7`
|
||||
**Latest known commit before this experiment:** `4661b8e` (experiment: inventory project knowledge and context needs)
|
||||
|
||||
@@ -1638,7 +1638,68 @@ Once the information architecture and visual hierarchy stabilise we will investi
|
||||
|
||||
This should be treated as a future UX experiment rather than an accessibility feature.
|
||||
|
||||
## Backlog — Investigation Narrative (Potential Future Work)
|
||||
## Experiment 28 — Verify Current Project State Against Implementation
|
||||
|
||||
**Status:** Pending Rob's review
|
||||
|
||||
### Hypothesis
|
||||
|
||||
A focused code inspection can verify or correct the current-state document without requiring a fresh session to read the full experiment log. If the document is accurate, it can safely become the normal project entry point.
|
||||
|
||||
### Source Areas Inspected
|
||||
|
||||
- `docs/current-project-state.md` — entire file;
|
||||
- `.claude/architecture-guardrails.md` — entire file;
|
||||
- `docs/project-knowledge-inventory.md` — Current Working Context and Task-Specific References sections;
|
||||
- `app/api/*/route.js` — all API entry points (analyse, cases/start, cases/update, health);
|
||||
- `lib/graph/orchestrator.js` — imports (lines 6–32) and runtime calls at lines 376, 402, 552, 581, 622, 826, 904, 1013;
|
||||
- `lib/graph/*.js` — grep for imports of passive classifier modules (decision-condition-status, evidence-direction, evidence-condition-scope, question-decision-relevance, question-importance);
|
||||
- `lib/behaviour-selection/behaviour-selector.js` — cross-module import check;
|
||||
- `lib/assessment/investigation-state-assessor.js` — caller trace in orchestrator.
|
||||
|
||||
### Active / Passive Findings
|
||||
|
||||
**Active capabilities confirmed:**
|
||||
1. Scenario reconstruction (analyseScenario) — API entry at app/api/analyse/route.js → lib/analysis.js.
|
||||
2. Reasoning graph updates (startCase / updateCase) — API entries at app/api/cases/{start,update}/route.js → orchestrator.js → apply-proposal.js. Propagation, confidence cap, completeness calculated in apply-proposal.
|
||||
3. Unknown selection (atomicity + answerability) — selectActiveUnknownCandidate imported and called from orchestrator's determineGraphBackedQuestion within the active updateCase path.
|
||||
4. Question formulation — formulateQuestion / formulateTieResolutionQuestion imported and called from the active turn cycle.
|
||||
5. Turn orchestration — orchestrator.js updateCaseWithDependencies() is the active engine heart, coordinating unknown→question→answer→graph-update→propagation→next-unknown.
|
||||
|
||||
**Passive or isolated capabilities confirmed:**
|
||||
1. Investigation-state assessment (assessInvestigationState) — called at 3 sites in orchestrator but result only placed into a diagnostics field; not used for any control-flow decision. Classification: **diagnostic_only**.
|
||||
2. Behaviour selection (selectBehaviour) — exported from behaviour-selector.js; no callers anywhere in the repo. Classification: **isolated**.
|
||||
3. Question importance, question relevance to decision, evidence direction, evidence scope, scope-aware condition status — each exists as a standalone module or file with zero external callers. Evidence direction and scope are imported only by decision-condition-status.js, which itself has no callers.
|
||||
|
||||
### Corrections Made
|
||||
|
||||
None. The current-state document's active/passive classification is accurate as-is. Added verification marker to docs/current-project-state.md.
|
||||
|
||||
### Practical Context-Test Result
|
||||
|
||||
**Task:** A developer proposes connecting Behaviour Selection directly to the next user-facing response. Is it active today? What boundary exists? Which files would need inspection before future integration?
|
||||
|
||||
**Briefing:**
|
||||
1. **Active today?** No. `selectBehaviour` is exported from `lib/behaviour-selection/behaviour-selector.js` but has zero callers anywhere in the repository. It is not active, diagnostic, or accessible through any API.
|
||||
2. **Current boundary:** Behaviour Selection and Investigation-State Assessment exist as separate modules that were never wired into the orchestrator's turn cycle. The orchestrator returns an `assessment` field to clients but does not pass assessment results into its own decision logic. There is no data path from state assessment → behaviour selection → question/response.
|
||||
3. **Files to inspect before integration:** `lib/graph/orchestrator.js` (where the insertion point would be — between unknown selection and question formulation, or after propagation); `lib/assessment/investigation-state-assessor.js` (to understand what the assessment contract outputs); `lib/behaviour-selection/behaviour-selector.js` (to understand what behaviours it can produce); `docs/investigation-state-assessment-contract.md` and `docs/behaviour-selection.md` for the documented interfaces; `app/api/cases/update/route.js` to determine whether behaviour output would appear in the API response or remain internal.
|
||||
4. **Context sufficient?** Yes — the three-file set (current-project-state, verification file, guardrails) plus targeted code inspection of the modules above provides sufficient context for a designer to assess integration scope without reopening the full history.
|
||||
5. **Verdict:** Integration is feasible as a future experiment. The primary risk is that behaviour selection has no documented input contract from the assessment layer — these were built in parallel without an agreed handoff shape.
|
||||
|
||||
### Unresolved Questions
|
||||
|
||||
- Whether the assessment output from `assessInvestigationState` matches the documented `investigation-state-assessment-contract.md` (requires reading the assessor's internal logic, excluded per constraints).
|
||||
- Whether external API clients (not in this repo) call the orchestrator directly, bypassing the route files.
|
||||
- The exact integration sequence: should behaviour selection read from assessment output or from the graph state directly?
|
||||
|
||||
### Return-to-Work Note
|
||||
|
||||
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 work remains active. 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 `.claude/architecture-guardrails.md` before any code changes, then `lib/graph/orchestrator.js` for engine-resumption work.
|
||||
|
||||
Branch: feature/user-workspace-ux-v0.7
|
||||
Commit: 61c8a3a
|
||||
|
||||
|
||||
|
||||
These are observations, not implementation tasks.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user