LOCALHOST1978/SSK_DocGen/SSK_DocGen_Manual_Testing_Guide.md

SSK_DocGen P0 Manual Testing Guide

Status: Prepared for manual Xcode testing. All results are Not run.

This guide verifies the local P0 path:

Xcode MCP client
  -> SSK_StorageHost acp-agent
  -> com.ssk.vaulthost Mach XPC
  -> SSK_StorageHost daemon
  -> private SSK_DocGen worker
  -> isolated documentation ledger

Do not use this guide as proof of a pass until the evidence record contains an actual Xcode result and matching source hashes.

1. Safety Rules

• Use Xcode for all builds and tests in this procedure.
• Use an isolated workspace root and an isolated vault root.
• Do not use the production workspace as a writable fixture.
• Do not use a shared or production vault.
• Do not put a file path or executable path in an MCP or XPC request.
• Keep the test Mac offline when the test does not require another local process.
• Keep all DocGen P0 traffic local. Do not enable a remote or non-loopback route.
• Record Not run, Pass, Fail, or Blocked for each check.

2. Prepare Isolated Roots

1. Create an isolated workspace directory in Finder.
2. Put the minimum supported source fixture in that directory.
3. Create an isolated vault directory in Finder.
4. Put these approved resource fixtures directly in the isolated vault root:
   • docc_index.json;
   • graph.json;
   • DocC_Index.md.
5. Make both JSON files valid JSON.
6. Keep docc_index.json below 2 MiB.
7. Keep graph.json and DocC_Index.md below 256 KiB.
8. Record the two absolute paths in the evidence record. Do not put them in a client request.

Result: Not run

3. Configure SSKVaultHost

1. Open SovereignSurvivalKit.xcodeproj in Xcode.
2. Select the SSKVaultHost scheme.
3. Open the Run action environment settings.
4. Set SSK_DOCGEN_WORKSPACE to the absolute isolated workspace root.
5. Set SSK_DOCGEN_VAULT to the absolute isolated vault root.
6. Confirm that both values name existing directories.
7. Confirm that the scheme uses a macOS destination.
8. Record the Xcode version, macOS version, destination, and configuration.

Expected result: The lifecycle application accepts only the two valid absolute directories. It does not accept a missing, relative, or non-directory value.

Result: Not run

4. Build and Run SSKVaultHost

1. Build the SSKVaultHost scheme in Xcode.
2. Run SSKVaultHost.
3. Inspect its standard-error diagnostics in Xcode.
4. Confirm one of these results:
   • SSKVaultHost: launch agent is ready.; or
   • SSKVaultHost: launch agent requires user approval.
5. If approval is required, approve the background item in macOS System Settings. Run SSKVaultHost again.
6. Confirm that it reports that the launch agent is ready.

Expected result: SSKVaultHost stores the approved roots and registers the launch agent. It does not start an MCP server.

Result: Not run

5. Inspect the Built Lifecycle Bundle

Use Xcode's Products group and Show in Finder. Inspect SSKVaultHost.app.

Confirm that these items exist:

SSKVaultHost.app/Contents/MacOS/SSKVaultHost
SSKVaultHost.app/Contents/MacOS/SSK_StorageHost
SSKVaultHost.app/Contents/MacOS/SSK_DocGen
SSKVaultHost.app/Contents/Library/LaunchAgents/com.ssk.vaulthost.plist

Confirm that the plist contains:

• Label = com.ssk.vaulthost;
• BundleProgram = Contents/MacOS/SSK_StorageHost;
• MachServices/com.ssk.vaulthost = true;
• RunAtLoad = true;
• KeepAlive = true.

Confirm that the three executables are signed by the expected development team.

Result: Not run

6. Confirm Secure Stored Configuration

1. Inspect the current user's Application Support directory.
2. Confirm that SovereignSurvivalKit/DocGenHost is an owner-only directory.
3. Confirm that configuration.json is an owner-only regular file.
4. Confirm that the file contains only the approved workspace and vault roots and the supported format version.
5. Do not copy this file into test evidence. Record only the permissions and pass or fail result.
6. Restart the daemon without the two environment overrides.
7. Confirm that the daemon reads the stored configuration.

Expected result: The MCP client never supplies these roots. The daemon fails closed if the stored configuration is missing, malformed, linked, or insecure.

Result: Not run

7. Prepare the Xcode MCP Entry

Use one of these paths:

XCP plug-in path

1. Select the XCPSSKPlugin scheme.
2. Build the scheme in Xcode.
3. Confirm that the plug-in resources contain SSK_StorageHost and ssk-intelligence-plugin.json.
4. Confirm that the manifest command is ./Resources/SSK_StorageHost.
5. Confirm that its only argument is acp-agent.
6. Install or load the plug-in by the approved Xcode procedure.

Stable agent path

