{
  "schema_version": "0.1",
  "artifact_type": "architecture",
  "canonical": true,
  "artifact_id": "ARCH-005",
  "agent_summary": {
    "title": "PRD Plugin to AI-Collab Substrate adapter architecture",
    "status": "implemented",
    "summary": "A thin AI-Collab-side adapter consumes versioned PRD Plugin contracts, projects repo-scoped derived state into existing Substrate tables and causal edges, invokes canonical MCP writes only when coordinated mode permits, and delegates bounded model work through the established reporting contract.",
    "last_reviewed_at": "2026-07-14",
    "load_notes": "This JSON artifact is canonical. Generate Markdown only on explicit human request."
  },
  "context": "AI-Collab already discovers UTCP/MCP descriptors, watches repositories, mirrors part of PRD tracking state, carries PRD IDs on payloads, and exposes live subscriptions. PRD Plugin already owns eight read tools, twenty-two validated MCP tools, cause-effect graph export, delegated reporting, and parallel tracking branches. The adapter consolidates these existing boundaries rather than creating another protocol or canonical store.",
  "principles": [
    "One authority per concern: PRD Plugin owns project truth; AI-Collab owns runtime projection and execution.",
    "Translate and correlate; never duplicate ID allocation, validation, provider credentials, or canonical state mutation.",
    "Disabled is inert, observe is read-only, coordinate is explicitly allowlisted.",
    "Reuse existing Substrate records, causal edges, watches, tool discovery, and client primitives before adding state."
  ],
  "components": [
    {"id": "ARCH-COMP-024", "summary": "Substrate integration configuration", "responsibility": "Define the master switch, mode, capability allowlist, privacy constraints, and versioned adapter policy in committed PRD configuration.", "requirement_ids": ["PRD-REQ-030", "PRD-NFR-018", "PRD-NFR-019"], "interface_ids": ["ARCH-IF-017"]},
    {"id": "ARCH-COMP-025", "summary": "PRD capability handshake", "responsibility": "Produce deterministic effective configuration and official UTCP, MCP, graph, and reporting contract metadata.", "requirement_ids": ["PRD-REQ-031", "PRD-REQ-038"], "interface_ids": ["ARCH-IF-018"]},
    {"id": "ARCH-COMP-026", "summary": "AI-Collab record projector", "responsibility": "Collect complete bounded PRD snapshots, calculate generation-aware changes, and reconcile repo-scoped derived records including removals.", "requirement_ids": ["PRD-REQ-032", "PRD-REQ-034"], "interface_ids": ["ARCH-IF-019", "ARCH-IF-020"]},
    {"id": "ARCH-COMP-027", "summary": "Traceability graph projector", "responsibility": "Import cause-effect edges with repo-qualified node keys into the Substrate causal graph.", "requirement_ids": ["PRD-REQ-033"], "interface_ids": ["ARCH-IF-021"]},
    {"id": "ARCH-COMP-028", "summary": "Validated command gateway", "responsibility": "Authorize coordinate-mode operations and invoke allowlisted PRD MCP tools without direct canonical file writes.", "requirement_ids": ["PRD-REQ-035", "PRD-NFR-016"], "interface_ids": ["ARCH-IF-022"]},
    {"id": "ARCH-COMP-029", "summary": "Delegated reporting executor", "responsibility": "Build PRD-owned bundles, execute configured AI-Collab profiles, validate source-backed results, and apply fallback policy.", "requirement_ids": ["PRD-REQ-036", "PRD-NFR-020"], "interface_ids": ["ARCH-IF-023"]},
    {"id": "ARCH-COMP-030", "summary": "Goal and worker correlation bridge", "responsibility": "Carry PRD IDs on Substrate goals/capsules and prepare one tracking branch assignment for each parallel writer.", "requirement_ids": ["PRD-REQ-037"], "interface_ids": ["ARCH-IF-024"]},
    {"id": "ARCH-COMP-031", "summary": "Adapter diagnostics and delivery", "responsibility": "Expose effective status, last projection outcome, compatibility failures, docs, templates, installer policy, and contract tests.", "requirement_ids": ["PRD-REQ-038"], "interface_ids": ["ARCH-IF-017", "ARCH-IF-018"]}
  ],
  "interfaces": [
    {"id": "ARCH-IF-017", "summary": "integrations.substrate policy", "producer": "operator or prd_config.py", "consumer": "PRD handshake and AI-Collab adapter", "contract": "enabled:boolean, mode:off|observe|coordinate, capabilities:string[], contract_version:integer, require_source_refs:boolean"},
    {"id": "ARCH-IF-018", "summary": "PRD adapter handshake", "producer": "prd_substrate.py", "consumer": "AI-Collab adapter", "contract": "Versioned JSON with plugin version, policy, effective capabilities, supported surfaces, and privacy invariants."},
    {"id": "ARCH-IF-019", "summary": "PRD record snapshot", "producer": "prd_substrate.py", "consumer": "AI-Collab projector", "contract": "Versioned bounded records keyed by repo-relative kind and ID, with status, summary, links, provenance, and content hash; excludes local/private state."},
    {"id": "ARCH-IF-020", "summary": "Substrate projection changes", "producer": "AI-Collab adapter", "consumer": "tracking mirror, live subscriptions, and watches", "contract": "Idempotent upsert/delete operations scoped by workspace and repo; unchanged generations are silent."},
    {"id": "ARCH-IF-021", "summary": "Repo-qualified traceability edges", "producer": "prd_graph.py and adapter", "consumer": "Substrate causal graph", "contract": "{cause: repo::id, effect: repo::id, label, source_ref}; deterministic full-snapshot reconcile."},
    {"id": "ARCH-IF-022", "summary": "Validated PRD command", "producer": "AI-Collab orchestration", "consumer": "PRD MCP state server", "contract": "Allowlisted MCP tool name and schema-valid arguments; rejected unless coordinate mode and mutations capability are effective."},
    {"id": "ARCH-IF-023", "summary": "Delegated reporting job", "producer": "PRD reporting bundle", "consumer": "AI-Collab profile executor and PRD result validator", "contract": "Existing contract_version 1 bundle/result with known source_refs and configured limits/fallback."},
    {"id": "ARCH-IF-024", "summary": "Worker tracking assignment", "producer": "AI-Collab goal dispatcher", "consumer": "spawned agent runtime", "contract": "PRD_WORKER_SESSION=1, PRD_STOP_GUARD=off, PRD_TRACKING_BRANCH_ID, PRD_TRACKING_BRANCH_OWNER, and correlated PRD source IDs."}
  ],
  "data_state_model": {
    "canonical_policy": ".prd_plugin/config.json#integrations.substrate",
    "canonical_project_truth": ".prd_plugin/state and .prd_plugin/ids/registry.json",
    "derived_runtime_state": "AI-Collab Substrate repo tracking, freshness, causal, workspace-tool, watch, goal, and payload records",
    "runtime_binding": "AI-Collab-local workspace/repo registration and credentials",
    "identity_rule": "PRD IDs are domain IDs; every projected key is qualified by the registered repository ID"
  },
  "decisions": [
    {"id": "ARCH-DEC-017", "summary": "Place adapter execution in AI-Collab and keep only stable contracts and policy in PRD Plugin.", "rationale": "AI-Collab owns the Substrate client, credentials, workspaces, subscriptions, routing, and model runtime; duplicating those in PRD Plugin would create a second runtime.", "source_ids": ["PRD-REQ-031", "PRD-REQ-038"]},
    {"id": "ARCH-DEC-018", "summary": "Use one master switch plus off, observe, and coordinate modes.", "rationale": "The master switch guarantees an inert disabled path; modes express the only materially different authority levels without a maze of booleans.", "source_ids": ["PRD-REQ-030", "PRD-NFR-018"]},
    {"id": "ARCH-DEC-019", "summary": "Mount PRD Plugin's official UTCP manual and MCP server instead of hand-defining duplicate readers or writers.", "rationale": "One generated specification prevents coverage and schema drift while retaining duplicate-safe mutation invariants.", "source_ids": ["PRD-REQ-031", "PRD-REQ-035"]},
    {"id": "ARCH-DEC-020", "summary": "Use generation-aware reconciliation with explicit deletion rather than clear-and-rebuild.", "rationale": "Clear-and-rebuild creates notification storms, while upsert-only mirrors retain deleted records forever; generation-aware diffing preserves silence and correctness.", "source_ids": ["PRD-REQ-032", "PRD-REQ-034"]},
    {"id": "ARCH-DEC-021", "summary": "Keep committed policy separate from AI-Collab-local bindings and credentials.", "rationale": "Repositories should share intent without leaking machine identity, endpoints, or secrets or becoming coupled to one workspace.", "source_ids": ["PRD-NFR-019", "PRD-NFR-020"]},
    {"id": "ARCH-DEC-022", "summary": "Reuse the existing reporting bundle/result contract for model work.", "rationale": "PRD Plugin already owns deterministic inputs, source validation, and fallback semantics; a second delegation protocol would add drift without capability.", "source_ids": ["PRD-REQ-036"]}
  ],
  "risks": [
    {"id": "ARCH-RISK-013", "summary": "A derived mirror is mistaken for canonical project truth.", "mitigation": "Mark projections derived, retain source hashes/refs, expose freshness, and route all writes back through MCP.", "status": "mitigated"},
    {"id": "ARCH-RISK-014", "summary": "Same-numbered PRD IDs collide across repositories.", "mitigation": "Qualify every projected record and graph node with repo_id; test two-repo collisions.", "status": "mitigated"},
    {"id": "ARCH-RISK-015", "summary": "Reconciliation misses deletions or causes notification storms.", "mitigation": "Generation-aware diff/tombstone operations and tests proving unchanged silence and single deletion events.", "status": "mitigated"},
    {"id": "ARCH-RISK-016", "summary": "Coordinate mode bypasses PRD access, consent, locking, or validation.", "mitigation": "Explicit capability gate and MCP-only writes; no raw canonical writer in the adapter.", "status": "mitigated"},
    {"id": "ARCH-RISK-017", "summary": "Schema or installed-version drift breaks integration silently.", "mitigation": "Versioned handshake, compatibility checks, diagnostics, and fail-closed coordination with fail-open observation fallback.", "status": "mitigated"},
    {"id": "ARCH-RISK-018", "summary": "Projection or delegated work leaks secrets, local sessions, or private reflection content.", "mitigation": "Allowlisted canonical sources, explicit exclusions, source-ref validation, and privacy contract tests.", "status": "mitigated"}
  ],
  "validation_strategy": [
    "RED/GREEN Python tests for config validation, handshake, snapshot completeness, graph qualification, privacy exclusions, and disabled behavior.",
    "RED/GREEN AI-Collab tests for generation reconciliation, deletion, unchanged silence, capability gating, official tool discovery, reporting execution, and worker environment.",
    "Contract fixtures run against two repositories with overlapping PRD IDs.",
    "Full hub and AI-Collab verification plus repeated CHML review/audit until no findings remain."
  ],
  "traceability": {
    "source_ids": ["REQ-091", "DEC-005", "PRD-REQ-030", "PRD-REQ-031", "PRD-REQ-032", "PRD-REQ-033", "PRD-REQ-034", "PRD-REQ-035", "PRD-REQ-036", "PRD-REQ-037", "PRD-REQ-038"],
    "implementation_task_ids": ["IMP-TASK-042", "IMP-TASK-043", "IMP-TASK-044", "IMP-TASK-045", "IMP-TASK-046", "IMP-TASK-047", "IMP-TASK-048", "IMP-TASK-049"],
    "tracking_ids": ["TRK-091"],
    "health_ids": []
  }
}