Safety Testing

Safety Testing

This page defines how to validate safety-related behavior in SoulMap AI while preserving existing safeguards and behavioral invariants.

Core Principle

Safety is an enforced runtime boundary, not merely a documentation convention.

Safety-related changes must preserve established protections, remain consistent with canonical knowledge, and be supported by relevant tests and review evidence.

A passing test suite does not justify weakening an existing safeguard without an explicit, evidence-based requirement.

1. Scope

Safety testing may cover:

• Crisis detection and classification.
• Safety-related routing and response handling.
• False-positive and false-negative regression cases.
• Integration with shared safety enforcement.
• Boundary cases involving ambiguous or incomplete user input.
• Preservation of protected safety configuration and invariants.

The exact scope depends on the files and behavior affected by a change.

2. Protected Components

Treat existing safety mechanisms as protected architectural components.

Before making a safety-related change:

1. Inspect the current implementation and its tests.
2. Identify protected files, constants, and behavioral invariants.
3. Establish the intended change and the evidence supporting it.
4. Determine which existing tests must remain valid.
5. Avoid unrelated refactoring or structural changes.

Do not modify protected safety components merely to achieve naming symmetry, reduce duplication without evidence, or make the repository tree appear more uniform.

3. Test Categories

Crisis Detection

Verify that known crisis-related inputs continue to trigger the intended detection and handling paths.

Test relevant cases from the existing evaluation suite. Do not assume that a keyword match alone establishes the complete meaning or risk level of a message.

Negative Cases

Verify that ordinary reflective conversations do not incorrectly trigger crisis handling when the relevant safety conditions are absent.

Negative cases are important because overly broad detection can interfere with ordinary user conversations.

Boundary Cases

Test ambiguous language, negation, quoted statements, contextual references, and other cases supported by the current detector and evaluation design.

Use evidence from existing tests and documented behavior to determine the expected outcome. Do not invent new safety semantics simply to make a test more comprehensive.

Integration Cases

Verify that detection results are passed through the intended routing and shared safety mechanisms.

A detector passing its unit tests does not prove that downstream safety enforcement is functioning correctly.

Regression Cases

Preserve tests for previously identified safety defects and important behavioral invariants.

Do not remove or weaken a regression test merely because it fails after a proposed change. Investigate whether the implementation has violated the existing contract.

4. Safe Change Workflow

1. Identify the exact safety behavior being changed.
2. Inspect the relevant implementation, canonical knowledge, and tests.
3. Record the expected behavior before editing.
4. Make the smallest change that satisfies the justified requirement.
5. Run focused safety tests.
6. Run related integration and regression tests.
7. Review the diff for changes to protected components and invariants.
8. Report test results, unresolved failures, and any unverified assumptions.

If a change has no demonstrated safety requirement, do not modify protected behavior for cosmetic consistency.

5. Knowledge and Runtime Responsibilities

Canonical Markdown may define behavioral doctrine, while Python implements detection, routing, validation, and enforcement.

This division does not mean that every safety rule must be moved into Markdown.

Some safety mechanisms, technical configuration, and enforcement logic are intentionally implemented in protected Python components. Preserve those ownership decisions unless an explicit architectural decision establishes otherwise.

Do not create a second, conflicting safety policy in a framework.

6. Failure Handling

When a safety test fails:

• Identify the exact failing case and expected behavior.
• Determine whether the change introduced a regression.
• Inspect the relevant source, test fixture, and execution path.
• Preserve the failure evidence.
• Fix the underlying issue within the authorized scope.
• Rerun the relevant checks and verify their results.

Do not suppress a failing test, remove a safeguard, or weaken an assertion simply to obtain a passing CI result.

If the expected behavior is genuinely unclear, resolve the contract before changing the test.

7. Validation

Use the commands documented by the current repository configuration.

Common project checks include:

uv run soulmap format
uv run soulmap lint
uv run soulmap test -n auto -q

Run the relevant targeted safety and response-evaluation commands when available.

These examples are not a complete list of safety checks. Confirm the actual evaluation commands and required CI checks from the current repository before relying on them.

Do not report a check as passing unless it was executed and the result was verified.

8. Review Checklist

Before submitting a safety-related change, verify:

• The intended behavior and justification are documented.
• Protected safety components have not been changed without authorization.
• Existing crisis-detection behavior and safety invariants are preserved.
• Relevant positive, negative, boundary, and regression cases are covered.
• Shared safety enforcement has not been bypassed.
• No unrelated refactoring has been introduced.
• Relevant tests and audits have been executed.
• Failures and remaining uncertainties are reported accurately.

9. Definition of Done

A safety-related change is ready for review when the intended behavior is explicit, the change is limited to its justified scope, relevant safety and regression checks have been verified, and the diff preserves existing architectural boundaries.

Passing tests are necessary evidence, not permission to weaken established safeguards.

Related Documentation

• docs/engineering/knowledge-architecture.md
• docs/engineering/library-vs-framework.md
• docs/engineering/repo-contract.md
• SOULMAP.md
• README.md