1. Use the stable SSK_Agent link created in Application Support.
2. Confirm that it resolves to the embedded SSK_StorageHost executable.
3. Configure Xcode to use the stable executable with the acp-agent argument.

Do not configure Xcode to start SSK_DocGen serve.

Result: Not run

8. List P0 Resources

Start the configured MCP agent from Xcode. Ask the client to list resources.

Expected resources:

Name	URI	MIME type
SSK DocC Index	ssk://spec:SSK-DocGen-P0/ledger/documentation/docc-index	application/json
SSK Codebase Graph	ssk://spec:SSK-DocGen-P0/ledger/documentation/codebase-graph	application/json
SSK Documentation Index	ssk://spec:SSK-DocGen-P0/ledger/documentation/master-index	text/markdown

Confirm that no DocGen prompt, generation tool, curation tool, synthesis tool, or generic file-browser resource is present. Confirm that the existing commerce tools remain present and unchanged.

Result: Not run

9. Read Each P0 Resource

For each URI in Section 8:

1. Send one MCP resource-read request.
2. Confirm that the request crosses the named XPC route.
3. Confirm that the daemon starts the bundled private worker.
4. Confirm that the returned URI and MIME type match the requested resource.
5. Confirm that JSON resources contain valid JSON.
6. Confirm that the Markdown resource contains text.
7. Confirm that the response contains no workspace path, vault path, home path, bundle path, worker path, key, claim, or credential.
8. Confirm that standard output contains MCP protocol data only.
9. Confirm that diagnostics appear on standard error only.

Result for DocC index: Not run

Result for codebase graph: Not run

Result for documentation index: Not run

10. MCP and XPC Negative Cases

Run each case separately. Record the exact external error category. Do not expect an internal path or sensitive detail.

Case	Expected result	Result
Unknown logical resource URI	Invalid resource request	Not run
Client-supplied file URI	Invalid resource request	Not run
Malformed XPC data	Typed failure; no worker start	Not run
Unsupported XPC version	Typed failure; no worker start	Not run
Unknown XPC command	Typed failure; no worker start	Not run
Duplicate active request ID	Typed failure	Not run
Missing audit token	Connection rejected	Not run
Wrong signing team	Connection rejected	Not run
Unsigned or invalid caller	Connection rejected	Not run
Daemon unavailable	Redacted MCP failure	Not run
Worker unavailable	Redacted MCP failure	Not run
Request cancellation	One cancellation result and child cleanup	Not run
Request timeout	One timeout result and child cleanup	Not run

11. Resource Security Negative Cases

Use only the isolated vault. Restore the fixture after each case.

Case	Expected result	Result
Missing approved resource	Redacted unavailable failure	Not run
Leaf file replaced by a symlink	Read rejected	Not run
Ancestor directory replaced by a symlink	Read rejected	Not run
FIFO, socket, device, or directory at resource leaf	Read rejected	Not run
docc_index.json larger than 2 MiB	Read rejected	Not run
Graph or Markdown index larger than 256 KiB	Read rejected	Not run
File changes during read	Read rejected	Not run
Invalid JSON in a JSON resource	Read rejected	Not run
Absolute path in resource content	Path redacted	Not run
Sensitive JSON key or PEM data	Sensitive value redacted or response rejected	Not run
Insecure stored-configuration permissions	Daemon fails closed	Not run
Stored configuration is a symlink	Daemon fails closed	Not run

12. Xcode Test Targets

Run the applicable tests in Xcode and record exact test names and counts:

• SSK_AbstractionsTests: resource and host-command models;
• SSK_FoundationTests: process worker, XPC router, XPC bridge, and caller authorization;
• SSK_ProvidersTests: secure host configuration, MCP facade, external redaction, commerce surface, and daemon configuration;
• SSK_DocGenTests: private resource reader and worker protocol.

Do not claim that a shared SSK_DocGen scheme exists. If Xcode does not show a required package test target, record Blocked.

Result: Not run

13. Full-Chain Result and Evidence

After the checks finish:

1. Record the exact scheme, target, destination, configuration, Xcode version, macOS version, date, and operator.
2. Attach the Xcode test report or screenshot.
3. Record the source and configuration SHA-256 values listed in the evidence record.
4. Record bundle, signing, launch-agent, XPC, MCP, worker, and resource-security failures as separate categories.
5. Mark the full chain Pass only if the three resources list and read through SSK_StorageHost acp-agent and no direct Xcode DocGen command remains.

Full-chain result: Not run

Evidence record: /Users/voxels/SovereignSurvivalKit/next/dev/ssk_docgen_p0_xcode_evidence.md

14. Deferred Phases

• P1 local refresh is planned. It is not available in P0.
• P2 proposal, approval, publication, and rollback are planned. They are not available in P0.
• P3 enrolled-peer read access is planned. It is not available in P0.

Do not use the P0 manual result as proof for a deferred phase.