diff --git a/docs/adr/0001-noema-consumer-boundary.md b/docs/adr/0001-noema-consumer-boundary.md new file mode 100644 index 000000000..a6145625e --- /dev/null +++ b/docs/adr/0001-noema-consumer-boundary.md @@ -0,0 +1,82 @@ +# ADR-0001: Consume Noema and model orchestration through owner contracts + +- Status: Proposed +- Date: 2026-09-04 +- Decision owner: Naruon maintainers +- Scope: Naruon's workspace-agent integration boundary + +## Context + +Naruon owns workspace-agent tools, tenant and workspace authorization, and the +mail, calendar, task, and knowledge-graph domain rules those tools invoke. The +same product name also appears in `ContextualWisdomLab/noema`, whose protected +`main` currently defines Noema as an evidence-producing credential and +maintenance control plane for governed GitHub automation. + +The repositories compose, but neither may infer a shared runtime from a shared +name. Noema's protected contract says provider discovery and routing belong to +`ContextualWisdomLab/contextual-orchestrator`; model-backed Noema jobs consume +its published gateway contract and reject direct-provider fallback. A proposed +`noema-core` package exists only on draft Noema PR #536. It is not a released +dependency and does not prove a Naruon adoption contract. + +Naruon PRs #1384 and #1486 remain draft, independently active consumer lanes. +They must not copy an owner's source, consume an owner's branch, or transfer +review and check evidence between heads. + +## Decision + +1. Naruon retains ownership of workspace-agent prompts, tools, domain policy, + tenant/workspace authorization, audit behavior, and user-facing outcomes. +2. Provider-neutral model discovery and routing are consumed only through a + released `contextual-orchestrator` API and tenant/workspace-authorized + credential boundary. Naruon does not silently fall back to a direct provider. +3. Noema credential, GitHub review, and maintenance capabilities are consumed + only through Noema's released contracts. Naruon does not import Noema owner + source or read its database. +4. The proposed `noema-core` package is not adopted until its owner PR merges, + an immutable release is published, and Naruon verifies a versioned contract. + Shared construction code alone does not move Naruon domain logic into Noema. +5. Quarantine execution remains a separately published isolation capability; + this ADR does not assign it to Naruon or fold it into workspace-agent code. + +## Consequences + +- PR #1384 is the Naruon routing lane and must fail closed when the released + orchestrator contract is unavailable. +- PR #1486 may add Naruon-owned calendar policy as a workspace-agent tool, but + it cannot establish a second model-routing authority. +- Noema PR #536 is upstream proposed evidence only. A later Naruon adoption PR + must pin a released version and add contract tests at the consumer boundary. +- Earlier PR #1527 remains historical investigation evidence; this ADR replaces + its contradictory separate-runtime/shared-runtime conclusions with the live + owner/consumer boundary. + +## Alternatives considered + +### Treat all Noema-named code as one bounded context + +Rejected. The protected owner contract describes a GitHub automation control +plane, while Naruon owns workspace-agent domain behavior. A common name is not +a versioned interoperability contract. + +### Permanently separate every implementation detail + +Rejected. This would also forbid legitimate consumption of released owner +contracts. Reuse is allowed at published API/package boundaries after release +and conformance evidence exist. + +### Consume draft owner branches directly + +Rejected. Draft heads are mutable, carry no immutable release identity, and +cannot transfer their checks or approvals to a consumer. + +## Evidence and references + +- `ContextualWisdomLab/noema`, protected `main` README, verified 2026-09-04. +- `ContextualWisdomLab/noema` PR #536, draft proposal for `noema-core`, verified + 2026-09-04. +- `ContextualWisdomLab/naruon` PRs #1384, #1486, and #1527, verified 2026-09-04. +- Evans, E. (2003). *Domain-driven design: Tackling complexity in the heart of + software*. Addison-Wesley. +- Vernon, V. (2013). *Implementing domain-driven design*. Addison-Wesley. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 000000000..9050586c6 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,8 @@ +# Architecture decision records + +| ADR | Status | Decision | +| --- | --- | --- | +| [ADR-0001](0001-noema-consumer-boundary.md) | Proposed | Consume Noema and model orchestration through released owner contracts | + +`Proposed` records design intent. Only protected-branch implementation, +contract checks, and immutable releases establish shipped capability. diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md new file mode 100644 index 000000000..7e2b08f3b --- /dev/null +++ b/docs/product-technical-gap-baseline.md @@ -0,0 +1,40 @@ +# Product and technical gap baseline + +Snapshot: 2026-09-04. This file is a point-in-time planning record, not merge, +release, deployment, or commercial authority. + +## Evidence boundary + +- Naruon protected `develop`: `6cb9cc93a398e72c1c0daa564da7acbca65376fb`. +- Noema protected `main`: `e1ac9d50f6c646f04be8c137c8acdc7200182fcd`. +- Candidate heads are mutable and lose review/check evidence whenever changed. + +## Current gap + +| Gap | Customer impact | Protected state | Candidate evidence | Acceptance criterion | Next owner action | +| --- | --- | --- | --- | --- | --- | +| GAP-001 Noema consumer boundary | Workspace assistance can bypass governed model routing or depend on unreleased code, making behavior and supportability unpredictable. | Naruon has workspace-agent code; Noema says routing belongs to `contextual-orchestrator`. No released shared Noema runtime is proven. | Naruon #1384 `0fd330137cdd19068fa8903dc70e1dc88f42cdc9` and #1486 `b32954dbf6066bc0d953887e8ca06820588f2c5f` are draft. Noema #536 `a14cbe020d81fb7276ea4216f56d3f41c762c622` is draft. Naruon #1527 `23680b13b443bb4eb7659b9a75073ecc1b67e133` has an unrelated-history base and contradictory decisions. | A released orchestrator contract is tenant/workspace-authorized; direct-provider fallback fails closed; Naruon domain tools remain Naruon-owned; any shared package is immutable and contract-tested; current-head checks and independent review pass. | Repair the routing lane in #1384, reconcile #1486 without copying routing ownership, and consume Noema output only after an owner release. | + +## Decision and flow + +The normative proposal is [ADR-0001](adr/0001-noema-consumer-boundary.md). + +```mermaid +flowchart LR + User[Workspace user] --> Agent[Naruon workspace agent] + Agent --> Tools[Naruon mail, calendar, task, and graph tools] + Agent --> ACL[Tenant and workspace authorized client] + ACL --> CO[Released contextual-orchestrator API] + Noema[Released Noema contract] -. governed automation capability .-> Agent + CO --> Model[Capability-selected model] +``` + +## Verification plan + +1. Add an architecture regression that rejects direct provider construction in + the Naruon workspace-agent path. +2. Exercise the released orchestrator request and failure path with tenant and + workspace authorization in focused tests and a real integration smoke test. +3. Verify any Noema package/API against an immutable release, not an open PR. +4. Re-fetch each candidate head, reviews, required checks, and merge base before + making readiness or protected-merge claims.