Conversation
There was a problem hiding this comment.
Pull request overview
This PR introduces a “locked” contract layer for the Noema Agent architecture by adding a new ADR (ADR-0006) and a set of contract specification documents that define cross-layer boundaries, schemas, constraints, and authority rules to prevent architectural drift.
Changes:
- Added ADR-0006 to formalize the “Contract Lock” governance and change policy.
- Added initial contract specifications under
docs/contracts/(invocation boundary, API schema, constraints, authority model) plus a contracts README. - Updated
.gitignoreto discourage introduction of runtime/toolchain artifacts into this (documentation-focused) repo.
Reviewed changes
Copilot reviewed 6 out of 7 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/contracts/invocation-boundary.md | Defines invocation boundary invariants and conceptual request/response structures |
| docs/contracts/api-schema.md | Defines canonical cross-layer data structures and versioning/change policy |
| docs/contracts/constraint-contract.md | Defines constraint types, validation, composition, and enforcement expectations |
| docs/contracts/authority-model.md | Defines authority levels, hierarchy, and verification steps |
| docs/contracts/README.md | Overview/index of contract documents and “locked” status |
| docs/adr/adr-0006.md | ADR establishing the contract lock governance and compliance model |
| .gitignore | Adds ignores intended to prevent accidental runtime/tooling additions |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | privacy_scope | string | yes | Data privacy boundary | | ||
| | execution_mode | string | yes | local | cloud | hybrid | | ||
| | knowledge_scope | array | no | Explicit knowledge sources allowed | | ||
| | constraints | array | no | Execution constraints | |
There was a problem hiding this comment.
Markdown table cells include unescaped | (e.g., local | cloud | hybrid), which will render as extra columns and break the table. Escape the pipes or replace with commas/<br>/code formatting so the table renders correctly.
|
|
||
| We establish a **Contract Lock** on the architectural invariants of the RAGfish / Noema system. | ||
|
|
||
| Specifically, we freeze the following as **canonical specifications** at version 1.0.0: |
There was a problem hiding this comment.
This section says all canonical specifications are frozen at version 1.0.0, but later the ADR lists the API Schema contract as version 1.1.0. Please adjust the wording to avoid a versioning contradiction (e.g., freeze each contract at its own current version).
| Specifically, we freeze the following as **canonical specifications** at version 1.0.0: | |
| Specifically, we freeze the following as **canonical specifications** at their current versions: |
| # Invocation Boundary Specification | ||
| Version: 1.0.0 | ||
| Status: LOCKED | ||
| Owner: Noema Core Architecture |
There was a problem hiding this comment.
Status: value uses LOCKED here but other contract docs and the contracts README use Locked. For consistency (and easier grepping/validation), standardize the casing across all contract documents.
|
|
||
| - ExecutionContext | ||
| - KnowledgeReference | ||
| - InvocationRequest metadata |
There was a problem hiding this comment.
Section 2.4 states required context can be provided via “InvocationRequest metadata”, but the InvocationRequest field list in section 4 does not include metadata (and the API schema marks metadata optional). Please reconcile this so the contract is internally consistent about whether metadata exists and whether it’s required.
| - InvocationRequest metadata | |
| - Explicitly declared InvocationRequest fields (no hidden or implicit metadata channels) |
| | knowledge_scope | array | no | Explicit knowledge sources allowed | | ||
| | constraints | array | no | Execution constraints | |
There was a problem hiding this comment.
Invocation Boundary section 4 says knowledge_scope and constraints MUST be present, but this schema marks them Required = no. Either relax the Invocation Boundary wording or mark these fields required here to avoid contradictory “locked” contracts.
| | knowledge_scope | array | no | Explicit knowledge sources allowed | | |
| | constraints | array | no | Execution constraints | | |
| | knowledge_scope | array | yes | Explicit knowledge sources allowed | | |
| | constraints | array | yes | Execution constraints | |
|
|
||
| 1. **Version Clarity**: Schema version (1.0.0) makes compatibility explicit. Future versions (2.0.0, etc.) clearly signal breaking changes. | ||
|
|
||
| 2. **Extension Points**: API schema includes optional fields and "additionalData" maps that allow extension without breaking changes. |
There was a problem hiding this comment.
This ADR claims the API schema has extension points like optional “additionalData” maps, but docs/contracts/api-schema.md does not define any additionalData field. Either add the described extension point to the schema or remove/adjust this claim to keep the ADR accurate.
| 2. **Extension Points**: API schema includes optional fields and "additionalData" maps that allow extension without breaking changes. | |
| 2. **Extension Points**: API schema evolution should prefer optional fields and explicit, documented extension points to enable non-breaking changes, and any such extension points must be defined in `docs/contracts/api-schema.md`. |
|
|
||
| **Requirements**: | ||
| - Contract specifications exist and are complete | ||
| - All four documents present in `docs/contracts/` |
There was a problem hiding this comment.
Design-time verification says “All four documents present in docs/contracts/”, but this ADR also lists (and locks) docs/contracts/README.md, making at least five documents in that directory. Clarify whether the README is included in the verification checklist to avoid ambiguity.
| - All four documents present in `docs/contracts/` | |
| - All five locked contract documents present in `docs/contracts/` (including `README.md`) |
|
|
||
| --- | ||
|
|
||
| # Enforcement |
There was a problem hiding this comment.
# Enforcement is a top-level heading, which makes it a second document title rather than a section. It should likely be ## Enforcement (or consistent with the other section heading levels in this document).
| # Enforcement | |
| ## Enforcement |
| - Stateless execution is mandatory | ||
| - Evidence attachment required | ||
|
|
||
| **Enforcement**: Constraint violations must abort execution immediately and generate incident reports. |
There was a problem hiding this comment.
ADR states constraint violations must “generate incident reports”, but the locked constraint contract only specifies an ExecutionError. Please align these documents (either specify incident reporting in the constraint contract or soften the ADR language) so compliance requirements are unambiguous.
| **Enforcement**: Constraint violations must abort execution immediately and generate incident reports. | |
| **Enforcement**: Constraint violations must abort execution immediately by returning an `ExecutionError`; any incident reporting is handled by higher-level operational policy, not by this contract. |
| # Contract Enforcement Rules | ||
|
|
||
| 1. All executions MUST originate from InvocationRequest. | ||
| 2. Router mediation is mandatory. | ||
| 3. Authority escalation is forbidden. | ||
| 4. Stateless execution is required. | ||
| 5. Implicit memory injection is prohibited. | ||
|
|
||
| --- | ||
|
|
||
| # Change Policy | ||
|
|
||
| - Backward incompatible changes require major version increment. | ||
| - Additive changes require minor version increment. | ||
| - Editorial changes require patch increment. | ||
| - Contract-breaking changes require ADR approval. No newline at end of file |
There was a problem hiding this comment.
# Contract Enforcement Rules and # Change Policy restart at H1 level, which makes the document appear to have multiple titles. For consistent Markdown structure (and TOC generation), these should likely be ## headings like the other sections.
This pull request formalizes and locks the architectural contract layer for the Noema Agent system. It introduces explicit, immutable specifications for the boundaries, APIs, constraints, and authority distribution between core architectural layers. The goal is to prevent architectural drift, enable parallel development, and preserve human accountability by requiring all implementations to comply with these locked contracts. The most important changes are grouped below by theme.
Architectural Contract Lock and Governance
adr-0006.mdto establish a "Contract Lock" ADR, freezing the architectural invariants and specifying strict change policies, verification procedures, and rationale for immutability. This ADR mandates explicit, immutable contracts for invocation boundary, API schema, constraint model, and authority distribution, and outlines the process for future changes.Contract Specification Documents
invocation-boundary.md: Defines the strict interface and invariants between client, router, execution engine, and knowledge layers.api-schema.md: Specifies canonical API structures, required fields, enforcement rules, and versioning policy for all cross-layer data.constraint-contract.md: Formalizes constraint types, validation, composition, and enforcement rules for execution.authority-model.md: Establishes the authority hierarchy, rules, and verification procedures to preserve human accountability.Documentation and Guidance
contracts/README.mdto document the purpose, scope, and status of the contract layer, listing all contract files and emphasizing their immutable, locked nature.