{ "schema_version": "0.1", "artifact_type": "architecture", "canonical": true, "artifact_id": "ARCH-009", "agent_summary": { "title": "Substrate parity integration architecture", "status": "approved", "summary": "A negotiated runtime bridge lets deterministic PRD workflows discover and call allowlisted AI-Collab capabilities, while a policy layer preserves local canonical authority, explicit fallbacks, bounded latency, and receipt-backed external execution.", "last_reviewed_at": "2026-07-15", "load_notes": "Canonical JSON; generate Markdown only on explicit human request." }, "context": "PRD Plugin 0.15.5 exposes an export-only Substrate contract with handshake, snapshot, and graph actions. AI-Collab 1.0.0 ships Conduit/Tool Hub discovery, Knowledge Hub, memory/context, causal impact, goals, bus, diagnostics, App Server, specialist workspaces, threads, watches, and related services. Current PRD workflows create some external request bundles but no runtime consumer returns and resumes them, leaving duplicated state reads and high-value capabilities disconnected.", "principles": [ "PRD Plugin remains canonical for project truth; AI-Collab supplies execution, retrieval, prediction, coordination, and observability.", "Exact deterministic local state and dependency facts outrank semantic or predictive results.", "Every external operation is allowlisted, version-negotiated, hash-bound, idempotent, timeout-bounded, and receipt-backed.", "Capabilities are enabled by workflow intent and profile, not globally invoked merely because they are available.", "Local-only operation is complete; unavailable or incompatible runtime features degrade explicitly without false success.", "One adapter contract serves CLI, MCP, workflows, hosts, downstream templates, and tests." ], "components": [ { "id": "ARCH-COMP-047", "summary": "Capability catalog and parity auditor", "responsibility": "Normalize shipped Substrate tool groups and PRD workflow needs into one versioned catalog; classify execution intent, availability, configuration, fallback, exclusions, and coverage; generate CHML parity findings.", "requirement_ids": ["PRD-REQ-058", "PRD-REQ-069", "PRD-REQ-071"], "interface_ids": ["ARCH-IF-040"] }, { "id": "ARCH-COMP-048", "summary": "Connection, identity, and compatibility manager", "responsibility": "Resolve configured endpoint/transport, negotiate contract/runtime versions, identify repository/workspace/auth mode, call health/index/tool discovery, redact secrets, and calculate effective capability availability.", "requirement_ids": ["PRD-REQ-059", "PRD-NFR-033", "PRD-NFR-037"], "interface_ids": ["ARCH-IF-041"] }, { "id": "ARCH-COMP-049", "summary": "Executable Substrate bridge", "responsibility": "Provide one transport-neutral discover/call/submit/status/result boundary for allowlisted Conduit/Tool Hub operations with typed envelopes, timeouts, idempotency, asynchronous correlation, and explicit errors.", "requirement_ids": ["PRD-REQ-060", "PRD-REQ-061", "PRD-NFR-034", "PRD-NFR-036"], "interface_ids": ["ARCH-IF-042", "ARCH-IF-043"] }, { "id": "ARCH-COMP-050", "summary": "Workflow capability action adapter", "responsibility": "Register narrowly typed Substrate actions in the deterministic workflow engine, enforce capability/profile/authority policy, bind requests to WFR steps, validate receipts, and apply declared local fallback.", "requirement_ids": ["PRD-REQ-060", "PRD-REQ-062", "PRD-REQ-069"], "interface_ids": ["ARCH-IF-042", "ARCH-IF-044"] }, { "id": "ARCH-COMP-051", "summary": "Federated knowledge, memory, and context adapter", "responsibility": "Route wiki/docs/manual search, memory recall/promotion, code/docs recall, context packing, and skillbook resolution through authorized Substrate services with provenance, freshness, backlinks, bounds, and local fallbacks.", "requirement_ids": ["PRD-REQ-063", "PRD-REQ-064", "PRD-NFR-033", "PRD-NFR-035"], "interface_ids": ["ARCH-IF-045"] }, { "id": "ARCH-COMP-052", "summary": "Judgment, reporting, and verification executor", "responsibility": "Consume hash-bound workflow judgment, delegated reporting, and test-scope requests; use configured models and impact/structural tools; validate results; resume the exact workflow step; and widen verification when confidence is insufficient.", "requirement_ids": ["PRD-REQ-065", "PRD-REQ-068", "PRD-NFR-034", "PRD-NFR-035"], "interface_ids": ["ARCH-IF-046", "ARCH-IF-047"] }, { "id": "ARCH-COMP-053", "summary": "Goal, bus, and execution binding", "responsibility": "Link PRD goals, WFR runs, tracking branches, evidence, and closeout to Substrate goal/execution/capsule identities, while keeping PRD status canonical and settling duplicate-safe receipts serially.", "requirement_ids": ["PRD-REQ-061", "PRD-REQ-066", "PRD-NFR-034"], "interface_ids": ["ARCH-IF-048"] }, { "id": "ARCH-COMP-054", "summary": "Optional worker, specialist, and evidence adapter", "responsibility": "Expose explicitly authorized agent/team routing, specialist cases, App Server evidence, watches/notices, threads, polls, and scratchpads through bounded workflow actions that enforce consent and tracking-branch ownership.", "requirement_ids": ["PRD-REQ-067", "PRD-NFR-033"], "interface_ids": ["ARCH-IF-049"] }, { "id": "ARCH-COMP-055", "summary": "Diagnostics, telemetry, and configuration advisor", "responsibility": "Collect doctor/index/freshness/tool/model/notices and bounded latency/cache/fallback receipts; explain effective policy and recommend profiles without changing configuration autonomously outside configured authority.", "requirement_ids": ["PRD-REQ-062", "PRD-REQ-068", "PRD-NFR-035", "PRD-NFR-037"], "interface_ids": ["ARCH-IF-041", "ARCH-IF-044"] }, { "id": "ARCH-COMP-056", "summary": "Downstream delivery and compatibility layer", "responsibility": "Synchronize scripts, contracts, workflow definitions, config catalog, CLI/MCP/UTCP, hooks, skills, host instructions, templates, installer migrations, docs/wiki/manual, versions, fixtures, and release checks.", "requirement_ids": ["PRD-REQ-070", "PRD-REQ-071", "PRD-NFR-036", "PRD-NFR-037"], "interface_ids": ["ARCH-IF-040", "ARCH-IF-041", "ARCH-IF-042"] }, { "id": "ARCH-COMP-057", "summary": "Repository service manifest authority", "responsibility": "Load, validate, query, and mutate canonical .prd_plugin/services.json declarations; preserve repository-owned entries during installation; reconcile declared consumption/provision with the capability catalog and effective runtime; and advertise a bounded hash-bearing projection through handshake, workflow, MCP, and UTCP surfaces.", "requirement_ids": ["PRD-REQ-072", "PRD-NFR-033", "PRD-NFR-034", "PRD-NFR-037"], "interface_ids": ["ARCH-IF-050"] } ], "interfaces": [ { "id": "ARCH-IF-040", "summary": "Capability parity manifest", "producer": "hub capability catalog generator and parity auditor", "consumer": "workflow catalog, configuration inventory, installer, documentation, and release gate", "contract": "Capability key, Substrate source/tool/version, PRD consumer workflows, intent class, default profile, authority, bounds, fallback, exclusions, config paths, and validation IDs." }, { "id": "ARCH-IF-041", "summary": "Negotiated connection descriptor", "producer": "connection manager and runtime doctor", "consumer": "bridge, workflow planner, status/config reporting, and compatibility tests", "contract": "Contract/runtime versions, transport/endpoint identity, repository/workspace identity, auth mode, health, index freshness, tool/model capabilities, notices, compatibility result, timestamps, and redacted diagnostics." }, { "id": "ARCH-IF-042", "summary": "Runtime operation request", "producer": "CLI, MCP, or registered workflow action", "consumer": "executable bridge and Conduit/Tool Hub", "contract": "Request ID, WFR/step/source hashes, capability/tool, validated arguments, intent, authority, timeout, bounds, idempotency key, expected result schema, fallback policy, and caller identity." }, { "id": "ARCH-IF-043", "summary": "Runtime operation receipt", "producer": "Substrate bridge or asynchronous result consumer", "consumer": "workflow validator, run store, telemetry, and canonical promotion action", "contract": "Matching request/idempotency/source/runtime identities, status, typed result or error, provenance, timing/cache/freshness data, tool/model versions, settlement state, and receipt hash." }, { "id": "ARCH-IF-044", "summary": "Effective capability policy", "producer": "unified config plus connection/capability resolver", "consumer": "workflow plan, action adapter, configuration UI/tools, and status reporting", "contract": "Enabled state, execution intent, profile, authority, bounds, timeout/retry, cache/freshness, model/executor, fallback, reason, and availability for each capability and workflow." }, { "id": "ARCH-IF-045", "summary": "Knowledge/context result", "producer": "Knowledge Hub, memory, code/docs recall, context engine, or skillbook resolver", "consumer": "planning, debugging, review, wiki, decision, reporting, and closeout workflows", "contract": "Bounded ranked items with repository/document/source identity, accessible link, excerpt/summary, provenance, authorization scope, freshness, backlinks/relationships, score axis, and local-fallback marker." }, { "id": "ARCH-IF-046", "summary": "Judgment/report execution result", "producer": "configured Substrate model/router executor", "consumer": "workflow judgment and reporting validators", "contract": "Exact request/run/step/source hashes, schema-valid result, cited allowed sources, model/profile/route metadata, token/latency telemetry, and explicit refusal/degradation state; no direct canonical writes." }, { "id": "ARCH-IF-047", "summary": "Impact verification result", "producer": "changed-file, structural, impact, and test-ownership resolvers", "consumer": "verification planner and executor", "contract": "Exact changed files, structural and predictive neighbours labelled by axis/source/confidence, mapped tests, unmapped files, widening reasons, selected verification tier, fingerprints, and full-suite fallback decision." }, { "id": "ARCH-IF-048", "summary": "Lifecycle binding record", "producer": "goal/bus/execution binding component", "consumer": "PRD tracking/goal tools, workflow engine, evidence ledger, and Substrate goal/bus tools", "contract": "Canonical PRD IDs plus external goal/execution/capsule IDs, source hashes, owner/branch, status projection, settlement/idempotency state, evidence links, timestamps, and authority declaration." }, { "id": "ARCH-IF-049", "summary": "Optional operation envelope", "producer": "authorized worker/specialist/evidence workflow action", "consumer": "Substrate agents, teams, specialists, App Server, watches, threads, or polls", "contract": "Declared workflow purpose, consent source, bounded assignment, repository/worktree/tracking-branch ownership, allowed tools/data, timeout/budget, stop guard, evidence policy, expected result schema, and settlement route." }, { "id": "ARCH-IF-050", "summary": "Repository service manifest", "producer": "repository owner through validated service CRUD plus additive installer defaults", "consumer": "Substrate handshake, capability resolver, workflow planner, federation/discovery, configuration/status tools, and parity auditor", "contract": "Schema version, stable repository identity, separately keyed consumes/provides entries, service and capability names, provider/consumer identity, required/optional intent, supported contract-version ranges, visibility, bounds, fallback, owner, metadata, and deterministic manifest hash." } ], "data_state_model": { "canonical_policy": ".prd_plugin/config.json plus the generated config catalog", "capability_manifest": ".prd_plugin/substrate/capabilities.json mirrored from the hub template", "connection_state": "ignored .prd_plugin/local/substrate connection/session cache; secrets never enter canonical state", "operation_state": "bounded request and receipt summaries attached to WFR records; large/transient payloads remain ignored local data or Substrate-owned", "lifecycle_links": ".prd_plugin/state/substrate-links.json with duplicate-safe PRD-to-runtime identities and no copied canonical content", "knowledge_authority": "source repositories remain authoritative; Knowledge Hub stores indexes/projections and returns provenance-bearing authorized results", "canonical_mutations": "existing PRD MCP/state actions only after deterministic validation; external receipts are inputs, never write authority", "fallback": "current local wiki/state/git/graph/reporting/test planning paths remain complete and declare degraded execution explicitly" ,"repository_service_manifest": ".prd_plugin/services.json is canonical repository-owned declaration data; shipped defaults are additive, identity/entries are never inferred as project truth, and runtime projections carry a content hash" }, "decisions": [ { "id": "ARCH-DEC-038", "summary": "Use one generated capability manifest as the parity and mapping authority.", "rationale": "A machine-readable inventory prevents documentation, config, workflow, skill, and runtime support from drifting independently.", "source_ids": ["PRD-REQ-058", "PRD-REQ-069", "BR-DEC-011"] }, { "id": "ARCH-DEC-039", "summary": "Evolve the adapter into a transport-neutral executable bridge instead of adding direct calls throughout individual workflows.", "rationale": "One narrow boundary centralizes versioning, authentication, validation, observability, idempotency, and fallback.", "source_ids": ["PRD-REQ-059", "PRD-REQ-060", "BR-DEC-012"] }, { "id": "ARCH-DEC-040", "summary": "Keep canonical state and lifecycle authority in PRD Plugin and store only identity links plus validated receipts for external execution.", "rationale": "This avoids dual truth while still using Substrate goals, bus, memory, and coordination services.", "source_ids": ["PRD-REQ-061", "PRD-REQ-066", "BR-DEC-013"] }, { "id": "ARCH-DEC-041", "summary": "Select capabilities per workflow and named latency profile, with conservative defaults and explicit execution intent.", "rationale": "Users need precise control over latency and cost; availability alone is not authority to execute.", "source_ids": ["PRD-REQ-062", "PRD-REQ-069", "BR-DEC-014"] }, { "id": "ARCH-DEC-042", "summary": "Use Knowledge Hub as the federated discovery layer while retaining local exact reads and local wiki fallback.", "rationale": "This provides the Obsidian-like cross-repository view without copying canonical documents or requiring one server per repository.", "source_ids": ["PRD-REQ-063", "PRD-REQ-064", "BR-DEC-015"] }, { "id": "ARCH-DEC-043", "summary": "Combine exact changes, dependency structure, ownership, and predictive impact; never use semantic neighbours as the sole verification signal.", "rationale": "Focused verification becomes efficient without sacrificing soundness when the graph is stale, incomplete, or uncertain.", "source_ids": ["PRD-REQ-065", "BR-DEC-016"] }, { "id": "ARCH-DEC-044", "summary": "Keep agents, teams, specialists, App Server, watches, threads, and polls optional and consent-gated.", "rationale": "These features are valuable in declared workflows but would broaden authority and latency if enabled implicitly.", "source_ids": ["PRD-REQ-067", "BR-DEC-017"] }, { "id": "ARCH-DEC-045", "summary": "Test the bridge against a contract fixture and compatible live runtime, and make cross-version degradation a first-class outcome.", "rationale": "The two repositories release independently; parity requires contract tests and explicit compatibility, not shared-source assumptions.", "source_ids": ["PRD-REQ-070", "PRD-REQ-071"] }, { "id": "ARCH-DEC-046", "summary": "Use a local canonical services.json rather than inferring repository services or centralizing declarations only in the Substrate.", "rationale": "The declaration must travel with every repository, work without a runtime or remote, remain owner-editable through validated tools, and still be discoverable by federation and handshake.", "source_ids": ["PRD-REQ-072", "BR-DEC-018"] } ], "risks": [ { "id": "ARCH-RISK-033", "summary": "Runtime unavailable, unhealthy, or incompatible blocks ordinary PRD work.", "mitigation": "Preflight negotiation, short timeouts, declared per-action fallback, cached fresh results, and a complete local-only profile.", "status": "planned" }, { "id": "ARCH-RISK-034", "summary": "Authentication data or unauthorized cross-repository knowledge leaks through requests or logs.", "mitigation": "Secret redaction, least-privilege identity, authorization-preserving Knowledge Hub results, bounded provenance, and security tests.", "status": "planned" }, { "id": "ARCH-RISK-035", "summary": "Direct AI-Collab reads of PRD JSON diverge from the adapter snapshot and canonical state rules.", "mitigation": "Versioned snapshot/record retrieval contract, parity tests, deprecate undocumented direct reads, and require identity/source hashes on receipts.", "status": "planned" }, { "id": "ARCH-RISK-036", "summary": "External calls increase latency or token cost across every workflow.", "mitigation": "Per-capability profiles, deterministic-first policy, freshness-aware cache, bounded results, telemetry, and no-call local profile.", "status": "planned" }, { "id": "ARCH-RISK-037", "summary": "Predictive impact omits a required test.", "mitigation": "Exact changes, structural callers, explicit ownership, unmapped-file detection, confidence thresholds, widening, and release full-suite policy.", "status": "planned" }, { "id": "ARCH-RISK-038", "summary": "PRD and Substrate goals or bus settlements become competing status authorities.", "mitigation": "One-way canonical PRD status, link records, idempotent projections, reconciliation diagnostics, and serial canonical promotion.", "status": "planned" }, { "id": "ARCH-RISK-039", "summary": "Optional worker or App Server actions silently broaden consent or corrupt parallel state.", "mitigation": "Default-off capability policy, explicit consent source, one-level bounded assignments, worktree/tracking-branch enforcement, and typed settlement.", "status": "planned" }, { "id": "ARCH-RISK-040", "summary": "Hub and downstream contracts, templates, skills, workflows, or versions drift again.", "mitigation": "Generated parity manifest, fixture-based cross-version tests, installer audits, host mirror checks, wiki/manual lint, package checks, and release gating.", "status": "planned" }, { "id": "ARCH-RISK-041", "summary": "Service manifests drift from actual workflow/runtime use or safe updates overwrite repository declarations.", "mitigation": "Schema and semantic audit, duplicate-safe keyed CRUD, declared-versus-effective reconciliation, manifest hashing, additive installer merge, template/package parity, and CHML release checks.", "status": "planned" } ], "validation_strategy": [ "RED/GREEN unit tests for capability classification, config resolution, handshake negotiation, request/receipt schemas, redaction, idempotency, timeouts, and fallback.", "Contract tests against a deterministic fake Conduit/Tool Hub plus focused live compatibility tests for the installed AI-Collab version.", "Workflow integration tests for knowledge/memory/context, judgment/reporting, impact verification, goals/bus, diagnostics, and optional capability consent boundaries.", "Installer and cross-host parity tests for templates, config, workflows, tools, skills, hooks, instructions, docs, wiki/manual, and version propagation.", "Focused verification per implementation task, followed by full release verification and repeated CRAFTE/CHML audit-fix-re-audit to zero." ], "traceability": { "source_ids": [ "REQ-099", "PRD-REQ-058", "PRD-REQ-059", "PRD-REQ-060", "PRD-REQ-061", "PRD-REQ-062", "PRD-REQ-063", "PRD-REQ-064", "PRD-REQ-065", "PRD-REQ-066", "PRD-REQ-067", "PRD-REQ-068", "PRD-REQ-069", "PRD-REQ-070", "PRD-REQ-071" ,"PRD-REQ-072" ], "implementation_task_ids": [ "IMP-TASK-068", "IMP-TASK-069", "IMP-TASK-070", "IMP-TASK-071", "IMP-TASK-072", "IMP-TASK-073", "IMP-TASK-074", "IMP-TASK-075", "IMP-TASK-076", "IMP-TASK-077", "IMP-TASK-078", "IMP-TASK-079", "IMP-TASK-080", "IMP-TASK-081", "IMP-TASK-082", "IMP-TASK-083", "IMP-TASK-084", "IMP-TASK-085", "IMP-TASK-086", "IMP-TASK-087", "IMP-TASK-088" ], "tracking_ids": ["TRK-111"], "health_ids": [] } }