Add Phase 2 validator documentation

[Copilot]

Documents the Phase 2 validator stack introduced in feat/agent-plane-capd-patch-v0: three Python CLI validators, the CAPD patch fragment, and the planned admission webhook integration.

What's documented

• Architecture — Three-tier validation stack (Tier 1: make validate gate → Tier 2: Python CLI validators → Tier 3: K8s admission webhook) with ASCII flow diagrams
• Validator specs — Per-module tables for ExecutionDecisionValidator, SkillManifestValidator, SessionReceiptValidator: discriminator constant, CLI entry point, exit codes, stdout/stderr contract
• CAPD patch — Annotated imagelab.capd.patch.yaml with contract-dir → artefact-type and validator entry-point cross-reference tables
• Admission webhook — ValidatingWebhookConfiguration YAML + Python pseudocode handler; route-to-module mapping; security notes on TLS/mTLS and temp-file cleanup
• Schema binding roadmap — Current type-discriminator-only scope explained; migration steps and anticipated URN pattern (socio:<capability>:<resource>:<version>:<id>) once sourceos-spec#1 merges
• Testing strategy — Target test layout, 5 canonical test cases per validator, full example unit-test module, integration test outline
• Limitations & deferred work — Prioritised deferral table (full schema validation, URN enforcement, webhook HTTP server, CAPD merge tooling)
• File inventory — All 5 PR files with line counts, descriptions, and stdlib-only dependency graph

Original prompt

Phase 2: Comprehensive Validator Documentation

Add comprehensive Phase 2 documentation to imagelab#1 (feat/agent-plane-capd-patch-v0 branch).

Documentation to Add

Create PHASE_2_VALIDATOR_DOCUMENTATION.md with:

1. Validator Architecture Overview - Three-tier validation stack diagram
2. Validator Module Specifications - ExecutionDecisionValidator, SkillManifestValidator, SessionReceiptValidator (22 lines each)
3. Capability Descriptor (CAPD) Patch - Contract directories and validator entry points
4. Admission Webhook Integration - Kubernetes configuration and admission handler implementation
5. Full Schema Binding Roadmap - How validators will bind to sourceos-spec schemas post-merge
6. Testing Strategy - Unit tests, test cases, integration tests
7. Current Limitations & Follow-Up Tasks - What's done, what's deferred
8. Complete File Inventory - All 5 files (3 validators + 1 CAPD + 1 init)

Current Files in PR

• validators/execution_decision.py (22 lines)
• validators/skill_manifest.py (22 lines)
• validators/session_receipt.py (22 lines)
• validators/init.py (1 line)
• capd/imagelab.capd.patch.yaml (11 lines)

Key Points to Document

• How validators check type discrimination
• URN pattern validation approach
• Return format (JSON with ok/error fields)
• CLI entry points (python -m validators.{validator_name})
• Admission webhook flow
• Schema binding strategy once sourceos-spec#1 merges
• Integration points with agentplane artifacts
• Testing approach and test case examples

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: @copilot Accepted Confirmation: Are you sure?

This pull request was created from Copilot chat.