added claude context files

2026-08-03 15:51:46 +01:00
parent 44aad69e12
commit e2960853ba
5 changed files with 415 additions and 0 deletions
@@ -0,0 +1,77 @@
 # Architecture Guardrails
 ## Hard boundary for UX tasks
 When a task is described as UI, UX, layout, styling, loading feedback or
 presentation work, do not modify:
 - reasoning algorithms;
 - unknown selection;
 - reasoning-pattern selection;
 - question formulation;
 - atomicity or answerability assessment;
 - graph mutation;
 - graph schemas;
 - API request or response contracts;
 - reconstruction prompts;
 - provider configuration;
 - confidence propagation;
 - compatibility validation.
 If a UX request appears to require one of those changes, stop and report the
 dependency rather than changing it silently.
 ## Reasoning invariants
 Preserve these invariants:
 - The LLM proposes information; deterministic code owns graph mutation.
 - Every user-facing question comes from an explicit unresolved graph node.
 - Questions contain one primary concept and seek one coherent answer.
 - Unknowns must be atomic or decomposed.
 - Atomic wording alone is insufficient; a selected unknown must be independently
  answerable.
 - Question family must match the active reasoning pattern.
 - Active investigation nodes must be compatible with the reasoning pattern.
 - Relationship classification cannot outrun comparability assessment.
 - Ambiguity remains explicit rather than being resolved alphabetically.
 - Parent unknowns do not resolve before their completion rule is satisfied.
 - Confidence must not outrun evidence or completeness.
 - Duplicate evidence must not increase confidence.
 - Conflicting evidence caps conclusion confidence.
 - A successful update must rerun deterministic next-question selection when
  eligible unknowns remain.
 - No question is preferable to an unjustified question.
 ## Current architecture, simplified
 Scenario
 → reconstruction
 → situation graph
 → unknown selection
 → atomicity
 → answerability
 → reasoning pattern
 → investigation strategy
 → question family
 → question formulation
 → complexity validation
 → user answer
 → proposed graph update
 → deterministic validation/application
 → propagation
 → confidence/completeness update
 → next unknown
 ## Compatibility discipline
 Do not expand schemas merely because a model emits a synonym.
 Prefer:
 1. identify the source;
 2. determine whether it is a synonym;
 3. normalise deterministically when justified;
 4. retain strict validation.
 Do not weaken validation globally to fix a single malformed response.
@@ -0,0 +1,74 @@
 # Project Context
 ## What the Confidence Engine is
 The Confidence Engine is a structured reasoning tool intended to help people
 decide whether they have enough justified confidence to act.
 It does not simply answer the user's original question.
 It:
 1. reconstructs the situation;
 2. separates observations, assumptions, relationships and unknowns;
 3. creates a structured reasoning graph;
 4. selects the most useful unresolved uncertainty;
 5. asks one simple question;
 6. updates the graph from the answer;
 7. repeats until action is justified or the remaining uncertainty is clear.
 A chatbot remembers the conversation.
 The Confidence Engine preserves the state of the reasoning.
 ## Product direction
 The eventual product should feel like a calm, capable investigator helping the
 user think one step at a time.
 The user should not need to understand:
 - graph theory;
 - node IDs;
 - internal enums;
 - schemas;
 - prompt versions;
 - proposal validation;
 - model-provider details.
 Those remain available through developer/debug views.
 ## Core product promise
 The engine should help a user reach one of these states:
 - I have enough justified confidence to act.
 - I do not yet have enough confidence, but I know what to investigate next.
 - I have discovered that my original question needs reframing.
 ## Current development stage
 The deterministic reasoning architecture reached a stable alpha checkpoint.
 Current work is primarily improving:
 - usability;
 - presentation;
 - loading feedback;
 - plain-language explanations;
 - separation of user and developer views.
 Do not resume broad reasoning architecture work unless a repeated observed
 failure clearly requires it.
 ## Important philosophy
 Complicated situations are made from smaller parts.
 Each part may influence the whole, but parts do not necessarily carry equal
 weight.
 Previous cases may suggest where to investigate, but they must never determine
 the outcome of a new case.
 Every case begins with no accepted evidence from previous cases.
