retestkit 1.4.1

package/openspec/changes/rename-package-to-retest/proposal.md

@@ -0,0 +1,52 @@
+# Proposal: Rename Package to Retest
+
+## Why
+
+The current naming (`testing-mcp`, `webtest_*` tools, `webtest://` resources) is verbose and inconsistent. A unified "retest" brand simplifies the user experience, makes the CLI and tool names more memorable, and establishes a clear product identity.
+
+## What Changes
+
+- **BREAKING**: Rename npm package from `@jan-beranek/testing-mcp` to `@jan-beranek/retest`
+- **BREAKING**: Reset version to `0.0.1` (fresh start for the new brand)
+- **BREAKING**: Rename all tool prefixes from `webtest_*` to `retest_*`
+- **BREAKING**: Rename all prompt names from `webtest-*` to `retest-*`
+- **BREAKING**: Rename resource URI scheme from `webtest://` to `retest://`
+- **BREAKING**: Rename environment variable from `WEBTEST_WORKSPACE_DIR` to `RETEST_WORKSPACE_DIR`
+- **BREAKING**: Rename system prefix token from `[WEBTEST-SYSTEM]:` to `[RETEST-SYSTEM]:`
+- Rename source directory from `src/tools/webtest/` to `src/tools/retest/`
+- Rename prompt template files from `webtest-*.md` to `retest-*.md`
+- Rename default workspace directory from `webtest-workspaces` to `retest-workspaces`
+- Update CLI binary name from `testing-mcp` to `retest`
+- Update MCP server name to `retest`
+- Rename all OpenSpec specs from `webtest-*` to `retest-*`
+
+## Impact
+
+### Specifications Affected
+- `webtest-tools` → `retest-tools` (all tool definitions)
+- `webtest-prompts` → `retest-prompts` (all prompt definitions)
+- `webtest-resources` → `retest-resources` (URI scheme and resource patterns)
+- `webtest-sampling` → `retest-sampling` (system prefix token)
+- `webtest-logging` → `retest-logging` (logger name)
+- `webtest-lifecycle` → `retest-lifecycle` (workspace directory)
+- `mcp-server-core` (package name, binary, server name)
+
+### Code Files Affected
+- `package.json` - name, version, bin
+- `src/server.ts` - server name, imports
+- `src/tools/webtest/` → `src/tools/retest/` - directory and all files
+- `src/tools/index.ts` - import path
+- `src/prompts/index.ts` - function names, prompt names
+- `src/prompts/templates/mcp/webtest-*.md` → `retest-*.md`
+- `src/prompts/templates/sampling/system-prefix.md`
+- `src/resources/index.ts` - URI scheme
+- `src/config.ts` - environment variable
+- `src/schemas/config.ts` - default directory
+- `src/security/index.ts` - system prefix regex
+- `src/sampling/index.ts` - system prefix references
+- `src/workspace/types.ts` - comments
+- `src/logger.ts` - logger name
+- `src/test-utils/mock-context.ts` - test directory
+- All test files with hardcoded tool/prompt names
+- `README.md` - documentation
+- `.gitignore` - workspace directory pattern

package/openspec/changes/rename-package-to-retest/specs/mcp-server-core/spec.md

@@ -0,0 +1,53 @@
+# mcp-server-core Specification Delta
+
+## MODIFIED Requirements
+
+### Requirement: MCP Server Initialization
+
+The system SHALL provide an MCP server that initializes with proper identification and connects to the configured transport.
+
+#### Scenario: Server starts with stdio transport
+
+- **GIVEN** the environment variable `TRANSPORT` is set to `stdio` or not set
+- **WHEN** the server entry point is executed
+- **THEN** it SHALL identify itself with name "retest" and version from package.json
+- **AND** it SHALL connect to stdio transport for communication
+
+#### Scenario: Server starts with HTTP transport
+
+- **GIVEN** the environment variable `TRANSPORT` is set to `http`
+- **AND** the environment variable `PORT` is set to a valid port number
+- **WHEN** the server entry point is executed
+- **THEN** it SHALL start a Streamable HTTP server on the specified port
+- **AND** it SHALL accept MCP protocol connections over HTTP
+
+#### Scenario: Server handles graceful shutdown
+
+- **GIVEN** the server is running
+- **WHEN** the process receives SIGINT or SIGTERM
+- **THEN** the server SHALL disconnect gracefully
+- **AND** the process SHALL exit with code 0
+
+### Requirement: Project Build Configuration
+
+The system SHALL be buildable to JavaScript for production deployment using TypeScript compiler.
+
+#### Scenario: Project builds successfully
+
+- **GIVEN** the source code is valid TypeScript
+- **WHEN** `npm run build` is executed
+- **THEN** compiled JavaScript SHALL be output to `dist/` directory
+- **AND** the build SHALL complete without errors
+
+#### Scenario: Development mode runs with hot-reload
+
+- **GIVEN** the development dependencies are installed
+- **WHEN** `npm run dev` is executed
+- **THEN** the server SHALL start with file watching enabled
+- **AND** changes to source files SHALL trigger automatic restart
+
+#### Scenario: Package is executable as CLI
+
+- **GIVEN** the project is built
+- **WHEN** `npx @jan-beranek/retest` is executed (or the bin entry is invoked)
+- **THEN** the server SHALL start with default configuration

