Buckets:
| # SSK_DocGen | |
| Status: P0 and P1 source and configuration are implemented. Manual Xcode verification is not run. | |
| See [SSK_DocGen Phase and Priority Roadmap](file:///Users/voxels/SovereignSurvivalKit/next/dev/SSK_DOCGEN_PHASE_ROADMAP.md) for the complete phase matrix, priority specifications, and capability roadmap. | |
| --- | |
| ## 1. Module Role and Topology | |
| `SSK_DocGen` is the private documentation generator and resource worker for SovereignSurvivalKit. It is **not** the external Xcode MCP entry point. | |
| Xcode has one external MCP entry point: | |
| ```text | |
| SSK_StorageHost acp-agent | |
| ``` | |
| The request path is: | |
| ```text | |
| Xcode or Approved MCP Client | |
| │ (stdio) | |
| ▼ | |
| SSK_StorageHost acp-agent (External MCP Facade) | |
| │ (com.ssk.vaulthost Mach XPC) | |
| ▼ | |
| SSKVaultHost Daemon (Validates Audit Token & Code Signature) | |
| │ (Private Worker Process) | |
| ▼ | |
| SSK_DocGen (Isolated Resource Worker) | |
| │ (Descriptor-Relative Read) | |
| ▼ | |
| Approved Documentation Ledger (SSK_Ledger_Vault) | |
| ``` | |
| The commerce tools in `SSK_StorageHost acp-agent` remain unchanged. DocGen adds documentation resources and maintenance tools. | |
| --- | |
| ## 2. P0 and P1 User Capabilities | |
| An approved local MCP client can discover and read documentation resources: | |
| | Resource | Logical URI | MIME Type | | |
| | :--- | :--- | :--- | | |
| | **DocC Index** | `ssk://spec:SSK-DocGen-P0/ledger/documentation/docc-index` | `application/json` | | |
| | **Codebase Graph** | `ssk://spec:SSK-DocGen-P0/ledger/documentation/codebase-graph` | `application/json` | | |
| | **Documentation Index** | `ssk://spec:SSK-DocGen-P0/ledger/documentation/master-index` | `text/markdown` | | |
| | **Refresh Status** | `ssk://spec:SSK-DocGen-P1/ledger/documentation/status` | `application/json` | | |
| P1 adds documentation refresh and status query tools to `SSK_StorageHost acp-agent`: | |
| - `refresh_docs`: Triggers background documentation rescanning and updates the ledger in isolated staging. | |
| - `get_docgen_status`: Returns current state (`queued`, `running`, `ready`, or `failed`) and process metrics. | |
| The client does not provide a file path, executable path, workspace path, or vault path. `SSKVaultHost` stores operator-approved roots in secure configuration. The daemon reads this configuration and starts the private worker. | |
| --- | |
| ## 3. Phase Summary | |
| | Phase | Priority Level | User Capability | Status | | |
| | :--- | :--- | :--- | :--- | | |
| | **P0** | **Critical** | Read approved local documentation resources via `SSK_StorageHost acp-agent`. | `Implemented, not verified` | | |
| | **P1** | **High** | Request local documentation refresh and query status. | `Implemented, not verified` | | |
| | **P2** | **Medium** | Review proposed documentation changes and approve or reject before publication. | `Planned. Not available in P1.` | | |
| | **P3** | **Low** | Read approved documentation from enrolled peer mesh devices. | `Planned. Not available in P1.` | | |
| --- | |
| ## 4. Xcode Setup | |
| Use the `SSKVaultHost` scheme to prepare the local daemon: | |
| 1. Create an isolated workspace directory and an isolated vault directory. | |
| 2. In the `SSKVaultHost` Run scheme, set `SSK_DOCGEN_WORKSPACE` to the absolute workspace directory. | |
| 3. Set `SSK_DOCGEN_VAULT` to the absolute vault directory. | |
| 4. Build and run `SSKVaultHost`. | |
| 5. Confirm that the application contains `SSK_StorageHost`, `SSK_DocGen`, and `Contents/Library/LaunchAgents/com.ssk.vaulthost.plist`. | |
| 6. Confirm that the launch agent is registered or approve it when macOS requests permission. | |
| 7. Build and install `XCPSSKPlugin`, or use `/usr/local/bin/SSK_StorageHost`. | |
| 8. Configure the MCP command in Xcode as `SSK_StorageHost acp-agent`. | |
| > [!WARNING] | |
| > Do not configure Xcode to start `SSK_DocGen serve` directly. | |
| See [SSK_DocGen_Manual_Testing_Guide.md](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SSK_DocGen/SSK_DocGen_Manual_Testing_Guide.md) for the complete manual procedure. | |
| --- | |
| ## 5. Private Worker Commands | |
| `SSK_DocGen` provides two internal engineering commands: | |
| ```text | |
| SSK_DocGen generate --vault <path> [--workspace <path>] [--clean|--no-clean] | |
| SSK_DocGen serve [--vault <path>] [--workspace <path>] | |
| ``` | |
| - `generate` builds ledger artifacts. It requires `--vault`. Do not use a shared or production vault for a test. | |
| - `serve` is a private worker protocol mode. The host starts it with trusted configuration. It receives JSON-RPC requests on standard input and writes protocol responses to standard output. Diagnostics go to standard error. | |
| --- | |
| ## 6. Security Boundaries | |
| - `SSK_StorageHost acp-agent` owns MCP standard input and standard output. | |
| - The MCP facade accepts only fixed logical DocGen URIs. | |
| - The named XPC route uses typed, versioned `DocGenHostCommand` messages. | |
| - The XPC listener verifies the audit token and Apple code signature before exporting the service. | |
| - `SSKVaultHost` persists approved roots in an owner-only directory and configuration file. | |
| - The daemon resolves approved roots and the bundled worker. Clients cannot select them. | |
| - Child-process input, output, diagnostics, duration, and response counts are bounded. | |
| - The resource reader uses descriptor-relative access, no-symlink checks, regular-file checks, and bounded reads. | |
| - Content is redacted in the worker and again at the external MCP boundary. | |
| - Errors never return local file paths, private keys, claims, or credentials. | |
| --- | |
| ## 7. Development and Testing Rules | |
| - Use `SSK_DocGenTests` for private worker and resource-reader tests. | |
| - Use `SSK_AbstractionsTests` for typed resource and command model tests. | |
| - Use `SSK_FoundationTests` for process launcher and XPC route tests. | |
| - Use `SSK_ProvidersTests` for secure configuration store and MCP facade tests. | |
| - Use `SSKVaultHost` and `XCPSSKPlugin` schemes for bundle and lifecycle checks. | |
| - Do not claim that an Xcode test passed without the attached Xcode result. | |
| - Do not add a second Xcode agent, daemon, Mach service, or DocGen network server. | |
| - Do not make `SSK_Providers` import `SSK_Orchestrator`. | |
| - **Do not use `git`**. This workspace uses `lore` for version control. | |
Xet Storage Details
- Size:
- 6.01 kB
- Xet hash:
- c8b1263789038bc8ec32e4b6d669875cdf62bd3b3648054f2169013dcd780265
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.