@@ -0,0 +1,137 @@
 # UX Guidelines
 ## Main principle
 The user should see the next useful step clearly.
 The system may retain considerable complexity underneath, but the primary
 workspace should remain calm and understandable.
 ## Main user view
 Prioritise:
 1. Your situation
 2. Current understanding
 3. What we are working out
 4. Why it matters
 5. Next question
 6. Answer field
 7. Reasoning progress
 ## Developer view
 Keep technical details behind a collapsed `Developer details` disclosure.
 This may contain:
 - complete situation graph;
 - graph counts;
 - nodes and edges;
 - affected and resolved nodes;
 - diagnostics;
 - proposal details;
 - raw JSON;
 - prompt and model details;
 - technical confidence data.
 Do not remove the developer view. It remains important while the product is
 being tested.
 ## Language
 Use plain language.
 Prefer:
 - `areas that still need investigation`
 - `what we are working out`
 - `why this matters`
 - `what we understand so far`
 - `next question`
 Avoid in the main view:
 - unknown nodes;
 - unresolved candidates;
 - activeUnknownNodeId;
 - graph references;
 - proposal compatibility;
 - candidate count;
 - internal enum values;
 - raw IDs.
 Never display an unexplained count such as:
 `3 remaining`
 Explain what the count represents, or omit it.
 Do not imply that one unresolved graph node always equals one remaining user
 question.
 ## Loading experience
 Analysis and update requests can take around a minute with the current local
 model.
 A disabled button is not sufficient feedback.
 Show a visible processing card immediately.
 Recommended initial-analysis messages:
 - 0–10 seconds: `Reading your situation`
 - 10–25 seconds: `Building a structured understanding`
 - 25–45 seconds: `Identifying what is known and still unclear`
 - 45+ seconds: `Selecting the next useful question`
 Recommended update messages:
 - 0–10 seconds: `Considering your answer`
 - 10–25 seconds: `Updating the situation`
 - 25–45 seconds: `Checking what changed`
 - 45+ seconds: `Choosing the next question`
 These messages are time-based reassurance only.
 Do not claim that a backend stage has completed unless the backend explicitly
 reports it.
 Show elapsed time.
 Do not show fake progress percentages.
 Disable duplicate submission while a request is active.
 ## Visual character
 Aim for:
 - calm;
 - professional;
 - spacious;
 - accessible;
 - suitable for business, consultancy and government users.
 Prefer:
 - clear hierarchy;
 - restrained colour;
 - generous whitespace;
 - readable line lengths;
 - consistent cards;
 - accessible contrast;
 - responsive layouts.
 Avoid:
 - visual clutter;
 - excessive badges;
 - neon colour;
 - unnecessary gradients;
 - glassmorphism;
 - distracting animation;
 - dashboard-style density.
 The next question should be the strongest visual element.
@@ -0,0 +1,83 @@
 # Claude Code Working Rules
 ## Mandatory command constraints
 These rules exist because previous long shell commands and streamed responses
 caused tool failures.
 - Do not use heredocs.
 - Do not use long `node -e` commands.
 - Do not use long `python -c` commands.
 - If helper code is needed, create a small script file and run it.
 - Keep shell commands short and readable.
 - Break complex work into several commands.
 - Write large outputs to files instead of printing them.
 - Do not print full JSON responses or graph objects.
 - Do not paste complete large files into chat.
 - Prefer: tool → file → concise summary.
 - Keep final reports concise.
 - Do not narrate every implementation step.
 ## Change discipline
 Before editing:
 1. state the current branch;
 2. inspect `git status`;
 3. identify the relevant files;
 4. explain the smallest intended change.
 Work on one component or concern at a time.
 Do not combine unrelated cleanup with the requested task.
 Do not reformat unrelated files.
 Do not modify production reasoning code during UX tasks.
 ## Testing discipline
 Use focused tests.
 Do not run the full test suite unless requested or genuinely necessary.
 Do not call Ollama in unit tests.
 Do not run live multi-scenario evaluations for ordinary UI changes.
 Do not run Playwright unless the task specifically requires it.
 Do not weaken existing reasoning tests to make UI changes pass.
 ## Git discipline
 Before committing:
 - inspect the diff;
 - confirm no secrets;
 - confirm no internal IP addresses;
 - confirm no raw provider responses;
 - confirm no screenshots;
 - confirm no temporary scripts;
 - confirm no generated test outputs;
 - confirm only intended files changed.
 Use a focused commit message.
 Do not merge or tag unless explicitly requested.
 ## Response discipline
 At the end of a task, normally report only:
 - branch;
 - commit hash, when committed;
 - files changed;
 - behaviour changed;
 - tests;
 - lint/build;
 - manual result, if performed;
 - remaining limitation;
 - git status.
 Stop after reporting. Do not begin the next task automatically.
@@ -0,0 +1,44 @@
 # Confidence Engine
 Read these project instructions before making changes:
 - @.claude/project-context.md
 - @.claude/architecture-guardrails.md
 - @.claude/ux-guidelines.md
 - @.claude/working-rules.md
 ## Current working principle
 The Confidence Engine helps a person move from uncertainty towards justified
 confidence by asking one simple, useful question at a time.
 The graph preserves the state of the reasoning. The conversation is the primary
 user experience.
 ## Before changing anything
 1. Inspect the current branch and working tree.
 2. Read the relevant implementation and tests.
 3. Identify whether the request concerns:
   - reasoning behaviour;
   - API/data contracts;
   - or presentation only.
 4. Respect the boundaries in the imported instructions.
 5. Make the smallest change that satisfies the task.
 Do not assume an architectural redesign is wanted.
 ## Standard validation
 For UI-only work, normally run:
 ```bash
 npm test -- --run tests/ui/scenario-form.test.jsx
 npm run lint
 npm run build
 ```
 Run additional focused tests only when relevant files are affected.
 Do not run Ollama, Playwright, the full test suite, or evaluator suites unless the
 task explicitly requires them.