package/openspec/changes/rename-package-to-retest/specs/retest-lifecycle/spec.md

@@ -0,0 +1,68 @@
+# retest-lifecycle Specification Delta
+
+## RENAMED Requirements
+
+- **FROM**: `webtest-lifecycle` specification
+- **TO**: `retest-lifecycle` specification
+
+## MODIFIED Requirements
+
+### Requirement: Client Capability Negotiation
+
+The system SHALL query and record client capabilities during initialization and adapt behavior accordingly.
+
+#### Scenario: Server records sampling capability
+
+- **GIVEN** a client connects with `capabilities.sampling` present
+- **WHEN** initialization completes
+- **THEN** the server SHALL record that sampling is available
+- **AND** retest tools SHALL use `sampling/createMessage` for LLM reasoning
+
+#### Scenario: Server records elicitation capability
+
+- **GIVEN** a client connects with `capabilities.elicitation` present
+- **WHEN** initialization completes
+- **THEN** the server SHALL record that elicitation is available
+- **AND** retest tools SHALL use `elicitation/create` for user decisions
+
+#### Scenario: Server records logging capability
+
+- **GIVEN** a client connects with `capabilities.logging` present
+- **WHEN** initialization completes
+- **THEN** the server SHALL record that logging notifications are supported
+- **AND** the logger SHALL emit `notifications/message` to the client
+
+#### Scenario: Server records progress capability
+
+- **GIVEN** a client connects with MCP progress support
+- **WHEN** initialization completes
+- **THEN** the server SHALL record that progress notifications are supported
+- **AND** long-running tools SHALL emit `notifications/progress`
+
+#### Scenario: Server records resources listChanged capability
+
+- **GIVEN** a client connects with `capabilities.resources.listChanged` present
+- **WHEN** initialization completes
+- **THEN** the server SHALL record that resource list change notifications are supported
+- **AND** resource creation SHALL emit `notifications/resources/list_changed`
+
+#### Scenario: Server records resources subscribe capability
+
+- **GIVEN** a client connects with `capabilities.resources.subscribe` present
+- **WHEN** initialization completes
+- **THEN** the server SHALL record that resource subscriptions are supported
+- **AND** resource updates SHALL emit `notifications/resources/updated` to subscribers
+
+#### Scenario: Fallback when sampling not supported
+
+- **GIVEN** a client connects without `capabilities.sampling`
+- **WHEN** a retest tool requires LLM reasoning
+- **THEN** the tool SHALL return a prompt resource for manual execution
+- **AND** the tool output SHALL include `needsManualInput: true`
+
+#### Scenario: Fallback when elicitation not supported
+
+- **GIVEN** a client connects without `capabilities.elicitation`
+- **WHEN** a retest tool needs user decision
+- **THEN** the tool SHALL include questions in its output
+- **AND** the tool output SHALL include `needsInput: true` with question details

package/openspec/changes/rename-package-to-retest/specs/retest-logging/spec.md

@@ -0,0 +1,35 @@
+# retest-logging Specification Delta
+
+## RENAMED Requirements
+
+- **FROM**: `webtest-logging` specification
+- **TO**: `retest-logging` specification
+
+## MODIFIED Requirements
+
+### Requirement: MCP Logging Notifications
+
+The system SHALL emit structured logs as MCP logging notifications when the client supports it.
+
+#### Scenario: Log emitted as MCP notification
+
+- **GIVEN** the client supports MCP logging (`capabilities.logging` present)
+- **WHEN** a log event occurs
+- **THEN** it SHALL emit `notifications/message` with:
+  - `level`: one of "debug", "info", "warning", "error"
+  - `logger`: "retest"
+  - `data`: structured log payload
+
+#### Scenario: Fallback to stderr when logging unsupported
+
+- **GIVEN** the client does not support MCP logging
+- **WHEN** a log event occurs
+- **THEN** it SHALL write to stderr as JSON
+- **AND** not attempt MCP notification
+
+#### Scenario: Log level is respected
+
+- **GIVEN** client log level is set to "warning"
+- **WHEN** an "info" level log is generated
+- **THEN** it SHALL NOT be emitted
+- **AND** "warning" and "error" logs SHALL be emitted

