From 339b7de700eddc5de6221f41f3bf52ccf51371f2 Mon Sep 17 00:00:00 2001 From: Jeffrey Phillips Freeman Date: Mon, 16 Feb 2026 21:54:31 -0500 Subject: [PATCH] Docs: Added ADRs and improved TOC handling --- docs/adr/ADR-001-layered-architecture.md | 42 +- docs/adr/ADR-002-namespace-system.md | 43 +- docs/adr/ADR-003-dependency-injection.md | 42 +- docs/adr/ADR-004-data-validation.md | 42 +- docs/adr/ADR-005-technical-stack.md | 45 +- docs/adr/ADR-006-plan-lifecycle.md | 45 +- .../ADR-007-decision-tree-and-correction.md | 41 +- docs/adr/ADR-008-resource-system.md | 42 +- docs/adr/ADR-009-project-model.md | 42 +- .../ADR-010-actor-and-agent-architecture.md | 43 +- docs/adr/ADR-011-tool-system.md | 45 +- docs/adr/ADR-012-skill-system.md | 42 +- docs/adr/ADR-013-validation-abstraction.md | 42 +- docs/adr/ADR-014-context-management-acms.md | 42 +- docs/adr/ADR-015-sandbox-and-checkpoint.md | 41 +- docs/adr/ADR-016-invariant-system.md | 42 +- docs/adr/ADR-017-automation-profiles.md | 41 +- docs/adr/ADR-018-semantic-error-prevention.md | 43 +- docs/adr/ADR-019-storage-and-persistence.md | 42 +- docs/adr/ADR-020-session-model.md | 41 +- docs/adr/ADR-021-cli-and-output-rendering.md | 41 +- ...ADR-022-langchain-langgraph-integration.md | 42 +- docs/adr/ADR-023-server-mode.md | 42 +- docs/adr/ADR-024-configuration-system.md | 42 +- docs/adr/ADR-025-observability-and-logging.md | 41 +- docs/adr/index.md | 43 +- docs/javascripts/toc-collapse.js | 408 ++++++++++++++++-- docs/reference/resource_model.md | 81 ++++ docs/stylesheets/extra.css | 126 +++--- mkdocs.yml | 21 +- 30 files changed, 1546 insertions(+), 189 deletions(-) create mode 100644 docs/reference/resource_model.md diff --git a/docs/adr/ADR-001-layered-architecture.md b/docs/adr/ADR-001-layered-architecture.md index c09c92aab..b071cf380 100644 --- a/docs/adr/ADR-001-layered-architecture.md +++ b/docs/adr/ADR-001-layered-architecture.md @@ -1,9 +1,10 @@ # ADR-001: Layered Architecture -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-003, ADR-005, ADR-019, ADR-022 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -99,3 +100,36 @@ None — specification-driven requirement. The four-layer hexagonal architecture - **Dependency injection audit**: The DI container configuration is reviewed to ensure all cross-layer dependencies flow through declared providers, not direct imports. - **Architecture tests**: Dedicated test suite verifying layer dependency rules using static analysis (e.g., `import-linter` or custom AST checks). - **Code review**: Pull requests that introduce new cross-layer dependencies require explicit justification. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-003](ADR-003-dependency-injection.md) | Dependency Injection | Provides the composition root that wires components across all four layers | +| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | Defines the concrete technologies used in each architectural layer | +| [ADR-019](ADR-019-storage-and-persistence.md) | Storage and Persistence | Implements the Infrastructure Layer's persistence adapters | +| [ADR-022](ADR-022-langchain-langgraph-integration.md) | LangChain/LangGraph Integration | Implements the Infrastructure Layer's LLM runtime adapters | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Four-layer separation is the right foundation to keep domain logic portable across deployment modes | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-002-namespace-system.md b/docs/adr/ADR-002-namespace-system.md index ff6db9f27..1a1dc9af6 100644 --- a/docs/adr/ADR-002-namespace-system.md +++ b/docs/adr/ADR-002-namespace-system.md @@ -1,9 +1,10 @@ # ADR-002: Namespace System -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-009, ADR-010, ADR-011, ADR-012, ADR-023 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -88,3 +89,37 @@ None — specification-driven requirement. The universal namespace system is a f - **Name format tests**: Unit tests verify that entity name parsing correctly handles all forms (`name`, `namespace/name`, `server:namespace/name`) and rejects malformed inputs. - **Integration tests**: Multi-namespace scenarios (local + server, multiple servers) are exercised in integration test suites. - **Code review**: New entity types must demonstrate they follow the namespace convention before merging. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-009](ADR-009-project-model.md) | Project Model | Projects are namespace-scoped entities that use the naming convention | +| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Actors and agents are identified and resolved via namespaced names | +| [ADR-011](ADR-011-tool-system.md) | Tool System | Tools use namespaced identifiers for discovery and conflict resolution | +| [ADR-012](ADR-012-skill-system.md) | Skill System | Skills use namespaced names and resolve tool name conflicts via qualification | +| [ADR-023](ADR-023-server-mode.md) | Server Mode | Server mode introduces server-prefixed namespaces for multi-server resolution | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | A universal naming scheme avoids ambiguity and makes entity resolution predictable across all contexts | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-003-dependency-injection.md b/docs/adr/ADR-003-dependency-injection.md index 5a6f6f411..cae1d4671 100644 --- a/docs/adr/ADR-003-dependency-injection.md +++ b/docs/adr/ADR-003-dependency-injection.md @@ -1,9 +1,10 @@ # ADR-003: Dependency Injection -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-001, ADR-005, ADR-019, ADR-022 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -87,3 +88,36 @@ The container's `override()` context manager allows swapping providers for indiv - **Import linting**: CI rules verify that `domain` modules do not import from `dependency_injector`. - **Code review**: New services must include their container registration in the same pull request that introduces them. - **Test coverage**: Integration tests verify that the production container configuration resolves all dependencies correctly. Test configurations verify that override mechanisms work as expected. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-001](ADR-001-layered-architecture.md) | Layered Architecture | DI enforces the layered dependency rule by wiring outer-to-inner dependencies | +| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | Specifies `dependency-injector` as the chosen DI framework | +| [ADR-019](ADR-019-storage-and-persistence.md) | Storage and Persistence | Repository implementations are injected via the DI container | +| [ADR-022](ADR-022-langchain-langgraph-integration.md) | LangChain/LangGraph Integration | LLM providers and LangGraph components are registered through the DI container | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | A single composition root with declarative containers keeps wiring explicit and testable | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-004-data-validation.md b/docs/adr/ADR-004-data-validation.md index f9d28463d..e9e27bdff 100644 --- a/docs/adr/ADR-004-data-validation.md +++ b/docs/adr/ADR-004-data-validation.md @@ -1,9 +1,10 @@ # ADR-004: Data Validation -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-001, ADR-005, ADR-011, ADR-024 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -78,3 +79,36 @@ Pydantic handles serialization to and from JSON, YAML (via dict intermediary), a - **Schema drift tests**: Automated tests verify that JSON Schema generated from Pydantic tool models matches the schemas expected by MCP and LangChain tool-calling protocols. - **Validation coverage**: Unit tests exercise validation edge cases — missing required fields, wrong types, out-of-range values, malformed nested objects — for every domain model and configuration object. - **Code review**: New data structures that cross layer boundaries must be Pydantic models. Raw dict usage at boundaries is flagged during review. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-001](ADR-001-layered-architecture.md) | Layered Architecture | Pydantic models enforce Domain Layer contracts at layer boundaries | +| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | Specifies Pydantic V2 as the chosen validation library | +| [ADR-011](ADR-011-tool-system.md) | Tool System | Tool input/output schemas are Pydantic models that generate JSON Schema | +| [ADR-024](ADR-024-configuration-system.md) | Configuration System | Pydantic Settings powers environment variable loading and config validation | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Pydantic V2 strict mode gives us runtime type safety with minimal boilerplate and native JSON Schema support | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-005-technical-stack.md b/docs/adr/ADR-005-technical-stack.md index 7f1680b2e..26553dafc 100644 --- a/docs/adr/ADR-005-technical-stack.md +++ b/docs/adr/ADR-005-technical-stack.md @@ -1,9 +1,10 @@ # ADR-005: Technical Stack -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-001, ADR-003, ADR-004, ADR-019, ADR-021, ADR-022, ADR-025 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -153,3 +154,39 @@ None — specification-driven requirement. The technical stack is enumerated in - **Vulnerability scanning**: Automated dependency vulnerability scanning (e.g., `pip-audit` or `safety`) runs in CI. - **Build verification**: Docker image builds are tested in CI to catch platform-specific build failures for native extensions. - **Performance benchmarks**: ASV tracks key performance metrics across commits to detect regressions from dependency changes. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-001](ADR-001-layered-architecture.md) | Layered Architecture | Stack choices are organized according to the four-layer structure | +| [ADR-003](ADR-003-dependency-injection.md) | Dependency Injection | `dependency-injector` is a core stack choice for service wiring | +| [ADR-004](ADR-004-data-validation.md) | Data Validation | Pydantic V2 is a core stack choice for validation and modeling | +| [ADR-019](ADR-019-storage-and-persistence.md) | Storage and Persistence | SQLAlchemy and SQLite/PostgreSQL are the chosen persistence stack | +| [ADR-021](ADR-021-cli-and-output-rendering.md) | CLI and Output Rendering | Typer and Rich are the chosen CLI stack | +| [ADR-022](ADR-022-langchain-langgraph-integration.md) | LangChain/LangGraph Integration | LangChain and LangGraph are the chosen LLM orchestration stack | +| [ADR-025](ADR-025-observability-and-logging.md) | Observability and Logging | structlog is the chosen logging stack | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | This stack balances maturity, ecosystem support, and alignment with our architectural goals | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-006-plan-lifecycle.md b/docs/adr/ADR-006-plan-lifecycle.md index ce14335cb..a0d5a607c 100644 --- a/docs/adr/ADR-006-plan-lifecycle.md +++ b/docs/adr/ADR-006-plan-lifecycle.md @@ -1,9 +1,10 @@ # ADR-006: Plan Lifecycle -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-007, ADR-008, ADR-009, ADR-010, ADR-015, ADR-016, ADR-017 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -108,3 +109,39 @@ None — specification-driven requirement. The four-phase lifecycle with reversi - **Reversion boundary tests**: Tests verify that Execute-phase code cannot modify resources outside the sandbox and that reversion correctly preserves and transmits findings to the strategy actor. - **BDD scenarios**: Behave feature files describe end-to-end plan lifecycle scenarios including hierarchical decomposition, parallel child plan execution, and phase reversion. - **Automation profile integration tests**: Tests verify that each automation profile correctly gates the appropriate phase transitions. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-007](ADR-007-decision-tree-and-correction.md) | Decision Tree and Correction | Decisions are recorded at each phase transition in the plan lifecycle | +| [ADR-008](ADR-008-resource-system.md) | Resource System | Resources are bound to plans and sandboxed per the lifecycle phases | +| [ADR-009](ADR-009-project-model.md) | Project Model | Plans operate within project scope and inherit project-level configuration | +| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Actors drive phase transitions and execute plan steps | +| [ADR-015](ADR-015-sandbox-and-checkpoint.md) | Sandbox and Checkpoint | Sandboxes are created per-plan and checkpoints track execution progress | +| [ADR-016](ADR-016-invariant-system.md) | Invariant System | Invariants are reconciled at Strategize entry and enforced throughout the lifecycle | +| [ADR-017](ADR-017-automation-profiles.md) | Automation Profiles | Profiles control which phase transitions require human approval | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | The four-phase lifecycle with reversion rules gives us the right balance of structure and recovery | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-007-decision-tree-and-correction.md b/docs/adr/ADR-007-decision-tree-and-correction.md index 1fea35b88..eb1ac88ff 100644 --- a/docs/adr/ADR-007-decision-tree-and-correction.md +++ b/docs/adr/ADR-007-decision-tree-and-correction.md @@ -1,9 +1,10 @@ # ADR-007: Decision Tree and Correction -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-006, ADR-016, ADR-017 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -145,3 +146,35 @@ Decisions are stored in a `decisions` table with columns for all record fields, - **Context snapshot integrity**: Tests verify that replaying a decision from its context snapshot produces consistent results. - **BDD scenarios**: Behave features exercise correction workflows including prompt correction, strategy revision, and cross-hierarchy correction. - **Storage retention tests**: Tests verify that decision history cleanup respects retention policies. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Decision trees are built during lifecycle phases and drive phase transitions | +| [ADR-016](ADR-016-invariant-system.md) | Invariant System | Enforced invariants are recorded as decision nodes in the tree | +| [ADR-017](ADR-017-automation-profiles.md) | Automation Profiles | Confidence thresholds determine which decisions require human intervention | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Persistent decision graphs enable targeted correction without re-running entire plans | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-008-resource-system.md b/docs/adr/ADR-008-resource-system.md index 77979c569..38a55f05f 100644 --- a/docs/adr/ADR-008-resource-system.md +++ b/docs/adr/ADR-008-resource-system.md @@ -1,9 +1,10 @@ # ADR-008: Resource System -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-002, ADR-009, ADR-011, ADR-015 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -106,3 +107,36 @@ None — specification-driven requirement. The typed resource system with regist - **Sandbox strategy tests**: Each sandbox strategy has integration tests verifying isolation, modification, rollback, and cleanup. - **Binding resolution tests**: Unit tests verify that all three binding modes (contextual, static, parameter) resolve correctly for each resource type. - **BDD scenarios**: Behave features exercise multi-resource, multi-type plan execution including sandbox creation, tool binding, and result merging. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-002](ADR-002-namespace-system.md) | Namespace System | Resources are identified and resolved via the universal naming convention | +| [ADR-009](ADR-009-project-model.md) | Project Model | Projects aggregate and scope the resources available to plans | +| [ADR-011](ADR-011-tool-system.md) | Tool System | Tools declare resource bindings that determine which resources they operate on | +| [ADR-015](ADR-015-sandbox-and-checkpoint.md) | Sandbox and Checkpoint | Per-resource-type sandbox strategies isolate resource modifications | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Typed resources with DAG relationships and per-type sandbox strategies provide the right abstraction for safe manipulation | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-009-project-model.md b/docs/adr/ADR-009-project-model.md index 5983b68b7..0d400ff9d 100644 --- a/docs/adr/ADR-009-project-model.md +++ b/docs/adr/ADR-009-project-model.md @@ -1,9 +1,10 @@ # ADR-009: Project Model -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-002, ADR-008, ADR-014, ADR-016 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -97,3 +98,36 @@ None — specification-driven requirement. The project model as a named scope wi - **Multi-project tests**: Integration tests exercise plans targeting multiple projects with overlapping and non-overlapping resources. - **Configuration resolution tests**: Tests verify the full resolution chain (CLI > plan > action > project > global > default) for project-scopable keys. - **Code review**: New project-scopable configuration keys must be documented and tested for correct precedence. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-002](ADR-002-namespace-system.md) | Namespace System | Projects are namespace-scoped entities using the universal naming convention | +| [ADR-008](ADR-008-resource-system.md) | Resource System | Projects link and scope the resources available for plan execution | +| [ADR-014](ADR-014-context-management-acms.md) | Context Management (ACMS) | Projects configure context retrieval strategies and index scopes | +| [ADR-016](ADR-016-invariant-system.md) | Invariant System | Projects define project-scoped invariants that constrain all plans within | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Projects as named scopes linking resources, context, and invariants provide a clean organizational boundary | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-010-actor-and-agent-architecture.md b/docs/adr/ADR-010-actor-and-agent-architecture.md index 7897fd954..7f53a741f 100644 --- a/docs/adr/ADR-010-actor-and-agent-architecture.md +++ b/docs/adr/ADR-010-actor-and-agent-architecture.md @@ -1,9 +1,10 @@ # ADR-010: Actor and Agent Architecture -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-002, ADR-006, ADR-011, ADR-012, ADR-022 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -112,3 +113,37 @@ Agent behavior is configurable without code changes: prompt templates, tool sets - **Composition tests**: Integration tests verify that hierarchically composed actors correctly delegate to sub-actors and aggregate results. - **Role tests**: BDD scenarios verify that strategy, execution, estimation, and invariant actors fulfill their roles correctly within the plan lifecycle. - **Code review**: New actor definitions are reviewed for correct graph structure, appropriate skill access policies, and reasonable limit configurations. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-002](ADR-002-namespace-system.md) | Namespace System | Actors and agents are identified via namespaced names | +| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Actors drive plan phase transitions and execute plan steps | +| [ADR-011](ADR-011-tool-system.md) | Tool System | Tools serve as atomic execution nodes within actor graphs | +| [ADR-012](ADR-012-skill-system.md) | Skill System | Skills provide the tool collections that actors are equipped with | +| [ADR-022](ADR-022-langchain-langgraph-integration.md) | LangChain/LangGraph Integration | Actors are implemented as LangGraph StateGraph instances | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Actor-as-graph with hierarchical composition gives us flexible orchestration without tight coupling | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-011-tool-system.md b/docs/adr/ADR-011-tool-system.md index ba5650294..f0891bd89 100644 --- a/docs/adr/ADR-011-tool-system.md +++ b/docs/adr/ADR-011-tool-system.md @@ -1,9 +1,10 @@ # ADR-011: Tool System -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-002, ADR-004, ADR-008, ADR-010, ADR-012, ADR-013, ADR-015 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -136,3 +137,39 @@ None — specification-driven requirement. The tool system with its four-stage l - **Capability enforcement tests**: Tests verify that `read_only` actions reject tools with `writes: true`, and that `human_approval_required` tools trigger approval gates. - **Change tracking tests**: Tests verify that the changeset accurately reflects all tool invocations and contains no changes from LLM output parsing. - **Schema validation**: Tool registration validates input/output schemas against JSON Schema specification. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-002](ADR-002-namespace-system.md) | Namespace System | Tools use namespaced identifiers for discovery and conflict resolution | +| [ADR-004](ADR-004-data-validation.md) | Data Validation | Tool input/output schemas are Pydantic models with JSON Schema generation | +| [ADR-008](ADR-008-resource-system.md) | Resource System | Tools declare resource bindings that determine which resources they operate on | +| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Tools serve as atomic execution nodes within actor graphs | +| [ADR-012](ADR-012-skill-system.md) | Skill System | Skills compose tools into reusable collections for actor assignment | +| [ADR-013](ADR-013-validation-abstraction.md) | Validation Abstraction | Validations are a specialized Tool subtype with structured pass/fail semantics | +| [ADR-015](ADR-015-sandbox-and-checkpoint.md) | Sandbox and Checkpoint | Tool invocations create checkpoints for rollback and recovery | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | The four-stage lifecycle with dual role as skill component and graph node is a clean unification | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-012-skill-system.md b/docs/adr/ADR-012-skill-system.md index fddffd407..b6291bdfb 100644 --- a/docs/adr/ADR-012-skill-system.md +++ b/docs/adr/ADR-012-skill-system.md @@ -1,9 +1,10 @@ # ADR-012: Skill System -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-002, ADR-010, ADR-011, ADR-013 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -111,3 +112,36 @@ Actors specify a `skill_access_policy` that controls which skills they can use. - **Override tests**: Tests verify that metadata overrides at inclusion points are applied correctly and do not persist back to the source. - **Access policy tests**: Tests verify that actor skill access policies correctly restrict the available tool set. - **BDD scenarios**: Behave features exercise actors using hierarchically composed skills across all tool sources. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-002](ADR-002-namespace-system.md) | Namespace System | Skills use namespaced names and resolve tool conflicts via qualified names | +| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Skills are assigned to actors to provide their tool capabilities | +| [ADR-011](ADR-011-tool-system.md) | Tool System | Skills compose tools into reusable, hierarchical collections | +| [ADR-013](ADR-013-validation-abstraction.md) | Validation Abstraction | Validation tools can be included in skills alongside regular tools | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Composable skill collections with hierarchical inclusion keep actor configuration manageable | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-013-validation-abstraction.md b/docs/adr/ADR-013-validation-abstraction.md index fac5d643b..567090f0f 100644 --- a/docs/adr/ADR-013-validation-abstraction.md +++ b/docs/adr/ADR-013-validation-abstraction.md @@ -1,9 +1,10 @@ # ADR-013: Validation Abstraction -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-006, ADR-011, ADR-012, ADR-016 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -126,3 +127,36 @@ Validations can appear as tool nodes in actor graphs, with return values availab - **Attachment scoping tests**: Tests verify correct resolution across direct, project-scoped, and plan-scoped attachments. - **Failure handling tests**: BDD scenarios exercise the full failure sequence: fix → revalidate → retry limit → strategy revision → escalation → terminal failure. - **Wrapping tests**: Tests verify that wrapped tool transforms correctly interpret tool output and that inheritance rules are applied. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Validations gate phase transitions and can trigger phase reversion | +| [ADR-011](ADR-011-tool-system.md) | Tool System | Validations are a specialized Tool subtype inheriting the tool lifecycle | +| [ADR-012](ADR-012-skill-system.md) | Skill System | Validation tools can be composed into skills alongside regular tools | +| [ADR-016](ADR-016-invariant-system.md) | Invariant System | Invariant enforcement uses validation tools as its execution mechanism | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Modeling validation as a Tool subtype with structured pass/fail keeps the system uniform and composable | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-014-context-management-acms.md b/docs/adr/ADR-014-context-management-acms.md index d13536f4e..a2d2bc0d5 100644 --- a/docs/adr/ADR-014-context-management-acms.md +++ b/docs/adr/ADR-014-context-management-acms.md @@ -1,9 +1,10 @@ # ADR-014: Context Management (ACMS) -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-006, ADR-008, ADR-009, ADR-010 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -113,3 +114,36 @@ Child plans inherit a compressed "skeleton" of their parent's context. The Skele - **Strategy integration tests**: Tests verify that each retrieval strategy returns correctly structured results. - **Depth fallback tests**: Tests verify that fragments are downgraded to shallower depths when budget is insufficient for full depth. - **Configuration tests**: Tests verify that custom pipeline components and strategy registrations are loaded and invoked correctly. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Context is assembled and refreshed at each plan phase transition | +| [ADR-008](ADR-008-resource-system.md) | Resource System | Resources are indexed by the Unified Knowledge Ontology for context retrieval | +| [ADR-009](ADR-009-project-model.md) | Project Model | Projects configure context retrieval strategies and index scopes | +| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Actors consume assembled context to inform their decisions | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | A pipeline-based context assembly system keeps retrieval strategies composable and tunable per project | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-015-sandbox-and-checkpoint.md b/docs/adr/ADR-015-sandbox-and-checkpoint.md index 03c1dbaf7..0aa983048 100644 --- a/docs/adr/ADR-015-sandbox-and-checkpoint.md +++ b/docs/adr/ADR-015-sandbox-and-checkpoint.md @@ -1,9 +1,10 @@ # ADR-015: Sandbox and Checkpoint -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-006, ADR-008, ADR-011 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -116,3 +117,35 @@ Plans can require checkpoints via the `require_checkpoints` flag. If enabled, on - **Checkpoint tests**: Tests verify checkpoint creation, rollback to specific checkpoints, and pruning behavior. - **Lazy sandbox tests**: Tests verify that sandbox creation is deferred until first resource access and handles creation failures gracefully. - **Cleanup tests**: Tests verify that sandbox cleanup occurs at the correct lifecycle point (on_apply, on_terminal, manual). + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Sandboxes are created per-plan and destroyed on plan completion or reversion | +| [ADR-008](ADR-008-resource-system.md) | Resource System | Sandbox strategy is determined by resource type (git_worktree, filesystem_copy, etc.) | +| [ADR-011](ADR-011-tool-system.md) | Tool System | Tool invocations create checkpoints for granular rollback | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Lazy sandboxing with per-resource-type strategies avoids unnecessary overhead while keeping changes reversible | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-016-invariant-system.md b/docs/adr/ADR-016-invariant-system.md index 10b0322a4..d359e1575 100644 --- a/docs/adr/ADR-016-invariant-system.md +++ b/docs/adr/ADR-016-invariant-system.md @@ -1,9 +1,10 @@ # ADR-016: Invariant System -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-006, ADR-007, ADR-009, ADR-017 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -106,3 +107,36 @@ Invariants are correctable like any other decision: - **Inheritance tests**: Tests verify that child plans inherit the parent's effective invariant set and that child-level additions are correctly reconciled. - **Correction tests**: BDD scenarios verify that correcting an invariant invalidates downstream decisions and that adding/removing invariants triggers re-strategization. - **Reconciliation determinism**: Tests verify that the Invariant Reconciliation Actor produces identical output for identical inputs. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Invariants are reconciled at Strategize entry and enforced throughout the lifecycle | +| [ADR-007](ADR-007-decision-tree-and-correction.md) | Decision Tree and Correction | Enforced invariants are recorded as `invariant_enforced` decision nodes | +| [ADR-009](ADR-009-project-model.md) | Project Model | Projects define project-scoped invariants that constrain all child plans | +| [ADR-017](ADR-017-automation-profiles.md) | Automation Profiles | Invariant violations interact with automation profile thresholds for escalation | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Four-scope invariants with precedence and reconciliation give us layered constraint enforcement | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-017-automation-profiles.md b/docs/adr/ADR-017-automation-profiles.md index 20366b8f2..96a198b6b 100644 --- a/docs/adr/ADR-017-automation-profiles.md +++ b/docs/adr/ADR-017-automation-profiles.md @@ -1,9 +1,10 @@ # ADR-017: Automation Profiles -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-006, ADR-007, ADR-016 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -105,3 +106,35 @@ Custom automation profiles are registered via YAML configuration (`agents automa - **Safety constraint tests**: Tests verify that `require_sandbox` and `require_checkpoints` correctly reject non-compliant configurations and tools. - **Built-in profile tests**: Tests verify that all eight built-in profiles produce the expected behavior for standard plan lifecycles. - **BDD scenarios**: Behave features exercise plans under different profiles including transitions between manual approval, auto-proceed, and confidence-gated decisions. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Profiles control which lifecycle phase transitions require human approval | +| [ADR-007](ADR-007-decision-tree-and-correction.md) | Decision Tree and Correction | Confidence thresholds determine which decisions require human intervention | +| [ADR-016](ADR-016-invariant-system.md) | Invariant System | Invariant violation escalation is governed by the active automation profile | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Named profiles with confidence thresholds provide a clean spectrum from full manual to full autonomous control | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-018-semantic-error-prevention.md b/docs/adr/ADR-018-semantic-error-prevention.md index aec5a66f7..3a1d4abe6 100644 --- a/docs/adr/ADR-018-semantic-error-prevention.md +++ b/docs/adr/ADR-018-semantic-error-prevention.md @@ -1,9 +1,10 @@ # ADR-018: Semantic Error Prevention -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-006, ADR-007, ADR-013, ADR-016, ADR-017 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -99,3 +100,37 @@ The severity classification depends on the confidence score, the automation prof - **Guard performance tests**: Benchmarks verify that execution-time guards add acceptable latency (targets defined in ASV benchmarks). - **False positive tracking**: Metrics track false positive rates for each layer, enabling tuning. - **Integration tests**: BDD scenarios exercise multi-layer error detection including decision-time validation failure, execution-time guard intervention, invariant violation, and predictive warnings. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Error prevention layers operate at different lifecycle phases | +| [ADR-007](ADR-007-decision-tree-and-correction.md) | Decision Tree and Correction | Decision-time validation catches errors during tree construction | +| [ADR-013](ADR-013-validation-abstraction.md) | Validation Abstraction | Validation tools implement the execution-time semantic guards | +| [ADR-016](ADR-016-invariant-system.md) | Invariant System | Invariant enforcement is one of the four error prevention layers | +| [ADR-017](ADR-017-automation-profiles.md) | Automation Profiles | Low-confidence decisions are flagged based on automation profile thresholds | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Multiple prevention layers operating at different lifecycle points catch errors progressively earlier | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-019-storage-and-persistence.md b/docs/adr/ADR-019-storage-and-persistence.md index 002fe82b6..ea580da16 100644 --- a/docs/adr/ADR-019-storage-and-persistence.md +++ b/docs/adr/ADR-019-storage-and-persistence.md @@ -1,9 +1,10 @@ # ADR-019: Storage and Persistence -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-001, ADR-003, ADR-004, ADR-005 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -122,3 +123,36 @@ For server mode, the infrastructure layer swaps SQLite for PostgreSQL via the sa - **ULID ordering tests**: Tests verify that ULID-based queries return results in creation-time order. - **Concurrency tests**: Tests verify that concurrent read operations work correctly under WAL mode. - **Backup/restore tests**: Tests verify that backup creation and restoration produce consistent database state. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-001](ADR-001-layered-architecture.md) | Layered Architecture | Persistence adapters reside in the Infrastructure Layer behind domain ports | +| [ADR-003](ADR-003-dependency-injection.md) | Dependency Injection | Repository implementations are injected via the DI container | +| [ADR-004](ADR-004-data-validation.md) | Data Validation | Pydantic models define the schemas that map to SQLAlchemy ORM models | +| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | SQLAlchemy, SQLite, and PostgreSQL are the chosen persistence technologies | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Repository pattern with Unit of Work and dual-database support covers both local and server deployment cleanly | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-020-session-model.md b/docs/adr/ADR-020-session-model.md index 1bf467da5..baceef311 100644 --- a/docs/adr/ADR-020-session-model.md +++ b/docs/adr/ADR-020-session-model.md @@ -1,9 +1,10 @@ # ADR-020: Session Model -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-006, ADR-010, ADR-014 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -105,3 +106,35 @@ Plans are executed within sessions. A session may have multiple active plans (se - **Persistence tests**: Tests verify that conversation history survives CLI restarts and is correctly loaded on session resumption. - **Orchestrator binding tests**: Tests verify that the orchestrator actor is correctly bound at creation and that all session interactions route through it. - **Cleanup tests**: Tests verify that session archival correctly marks sessions as inactive without data loss. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Plans execute within sessions and inherit session-scoped context | +| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Sessions bind a user to an orchestrator actor for conversation | +| [ADR-014](ADR-014-context-management-acms.md) | Context Management (ACMS) | Sessions maintain session-scoped context tiers and conversation history | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Sessions as persistent conversation threads with cost budgets and context scoping tie the user experience together | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-021-cli-and-output-rendering.md b/docs/adr/ADR-021-cli-and-output-rendering.md index 6f396fc27..177ec0b80 100644 --- a/docs/adr/ADR-021-cli-and-output-rendering.md +++ b/docs/adr/ADR-021-cli-and-output-rendering.md @@ -1,9 +1,10 @@ # ADR-021: CLI and Output Rendering -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-001, ADR-005, ADR-024 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -137,3 +138,35 @@ All presentation surfaces consume the same Application Layer service facades. - **Structured output tests**: Tests verify that `json` and `yaml` outputs are valid, parseable, and contain no non-structured content. - **Stderr separation tests**: Tests verify that `-v` log output goes to stderr and does not appear in stdout when `--format json` is used. - **BDD scenarios**: Behave features exercise CLI workflows end-to-end with various format options. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-001](ADR-001-layered-architecture.md) | Layered Architecture | The CLI resides in the Presentation Layer and calls into Application Layer facades | +| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | Typer and Rich are the chosen CLI and rendering libraries | +| [ADR-024](ADR-024-configuration-system.md) | Configuration System | CLI flags participate in the five-tier configuration resolution chain | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | The noun-verb command pattern with six output formats covers both human and machine consumers well | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-022-langchain-langgraph-integration.md b/docs/adr/ADR-022-langchain-langgraph-integration.md index 33c4edfd3..cc35d7359 100644 --- a/docs/adr/ADR-022-langchain-langgraph-integration.md +++ b/docs/adr/ADR-022-langchain-langgraph-integration.md @@ -1,9 +1,10 @@ # ADR-022: LangChain/LangGraph Integration -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-001, ADR-003, ADR-005, ADR-010 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -102,3 +103,36 @@ LangChain Community provides `FakeListLLM` and `FakeEmbeddings` for testing with - **Checkpoint tests**: Tests verify that LangGraph checkpoints can be saved, loaded, and used for decision replay. - **Mock provider tests**: Tests verify that `FakeListLLM` and `FakeEmbeddings` produce deterministic results suitable for unit and integration testing. - **RxPY integration tests**: Tests verify that reactive streams correctly bridge with LangGraph execution and that backpressure is managed under concurrent load. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-001](ADR-001-layered-architecture.md) | Layered Architecture | LangChain/LangGraph implementations reside in the Infrastructure Layer | +| [ADR-003](ADR-003-dependency-injection.md) | Dependency Injection | LLM providers and LangGraph components are registered through the DI container | +| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | LangChain and LangGraph are core stack choices for LLM orchestration | +| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Actors are implemented as LangGraph StateGraph instances | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | LangChain for provider abstraction and LangGraph for stateful orchestration are the best fit for our actor model | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-023-server-mode.md b/docs/adr/ADR-023-server-mode.md index f95c4d3aa..31a34693c 100644 --- a/docs/adr/ADR-023-server-mode.md +++ b/docs/adr/ADR-023-server-mode.md @@ -1,9 +1,10 @@ # ADR-023: Server Mode -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-001, ADR-002, ADR-005, ADR-019 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -117,3 +118,36 @@ The key architectural enabler is the hexagonal pattern (ADR-001): - **Offline functionality tests**: Tests verify that local mode works completely without network access. - **Sync tests**: Integration tests verify entity sync behavior including auto-sync, manual sync, and conflict handling. - **Authentication tests**: Tests verify that server API calls require valid tokens and that unauthenticated requests are rejected. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-001](ADR-001-layered-architecture.md) | Layered Architecture | Both deployment modes share Domain and Application layers, differing only in Presentation and Infrastructure | +| [ADR-002](ADR-002-namespace-system.md) | Namespace System | Server mode introduces server-prefixed namespaces for multi-server entity resolution | +| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | FastAPI, uvicorn, and Helm/Kubernetes are the server mode stack choices | +| [ADR-019](ADR-019-storage-and-persistence.md) | Storage and Persistence | Server mode uses PostgreSQL instead of SQLite for multi-user persistence | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Sharing Domain and Application layers across both modes maximizes code reuse and behavioral consistency | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-024-configuration-system.md b/docs/adr/ADR-024-configuration-system.md index 4c0ae590d..3dddf1680 100644 --- a/docs/adr/ADR-024-configuration-system.md +++ b/docs/adr/ADR-024-configuration-system.md @@ -1,9 +1,10 @@ # ADR-024: Configuration System -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-004, ADR-005, ADR-009, ADR-017 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -137,3 +138,36 @@ Default behavior requires zero configuration. The system ships with sensible def - **YAML validation tests**: Tests verify that entity YAML files are validated completely and that invalid configurations are rejected with actionable error messages. - **Credential safety tests**: Tests verify that provider credential keys are masked in `agents config list` output and never appear in log output. - **Environment interpolation tests**: Tests verify that `${ENV_VAR}` syntax is correctly resolved in YAML entity files. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-004](ADR-004-data-validation.md) | Data Validation | Pydantic Settings validates and loads configuration values | +| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | TOML and YAML are the chosen configuration file formats | +| [ADR-009](ADR-009-project-model.md) | Project Model | Projects define project-scoped configuration overrides in the resolution chain | +| [ADR-017](ADR-017-automation-profiles.md) | Automation Profiles | Automation profiles are selected and configured through the configuration system | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Dual-format configuration with a five-tier resolution chain covers all override scenarios cleanly | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/ADR-025-observability-and-logging.md b/docs/adr/ADR-025-observability-and-logging.md index 6e6bd7b05..da5e017bf 100644 --- a/docs/adr/ADR-025-observability-and-logging.md +++ b/docs/adr/ADR-025-observability-and-logging.md @@ -1,9 +1,10 @@ # ADR-025: Observability and Logging -**Status:** Accepted -**Date:** 2026-02-16 -**Supersedes:** None -**Related ADRs:** ADR-001, ADR-005, ADR-024 +**Status:** Accepted +**Date:** 2026-02-16 +**Supersedes:** None +**Author(s):** Jeffrey Phillips Freeman +**Approver(s):** Jeffrey Phillips Freeman ## Context @@ -129,3 +130,35 @@ Metrics are exposed through structured log events and are available for performa - **Stderr separation tests**: Tests verify that log output goes to stderr and does not appear in stdout regardless of verbosity level. - **Retention tests**: Tests verify that log file cleanup correctly removes files older than the configured retention period. - **LangSmith opt-in tests**: Tests verify that the system functions correctly without LangSmith configured and that enabling LangSmith produces the expected traces. + +## Related ADRs + +| ADR | Title | Relationship | +|-----|-------|-------------| +| [ADR-001](ADR-001-layered-architecture.md) | Layered Architecture | Logging is a cross-cutting concern handled through the event bus in the Application Layer | +| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | structlog is the chosen structured logging library | +| [ADR-024](ADR-024-configuration-system.md) | Configuration System | Log verbosity levels are controlled through the configuration system and CLI flags | + +## Acceptance + +### Votes For + +| Voter | Comment | +|-------|---------| +| Jeffrey Phillips Freeman | Structured JSON logging with context binding gives us the observability needed for debugging LLM-driven workflows | + +**Total: 1** + +### Votes Against + +| Voter | Comment | +|-------|---------| + +**Total: 0** + +### Abstentions + +| Voter | Comment | +|-------|---------| + +**Total: 0** diff --git a/docs/adr/index.md b/docs/adr/index.md index a87539022..6dde8ae50 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -6,14 +6,24 @@ All ADRs derive their content from the [CleverAgents Specification](../specifica ## ADR Format -Every ADR follows a consistent 9-section template: +Every ADR follows a consistent template with metadata, content, and governance sections: -| Section | Purpose | -|---------|---------| +### Metadata + +Presented as plain text fields at the top of each ADR, one per line: + +| Field | Purpose | +|-------|---------| | **Status** | Current state of the decision: `Accepted`, `Proposed`, `Deprecated`, or `Superseded`. | | **Date** | Date the decision was accepted or last revised. | | **Supersedes** | Reference to a prior ADR this one replaces, or `None`. | -| **Related ADRs** | Cross-references to other ADRs that interact with this decision. | +| **Author(s)** | Contributors who authored or substantially edited the ADR text. | +| **Approver(s)** | Person(s) who verified the voting record and signed off on acceptance. | + +### Content Sections + +| Section | Purpose | +|---------|---------| | **Context** | The problem or situation that motivated this decision. Why it exists. | | **Decision** | The architectural choice that was made, stated declaratively. | | **Design** | Structural details — components, interfaces, patterns, data models, protocols. | @@ -22,6 +32,20 @@ Every ADR follows a consistent 9-section template: | **Alternatives Considered** | Other options evaluated and why they were not chosen. May be "None — specification-driven requirement." | | **Compliance** | How adherence to this decision is verified (CI checks, linting, code review, test patterns). | +### Related ADRs + +A table of cross-references to other ADRs that interact with this decision. Each entry includes a link to the related ADR, its title, and a brief description of the relationship. This is always the second-to-last section. + +### Acceptance + +Records the governance process for the ADR. This is always the last section. + +| Section | Purpose | +|---------|---------| +| **Votes For** | Table of voters who voted in favor, with optional comments and a total count. | +| **Votes Against** | Table of voters who voted against, with optional comments and a total count. | +| **Abstentions** | Table of voters who abstained, with optional comments and a total count. | + ## ADR Inventory ### Tier 1 — Foundational @@ -82,7 +106,10 @@ These ADRs address external integrations, operational interfaces, and deployment 1. Assign the next sequential number (e.g., `ADR-026`). 2. Create a file named `ADR-0NN-.md` in this directory. 3. Copy the template structure from any existing ADR. -4. Fill in all nine sections. Every section is required — use "N/A" only if genuinely not applicable. -5. Set `Status: Proposed` until the decision is reviewed and accepted. -6. Add the new ADR to the inventory table above and to the `nav` section in `mkdocs.yml`. -7. Cross-reference related ADRs in both directions (update existing ADRs' `Related ADRs` fields). +4. Fill in the metadata table with `Status: Proposed`, the current date, author(s), and leave approver(s) blank. +5. Add the Related ADRs table with links, titles, and relationship descriptions. +6. Leave the Acceptance section with empty voting tables — votes are recorded during the review process. +7. Fill in all content sections (Context through Compliance). Every section is required — use "N/A" only if genuinely not applicable. +8. Add the new ADR to the inventory table above and to the `nav` section in `mkdocs.yml`. +9. Cross-reference related ADRs in both directions (update existing ADRs' Related ADRs tables). +10. Once voting concludes and the ADR is accepted, update `Status` to `Accepted`, record all votes, and add the approver(s). diff --git a/docs/javascripts/toc-collapse.js b/docs/javascripts/toc-collapse.js index 20d3f6a5c..2627b8c12 100644 --- a/docs/javascripts/toc-collapse.js +++ b/docs/javascripts/toc-collapse.js @@ -64,33 +64,16 @@ li.classList.remove("toc-collapsed"); } - // ── Initialisation ────────────────────────────────────────────────── + // ── Shared: make nested items collapsible ──────────────────────────── + // + // Scans `containerEl` for
  • items with nested