LOCALHOST1978/SSK_DocGen/AGENTS.md

Agent Guidelines for SSK_DocGen

Status: P0 and P1 source and configuration are implemented. Manual Xcode verification is not run.

See SSK_DocGen Phase and Priority Roadmap for the complete phase and priority matrix.

---

1. Module Role

SSK_DocGen has two private engineering roles:

1. generate creates documentation ledger artifacts.
2. serve is the private worker protocol mode used by the trusted host daemon.

SSK_DocGen is not the Xcode MCP server. The only Xcode MCP command is:

SSK_StorageHost acp-agent

Do not add a direct Xcode configuration for SSK_DocGen serve.

---

2. Required Reading

Read these files before you change this module:

• README.md for module topology and setup;
• SSK_DocGen Phase Roadmap for priority phases and status;
• SSK_DocGen_Manual_Testing_Guide.md for manual Xcode checks.

All current manual results are Not run. Do not call evidence empirical or verified until an actual Xcode result and matching hashes exist.

---

3. Version Control

Do not use git. This workspace uses lore for version control and state tracking. Do not stage, commit, push, or sync unless the user asks.

---

4. Platform and Test Rules

• The package requires macOS 27 and the Swift 6.4 toolchain.
• Use SSK_DocGenTests for private worker and resource-reader tests.
• Use SSK_AbstractionsTests for typed resource and command models.
• Use SSK_FoundationTests for process and XPC behavior.
• Use SSK_ProvidersTests for host configuration and MCP facade behavior.
• Do not claim that a shared SSK_DocGen Xcode scheme exists.
• Do not claim a pass without the attached Xcode result.

---

5. Dependency Rules

SSK_DocGen/Package.swift has explicit dependencies on the modules that its generator uses. Keep direct imports as direct package dependencies.

The external host-worker boundary is in lower layers:

• SSK_Abstractions owns DocGenResource, worker request/response types, and DocGenHostCommand.
• SSK_Foundation owns the bounded child-process executor and XPC route.
• SSK_Providers owns the daemon configuration and MCP facade.
• SSK_Orchestrator can use the lower-layer worker executor as a compatibility adapter.

Do not make SSK_Providers import SSK_Orchestrator.

---

6. External Surface (P0 and P1)

The external MCP facade exposes these resources:

Resource	Logical URI
DocC Index	ssk://spec:SSK-DocGen-P0/ledger/documentation/docc-index
Codebase Graph	ssk://spec:SSK-DocGen-P0/ledger/documentation/codebase-graph
Documentation Index	ssk://spec:SSK-DocGen-P0/ledger/documentation/master-index
Refresh Status	ssk://spec:SSK-DocGen-P1/ledger/documentation/status

P1 exposes two MCP tools through SSK_StorageHost acp-agent:

• refresh_docs: Triggers documentation rescanning and ledger updates in isolated staging.
• get_docgen_status: Returns current status and progress metrics.

The commerce tools in SSK_StorageHost acp-agent are outside this module. Do not change them during DocGen work.

---

7. Security Rules

• Accept fixed logical resources only. Never turn client text into a file path.
• Do not accept a client workspace, vault, executable, or file path.
• Let SSKVaultHost store operator-approved roots.
• Let the daemon read the secure stored configuration and resolve the bundled worker.
• Keep protocol output on standard output and diagnostics on standard error.
• Bound worker input, output, diagnostics, duration, and response counts.
• Use descriptor-relative, no-symlink reads from the approved vault root.
• Require a regular and stable file before data is returned.
• Apply resource size limits while reading.
• Redact content in the worker and at the external MCP boundary.
• Fail closed. Do not return paths, keys, claims, credentials, or signing data.
• Do not add a second daemon, Mach service, Xcode agent, or DocGen network server.
• Do not route DocGen over HTTP/3, Bonjour, or mesh transport in P0 or P1.

---

8. Generation and Ignore Rules

generate scans supported module and DocGen source roots. LoreIgnore filters the scan. Do not weaken .loreignore or .agentignore rules.

Use an isolated vault for tests. Do not use the canonical ledger as a mutable test fixture.

---

9. Status Terms

Use these exact terms:

• Implemented, not verified for source behavior;
• Configured, not verified for project and bundle behavior;
• Not run for a missing Xcode result;
• Planned. Not available in P1. for P2 and P3 features.