package/openspec/changes/rename-package-to-retest/specs/retest-prompts/spec.md

@@ -0,0 +1,159 @@
+# retest-prompts Specification Delta
+
+## RENAMED Requirements
+
+- **FROM**: `webtest-prompts` specification
+- **TO**: `retest-prompts` specification
+
+## MODIFIED Requirements
+
+### Requirement: Prompt Template Registration
+
+The system SHALL register prompt templates with the MCP server for client discovery.
+
+#### Scenario: Prompts are listed on prompts/list
+
+- **GIVEN** a client calls `prompts/list`
+- **WHEN** the response is returned
+- **THEN** it SHALL include prompts:
+  - `retest-start` (Start web testing analysis)
+  - `retest-crawl` (Crawl to satisfy focus)
+  - `retest-discover` (Discover features and flows)
+  - `retest-generate-tests` (Generate test cases)
+  - `retest-run-test` (Run a test case)
+  - `retest-full-workflow` (Full testing workflow)
+
+### Requirement: Start Analysis Prompt
+
+The system SHALL provide a prompt template to initiate a web testing analysis.
+
+#### Scenario: Start analysis prompt is invoked
+
+- **GIVEN** client invokes `prompts/get` with name `retest-start`
+- **WHEN** the prompt is returned
+- **THEN** it SHALL include:
+  - Description: "Start a new web testing analysis for a URL"
+  - Arguments: `url` (required), `focus` (required), `maxSteps` (optional), `maxPages` (optional)
+
+#### Scenario: Start analysis prompt generates tool call
+
+- **GIVEN** client invokes the prompt with arguments
+- **WHEN** the prompt messages are returned
+- **THEN** it SHALL include a user message instructing to call `retest_init`
+- **AND** include the provided arguments in the instruction
+
+### Requirement: Crawl Prompt
+
+The system SHALL provide a prompt template to start or continue a crawl.
+
+#### Scenario: Crawl prompt is invoked
+
+- **GIVEN** client invokes `prompts/get` with name `retest-crawl`
+- **WHEN** the prompt is returned
+- **THEN** it SHALL include:
+  - Description: "Crawl a web application to explore and achieve a goal"
+  - Arguments: `analysisId` (required), `goal` (optional), `strategy` (optional)
+
+#### Scenario: Crawl prompt uses analysis goal by default
+
+- **GIVEN** client invokes crawl prompt with only `analysisId`
+- **WHEN** the prompt messages are returned
+- **THEN** it SHALL instruct to use the original focus as the crawl goal
+
+### Requirement: Discover Prompt
+
+The system SHALL provide a prompt template to discover features and flows.
+
+#### Scenario: Discover prompt is invoked
+
+- **GIVEN** client invokes `prompts/get` with name `retest-discover`
+- **WHEN** the prompt is returned
+- **THEN** it SHALL include:
+  - Description: "Discover features and flows from crawled data"
+  - Arguments: `analysisId` (required), `crawlId` (optional)
+
+#### Scenario: Discover prompt lists available crawls
+
+- **GIVEN** client invokes discover prompt with only `analysisId`
+- **WHEN** the prompt messages are returned
+- **THEN** it SHALL include context about available crawls for that analysis
+
+### Requirement: Generate Tests Prompt
+
+The system SHALL provide a prompt template to generate test cases.
+
+#### Scenario: Generate tests prompt is invoked
+
+- **GIVEN** client invokes `prompts/get` with name `retest-generate-tests`
+- **WHEN** the prompt is returned
+- **THEN** it SHALL include:
+  - Description: "Generate test cases from application analysis"
+  - Arguments: `analysisId` (required), `count` (optional), `types` (optional)
+
+#### Scenario: Generate tests prompt offers strategy options
+
+- **GIVEN** client invokes generate tests prompt
+- **WHEN** the prompt messages are returned
+- **THEN** it SHALL mention available test types: "smoke", "negative", "boundary", "integration"
+
+### Requirement: Run Test Prompt
+
+The system SHALL provide a prompt template to execute a test case.
+
+#### Scenario: Run test prompt is invoked
+
+- **GIVEN** client invokes `prompts/get` with name `retest-run-test`
+- **WHEN** the prompt is returned
+- **THEN** it SHALL include:
+  - Description: "Execute a test case and capture results"
+  - Arguments: `analysisId` (required), `testCaseId` (required)
+
+#### Scenario: Run test prompt lists available tests
+
+- **GIVEN** client invokes run test prompt with only `analysisId`
+- **WHEN** the prompt messages are returned
+- **THEN** it SHALL include context about available test cases for that analysis
+
+### Requirement: Prompt Argument Validation
+
+The system SHALL validate prompt arguments and return helpful errors.
+
+#### Scenario: Missing required argument returns error
+
+- **GIVEN** client invokes `retest-start` without `url`
+- **WHEN** validation occurs
+- **THEN** it SHALL return error indicating `url` is required
+
+#### Scenario: Invalid analysisId returns error
+
+- **GIVEN** client invokes a prompt with non-existent `analysisId`
+- **WHEN** validation occurs
+- **THEN** it SHALL return error indicating analysis not found
+
+### Requirement: Prompt Chaining Guidance
+
+The system SHALL include guidance in prompt outputs for the recommended workflow sequence.
+
+#### Scenario: Start analysis prompt suggests next step
+
+- **GIVEN** client uses start analysis prompt
+- **WHEN** the prompt messages are returned
+- **THEN** they SHALL include guidance: "After analysis starts, use retest-crawl to explore the application"
+
+#### Scenario: Crawl prompt suggests next step
+
+- **GIVEN** client uses crawl prompt
+- **WHEN** the prompt messages are returned
+- **THEN** they SHALL include guidance: "After crawl completes, use retest-discover to identify features and flows"
+
+#### Scenario: Discover prompt suggests next step
+
+- **GIVEN** client uses discover prompt
+- **WHEN** the prompt messages are returned
+- **THEN** they SHALL include guidance: "After discovery, use retest-generate-tests to create test cases"
+
+#### Scenario: Generate tests prompt suggests next step
+
+- **GIVEN** client uses generate tests prompt
+- **WHEN** the prompt messages are returned
+- **THEN** they SHALL include guidance: "After test generation, use retest-run-test to execute individual test cases"

