Buckets:

localhost1978
/

localhost

Files

xet

localhost1978/localhost / LOCALHOST1978 /SSK_DocGen /SSK_DocGen_Manual_Testing_Guide.md

localhost1978

3 months ago

preview code

download

raw

10.3 kB

# SSK_DocGen P0 Manual Testing Guide
Status: Prepared for manual Xcode testing. All results are `Not run`.
This guide verifies the local P0 path:
```text
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:
```text
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.

Xet Storage Details

Size:: 10.3 kB
Xet hash:: a77f9564502a0dee6a20188b0303317d2444f2462805913ef092c7d9e22cc1e6

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# SSK_DocGen P0 Manual Testing Guide

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

	This guide verifies the local P0 path:

	```text
	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:

	```text
	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.