{ "schema_version": "0.1", "artifact_type": "architecture", "canonical": true, "artifact_id": "ARCH-011", "agent_summary": { "title": "Structured Reasoning Diagnostic kernel architecture", "status": "approved", "summary": "Keep Reason Guard as one local deterministic hook kernel: normalize explicit directives, match bounded evidence, coalesce obligation diagnostics, and project coverage-qualified clearance through existing host and status surfaces.", "last_reviewed_at": "2026-07-24", "load_notes": "No RSP, standalone process, network boundary, remote ingestion, context broker, symbol-impact engine, or generic code-action service is part of this architecture." }, "context": "Reason Guard already provides cross-host hook dispatch, session-scoped state, event digests, evidence binding, enforcement modes, privacy controls, reporting, and completion-boundary checks. Its present obligation records are prose-first, expected results depend on a literal marker, evidence acceptance is not typed, and repeated boundary findings are stored as separate violations. The next slice strengthens those existing local seams instead of adding a service.", "principles": [ "One local kernel and one state authority; no parallel server architecture.", "Only explicit structured directives can create blocking obligations; heuristic inference remains lower-confidence and report-only.", "Acceptance predicates are a fixed, bounded data contract and are never executable code.", "Evidence remains host-bound, digest-backed, sanitized, and replay-safe.", "Diagnostics optimize human and agent comprehension without discarding bounded audit history.", "Clearance states what was observed and what was not; reduced coverage is never silently promoted to clear.", "The hook path remains model-free, network-free, bounded, and measurable." ], "components": [ { "id": "ARCH-COMP-065", "summary": "Directive normalizer and schema migrator", "responsibility": "Parse the versioned host-neutral directive, enforce field and collection bounds, label source confidence, translate supported legacy local state into the new schema atomically, and fail safely on malformed or future versions.", "requirement_ids": ["PRD-REQ-085", "PRD-REQ-086", "PRD-REQ-089", "PRD-NFR-045"], "interface_ids": ["ARCH-IF-057", "ARCH-IF-060"] }, { "id": "ARCH-COMP-066", "summary": "Obligation ledger and evidence matcher", "responsibility": "Store bounded structured obligations, bind sanitized tool evidence by host tool-use identity and digest, and evaluate only allowlisted deterministic predicates to advance the obligation lifecycle.", "requirement_ids": ["PRD-REQ-085", "PRD-REQ-087", "PRD-REQ-091", "PRD-NFR-043"], "interface_ids": ["ARCH-IF-057", "ARCH-IF-058", "ARCH-IF-060"] }, { "id": "ARCH-COMP-067", "summary": "Obligation-scoped diagnostic coalescer", "responsibility": "Maintain one active diagnostic per code and obligation, update bounded occurrence metadata idempotently, and retain a sanitized resolved summary for audit without producing repetitive agent-facing errors.", "requirement_ids": ["PRD-REQ-088", "PRD-NFR-044", "PRD-NFR-045"], "interface_ids": ["ARCH-IF-059", "ARCH-IF-060"] }, { "id": "ARCH-COMP-068", "summary": "Completion-clearance projector", "responsibility": "Derive clear, conditional, or blocked status from blocking obligations, active diagnostics, deferred work, enforcement mode, host coverage, and limitations, then bind the receipt to the sanitized report digest.", "requirement_ids": ["PRD-REQ-090", "PRD-REQ-093", "PRD-NFR-047"], "interface_ids": ["ARCH-IF-059"] }, { "id": "ARCH-COMP-069", "summary": "Cross-host and downstream surface adapters", "responsibility": "Carry the same directive, event, receipt, mode, report, configuration, and human-readable UI semantics across Claude, Codex, OpenCode, the hub copy, the repository skeleton, installer payloads, docs, and wiki.", "requirement_ids": ["PRD-REQ-092", "PRD-REQ-093", "PRD-NFR-046"], "interface_ids": ["ARCH-IF-057", "ARCH-IF-058", "ARCH-IF-059"] }, { "id": "ARCH-COMP-070", "summary": "Host ledger and session retention envelope", "responsibility": "Select a host-specific local report, migrate supported legacy state, retain bounded session records, isolate concurrent sessions, and project the active session through the backward-compatible current-report view.", "requirement_ids": ["PRD-REQ-094", "PRD-REQ-096", "PRD-NFR-045", "PRD-NFR-048"], "interface_ids": ["ARCH-IF-060", "ARCH-IF-061", "ARCH-IF-062"] }, { "id": "ARCH-COMP-071", "summary": "Trusted Claude visible-history adapter", "responsibility": "Resolve a Claude JSONL transcript below the configured Claude projects root and normalize only visible assistant text blocks into ordered Reason Guard observations while rejecting every other content shape.", "requirement_ids": ["PRD-REQ-095", "PRD-NFR-043", "PRD-NFR-044", "PRD-NFR-048"], "interface_ids": ["ARCH-IF-061"] } ], "interfaces": [ { "id": "ARCH-IF-057", "summary": "Host-neutral reasoning evidence directive", "producer": "Claude, Codex, or OpenCode reasoning-summary adapter", "consumer": "Directive normalizer and obligation ledger" }, { "id": "ARCH-IF-058", "summary": "Sanitized bound tool-evidence event", "producer": "Existing host hook dispatcher and tool lifecycle", "consumer": "Obligation evidence matcher" }, { "id": "ARCH-IF-059", "summary": "Human-readable diagnostics and completion-clearance projection", "producer": "Diagnostic coalescer and completion-clearance projector", "consumer": "Existing Reason Guard report, status, configuration, UI, and enforcement surfaces" }, { "id": "ARCH-IF-060", "summary": "Versioned local Reason Guard state", "producer": "Directive normalizer, migrator, ledger, and diagnostic coalescer", "consumer": "Reason Guard hook, report generation, status projection, and replay recovery" }, { "id": "ARCH-IF-061", "summary": "Host-scoped session ledger and normalized visible-history stream", "producer": "Claude, Codex, and OpenCode host adapters", "consumer": "Existing Reason Guard session-state kernel, status projection, and UI export" }, { "id": "ARCH-IF-062", "summary": "Allowlisted provider-surface and run-settings identity", "producer": "Explicit hook metadata, host-owned environment markers, or trusted transcript surface/model/effort metadata", "consumer": "Reason Guard session state, status projection, and UI export" } ], "decisions": [ { "id": "ARCH-DEC-055", "summary": "Evolve the existing Reason Guard hook into the diagnostic kernel and do not create an RSP or standalone server.", "rationale": "The shipped hook already owns the required local event, state, evidence, mode, privacy, and completion seams; another service would duplicate authority and add latency and failure modes outside the requested slice.", "source_ids": ["REQ-173", "PRD-REQ-093"] }, { "id": "ARCH-DEC-056", "summary": "Allow only valid explicit directives to create blocking obligations; keep heuristic inference report-only.", "rationale": "Natural-language inference is useful for visibility but is not reliable enough to become completion authority.", "source_ids": ["PRD-REQ-085", "PRD-REQ-086"] }, { "id": "ARCH-DEC-057", "summary": "Use a small allowlisted predicate data contract instead of free-form acceptance language.", "rationale": "Deterministic predicates make clearance testable and bounded while preventing arbitrary evaluation and hook-path model calls.", "source_ids": ["PRD-REQ-087", "PRD-NFR-043", "PRD-NFR-044"] }, { "id": "ARCH-DEC-058", "summary": "Key active diagnostics by diagnostic code and obligation identity.", "rationale": "This preserves the causal unit and occurrence history while preventing repeated completion events from flooding humans or agents with duplicate errors.", "source_ids": ["PRD-REQ-088"] }, { "id": "ARCH-DEC-059", "summary": "Use clear, conditional, and blocked clearance states and always expose coverage and limitations.", "rationale": "A binary certificate would overclaim when summaries or other inputs were absent; conditional status truthfully represents incomplete observation.", "source_ids": ["PRD-REQ-090", "PRD-NFR-047"] }, { "id": "ARCH-DEC-060", "summary": "Migrate local state atomically at the existing state boundary and preserve supported sanitized history.", "rationale": "A versioned in-place boundary retains continuity and rollback evidence without introducing a second state owner or persisting prohibited raw content.", "source_ids": ["PRD-REQ-089", "PRD-NFR-045"] }, { "id": "ARCH-DEC-061", "summary": "Separate state by host runtime and retain bounded session records inside each host ledger.", "rationale": "Host runtime names bind stable transcript and hook contracts, while session records prevent one session from replacing another without creating one file per event or duplicating the classifier.", "source_ids": ["REQ-176", "PRD-REQ-094", "PRD-REQ-096", "WFR-445"] }, { "id": "ARCH-DEC-062", "summary": "Store surface, latest model, and effort as bounded session metadata, not as another ledger or inferred label.", "rationale": "Provider owns the stable report file, session owns the durable record, and allowlisted surface/model/effort fields distinguish execution context without multiplying state files or guessing from missing metadata.", "source_ids": ["REQ-176", "PRD-REQ-097"] } ], "risks": [ { "id": "ARCH-RISK-048", "summary": "Heuristic extraction creates false blocking obligations.", "mitigation": "Only schema-valid explicit directives may block; heuristic records are labelled lower-confidence and report-only.", "status": "open" }, { "id": "ARCH-RISK-049", "summary": "Acceptance rules become an arbitrary expression language or a hidden security boundary.", "mitigation": "Use a closed predicate allowlist, strict shape and size validation, no eval, no executable regex, no shell, and no model or network call.", "status": "open" }, { "id": "ARCH-RISK-050", "summary": "State migration loses evidence history or corrupts concurrent sessions.", "mitigation": "Use fixtures for supported legacy versions, atomic replacement under the existing lock, idempotent migration, explicit malformed/future-version handling, and replay/concurrency tests.", "status": "open" }, { "id": "ARCH-RISK-051", "summary": "A completion certificate overstates assurance under reduced coverage.", "mitigation": "Name the output a clearance receipt, require full coverage for clear status, and surface missing inputs and limitations in every projection.", "status": "open" }, { "id": "ARCH-RISK-052", "summary": "Additional structure increases hook latency or downstream host drift.", "mitigation": "Keep collections and predicates bounded, measure the focused path, reuse the existing adapters and status surfaces, and enforce hub/skeleton/Claude/Codex/OpenCode parity in release gates.", "status": "open" }, { "id": "ARCH-RISK-053", "summary": "Historical Claude ingestion accidentally treats non-visible content as a reasoning summary or leaks transcript material.", "mitigation": "Trust only canonical paths below the Claude projects root, allowlist assistant/text records, reject thinking and every unknown block, persist only sanitized diagnostic state and digests, and carry privacy sentinels through fixtures and the offline historical reproduction.", "status": "open" } ], "validation_strategy": [ "Start every implementation increment with a focused failing test that proves the missing behavior and fails for that behavior.", "Contract and migration fixtures cover valid, invalid, oversized, malformed, future-version, replayed, interrupted, and concurrent inputs.", "Evidence fixtures cover matching and mismatched tool identity, outcome, digest, predicate values, duplicate delivery, failure, and sanitized persistence.", "Diagnostic fixtures prove coalescing, bounded occurrence history, lifecycle resolution, and readable projection.", "Clearance fixtures cover full, reduced, and missing coverage; all modes; open, deferred, resolved, and replayed obligations; and report-digest binding.", "Cross-host and install fixtures prove Claude, Codex, OpenCode, hub, skeleton, status, configuration, and UI parity.", "Host-ledger fixtures prove migration, bounded session retention, cross-host isolation, concurrency, and readable session projection.", "Claude transcript fixtures plus an offline old-session run prove assistant/text-only ingestion without launching Claude or persisting transcript material.", "Run-metadata fixtures prove Codex originator/turn-context and Claude entrypoint/assistant mapping for Desktop, CLI, latest model, effort, explicit overrides, and honest unknown fallback.", "Run focused performance and privacy sentinels, the affected suites, full hub gates, and audit-fix-reaudit loops until CHML is zero before release." ], "approval_gate": { "status": "approved", "implementation_authorized": true, "approved_at": "2026-07-24", "approved_by": "user" }, "traceability": { "source_ids": ["PRD-011", "REQ-173", "REQ-176", "DBR-002", "WFR-408", "WFR-445", "PRD-REQ-085", "PRD-REQ-086", "PRD-REQ-087", "PRD-REQ-088", "PRD-REQ-089", "PRD-REQ-090", "PRD-REQ-091", "PRD-REQ-092", "PRD-REQ-093", "PRD-REQ-094", "PRD-REQ-095", "PRD-REQ-096", "PRD-REQ-097"], "decision_ids": ["ARCH-DEC-055", "ARCH-DEC-056", "ARCH-DEC-057", "ARCH-DEC-058", "ARCH-DEC-059", "ARCH-DEC-060", "ARCH-DEC-061", "ARCH-DEC-062"], "implementation_task_ids": ["IMP-TASK-104", "IMP-TASK-105", "IMP-TASK-106", "IMP-TASK-107", "IMP-TASK-108", "IMP-TASK-109", "IMP-TASK-110", "IMP-TASK-111", "IMP-TASK-112", "IMP-TASK-117", "IMP-TASK-118", "IMP-TASK-119"], "tracking_ids": ["TRK-163"], "health_ids": [] } }