package/openspec/changes/rename-package-to-retest/specs/retest-resources/spec.md

@@ -0,0 +1,251 @@
+# retest-resources Specification Delta
+
+## RENAMED Requirements
+
+- **FROM**: `webtest-resources` specification
+- **TO**: `retest-resources` specification
+
+## MODIFIED Requirements
+
+### Requirement: Resource URI Scheme
+
+The system SHALL expose all retest artifacts using a `retest://` URI scheme with hierarchical paths, using markdown format for all human-readable artifacts.
+
+#### Scenario: Analysis root resource is accessible
+
+- **GIVEN** an analysis has been started with analysisId "abc123"
+- **WHEN** client requests resource `retest://abc123/`
+- **THEN** it SHALL return the analysis `index.md` metadata as markdown with YAML frontmatter
+
+#### Scenario: Crawl index resource is accessible
+
+- **GIVEN** a crawl has completed with crawlId "crawl-001"
+- **WHEN** client requests resource `retest://abc123/crawls/crawl-001/index.md`
+- **THEN** it SHALL return the crawl index as markdown with YAML frontmatter containing page list and metadata
+
+#### Scenario: Page artifacts are accessible by type
+
+- **GIVEN** a page was captured with pageId "page-001"
+- **WHEN** client requests `retest://abc123/crawls/crawl-001/pages/page-001/screenshot.png`
+- **THEN** it SHALL return the screenshot image
+- **AND** `snapshot.md` returns accessibility tree as formatted markdown with YAML frontmatter
+- **AND** `dom.html` returns HTML content
+
+#### Scenario: Crawl checkpoint is accessible
+
+- **GIVEN** a crawl is in progress with checkpoint saved
+- **WHEN** client requests `retest://abc123/crawls/crawl-001/checkpoint.md`
+- **THEN** it SHALL return the checkpoint as markdown with YAML frontmatter containing crawl state
+
+#### Scenario: Features report is accessible
+
+- **GIVEN** discover_features has completed
+- **WHEN** client requests `retest://abc123/features.md`
+- **THEN** it SHALL return the markdown features report
+
+#### Scenario: Feature flows are accessible
+
+- **GIVEN** discover_flows has completed for a feature
+- **WHEN** client requests `retest://abc123/features/{featureSlug}/flows.md`
+- **THEN** it SHALL return user flows as markdown with YAML frontmatter containing structured flow definitions
+
+#### Scenario: Tests are accessible
+
+- **GIVEN** generate_tests has completed
+- **WHEN** client requests `retest://abc123/tests/tests.md`
+- **THEN** it SHALL return the test cases as markdown with YAML frontmatter containing structured test definitions
+
+#### Scenario: Test run report is accessible
+
+- **GIVEN** a test run has completed with runId "run-001"
+- **WHEN** client requests `retest://abc123/runs/run-001/report.md`
+- **THEN** it SHALL return the test execution report as markdown with YAML frontmatter containing structured results
+
+#### Scenario: Test step snapshot is accessible
+
+- **GIVEN** a test step has captured evidence
+- **WHEN** client requests `retest://abc123/runs/run-001/steps/1/snapshot.md`
+- **THEN** it SHALL return the accessibility snapshot as formatted markdown with YAML frontmatter
+
+### Requirement: Resource Template Registration
+
+The system SHALL register resource templates with the MCP server for discovery, using markdown extensions for all index and report resources.
+
+#### Scenario: Templates are listed on resources/list
+
+- **GIVEN** a client calls `resources/list`
+- **WHEN** the response is returned
+- **THEN** it SHALL include templates for:
+  - `retest://{analysisId}/index.md` (Analysis index)
+  - `retest://{analysisId}/crawls/{crawlId}/index.md` (Crawl index)
+  - `retest://{analysisId}/crawls/{crawlId}/checkpoint.md` (Crawl checkpoint)
+  - `retest://{analysisId}/crawls/{crawlId}/pages/{pageId}/snapshot.md` (Page snapshot)
+  - `retest://{analysisId}/crawls/{crawlId}/pages/{pageId}/screenshot.png` (Page screenshot)
+  - `retest://{analysisId}/crawls/{crawlId}/pages/{pageId}/dom.html` (Page DOM)
+  - `retest://{analysisId}/features.md` (Features report)
+  - `retest://{analysisId}/features/{featureSlug}/flows.md` (Feature flows)
+  - `retest://{analysisId}/tests/tests.md` (Test definitions)
+  - `retest://{analysisId}/runs/{runId}/report.md` (Test run report)
+  - `retest://{analysisId}/runs/{runId}/steps/{stepNumber}/snapshot.md` (Step snapshot)
+  - `retest://{analysisId}/runs/{runId}/steps/{stepNumber}/screenshot.png` (Step screenshot)
+
+### Requirement: Resource Content Types
+
+The system SHALL return appropriate MIME types for different artifact types.
+
+#### Scenario: Markdown resources have correct type
+
+- **GIVEN** client reads a `.md` resource
+- **WHEN** response is returned
+- **THEN** mimeType SHALL be `text/markdown`
+
+#### Scenario: Screenshot resources have correct type
+
+- **GIVEN** client reads a `.png` resource
+- **WHEN** response is returned
+- **THEN** mimeType SHALL be `image/png`
+- **AND** content SHALL be base64 encoded
+
+#### Scenario: HTML resources have correct type
+
+- **GIVEN** client reads a `.html` resource
+- **WHEN** response is returned
+- **THEN** mimeType SHALL be `text/html`
+
+### Requirement: Resource Listing by Analysis
+
+The system SHALL support listing all resources within an analysis.
+
+#### Scenario: List all resources for analysis
+
+- **GIVEN** an analysis with multiple crawls and runs
+- **WHEN** client calls `resources/list` with `retest://abc123/` prefix
+- **THEN** it SHALL return all resources within that analysis
+- **AND** each resource SHALL include URI, name, and mimeType
+
+#### Scenario: List crawl resources
+
+- **GIVEN** a crawl with multiple pages
+- **WHEN** client calls `resources/list` with `retest://abc123/crawls/crawl-001/` prefix
+- **THEN** it SHALL return all resources within that crawl
+
+### Requirement: Resource Change Signaling
+
+The system SHALL support resource change notifications to surface new artifacts in real-time during long-running operations.
+
+#### Scenario: Server emits listChanged when new resource created
+
+- **GIVEN** client capability includes `resources.listChanged`
+- **WHEN** a crawl captures a new page artifact
+- **THEN** server SHALL emit `notifications/resources/list_changed`
+- **AND** client can re-fetch `resources/list` to discover new resources
+
+#### Scenario: Server emits listChanged during test execution
+
+- **GIVEN** client capability includes `resources.listChanged`
+- **WHEN** a test run completes a step and writes evidence
+- **THEN** server SHALL emit `notifications/resources/list_changed`
+
+#### Scenario: Fallback when listChanged not supported
+
+- **GIVEN** client does not support `resources.listChanged`
+- **WHEN** new resources are created
+- **THEN** server SHALL NOT emit notifications
+- **AND** client must poll `resources/list` to discover new resources
+
+### Requirement: Resource Subscription
+
+The system SHALL support resource subscriptions for live updates during operations when client supports it.
+
+#### Scenario: Client subscribes to crawl index
+
+- **GIVEN** client supports `resources/subscribe`
+- **AND** client subscribes to `retest://abc123/crawls/crawl-001/index.md`
+- **WHEN** crawl adds a new page
+- **THEN** server SHALL emit `notifications/resources/updated` with the resource URI
+
+#### Scenario: Client subscribes to analysis status
+
+- **GIVEN** client supports `resources/subscribe`
+- **AND** client subscribes to `retest://abc123/index.md`
+- **WHEN** analysis phase changes (crawl -> discover -> generate)
+- **THEN** server SHALL emit `notifications/resources/updated`
+
+#### Scenario: Subscription request when unsupported
+
+- **GIVEN** client does not support `resources/subscribe`
+- **WHEN** server attempts to notify
+- **THEN** server SHALL skip notification without error
+- **AND** client must poll resources for updates
+
+### Requirement: Workspace Persistence
+
+The system SHALL persist all resources to the filesystem for durability.
+
+#### Scenario: Resources survive server restart
+
+- **GIVEN** an analysis has been created
+- **WHEN** server restarts
+- **THEN** all previously created resources SHALL be accessible
+- **AND** resource URIs SHALL resolve to the same content
+
+#### Scenario: Workspace directory is configurable
+
+- **GIVEN** environment variable `RETEST_WORKSPACE_DIR` is set to `/data/retests`
+- **WHEN** analysis is created
+- **THEN** workspace SHALL be created under `/data/retests/{analysisId}/`
+
+#### Scenario: Default workspace location
+
+- **GIVEN** `RETEST_WORKSPACE_DIR` is not set
+- **WHEN** analysis is created
+- **THEN** workspace SHALL be created under `./retest-workspaces/{analysisId}/`
+
+### Requirement: Resource Error Handling
+
+The system SHALL return appropriate errors for invalid resource requests.
+
+#### Scenario: Unknown analysis returns not found
+
+- **GIVEN** client requests `retest://unknown-id/`
+- **WHEN** URI is resolved
+- **THEN** it SHALL return error with code "ResourceNotFound"
+
+#### Scenario: Invalid URI format returns error
+
+- **GIVEN** client requests resource with invalid URI format
+- **WHEN** URI is parsed
+- **THEN** it SHALL return error with code "InvalidResourceUri"
+
+#### Scenario: Missing artifact returns not found
+
+- **GIVEN** client requests `retest://abc123/crawls/crawl-001/pages/page-999/screenshot.png`
+- **AND** page-999 does not exist
+- **WHEN** URI is resolved
+- **THEN** it SHALL return error with code "ResourceNotFound"
+
+### Requirement: Hybrid Artifact Access
+
+The system SHALL provide both filesystem paths and MCP resource URIs for all artifacts, enabling direct file access alongside MCP resource reads.
+
+#### Scenario: Workspace manager returns both path and URI
+
+- **GIVEN** a workspace method saves an artifact (analysis, tests, pages, evidence)
+- **WHEN** the save operation completes
+- **THEN** it SHALL return both the absolute filesystem path and the `retest://` URI
+- **AND** the filesystem path SHALL be absolute (not relative)
+- **AND** the path SHALL point to the actual file on disk
+
+#### Scenario: File path resolves to same content as resource URI
+
+- **GIVEN** an artifact has been saved
+- **WHEN** the file is read directly via filesystem path
+- **AND** the resource is read via MCP `resources/read` with the URI
+- **THEN** both SHALL return identical content
+
+#### Scenario: Workspace root path is accessible
+
+- **GIVEN** a workspace has been created
+- **WHEN** the workspace manager is queried
+- **THEN** it SHALL provide the absolute path to the workspace root directory
+- **AND** this path SHALL be used as the base for all artifact file paths