影 kaged
← back to Architecture Decision Records

ADR-0015: Federated Project Configuration & Resource Resolution

Status

Accepted

Context

As the project management and multi-agent harness grows, we need a standardized way to handle configurations across nested projects (submodules). The current system needs to support deep-merging, local user overrides, strict security sandboxing, and cross-project coordination without creating "leaky" abstractions where sub-projects become dependent on parent project structures.

Decision

1. The Project "Silo" Boundary

We will implement a strict "No-Exit" policy for all projects.

  • A project is defined by the presence of a .kaged/ directory.
  • The project:/ prefix is a logical root tied to that specific project’s directory.
  • Path traversal using ../ is forbidden if it attempts to resolve outside the logical project root.
  • Sub-projects (nested projects) are treated as autonomous cells. They are unaware of any parent project, ensuring they remain fully portable and functional as standalone units.

2. Configuration Merging & Inheritance

Configuration will move away from arrays toward Named Objects to facilitate predictable merging.

  • Deep Merge: All configurations will undergo a deep merge in the following order of precedence:
  1. project.yaml (Base)
  2. project.local.yaml (Local user overrides)
  3. Parent Injection (Virtual overrides passed down by a parent harness)
  • Nullification: To remove a key inherited from a base config, the override file must set that key to null.
  • Ordering: In contexts where sequence matters, the order of keys in the YAML serves as the default priority.

3. The Prefix Protocol (URI-based Resolution)

To eliminate ambiguity, all file and resource references in any config must use a URI prefix. Naked strings will be rejected by the harness.

  • project:/ - Resolves relative to the project root.
  • config:/ - Resolves relative to the .kaged/ directory.
  • git:/, https:/ - External resources (subject to opt-in security rules).

4. Security & Protocol Hierarchy

  • Opt-in Protocol Safety: External protocols (e.g., https) must be explicitly enabled in the security.allowed_protocols section of the config.
  • The Security Ceiling: A child project cannot enable a protocol that is disabled by its parent. A child may only increase security (remove protocols), never decrease it.

5. Local Shadowing

The harness will support implicit shadowing of system files. If a config references config:/prompts/agent.md, the harness will check for config:/prompts/agent.local.md first. If present, the local version is used, allowing users to tweak prompts without modifying the core project repository.

6. Cross-Project Injection

To allow coordination between silos (e.g., a Frontend project talking to a Backend project), the Parent project will "inject" virtual agent or tool definitions into the Child project’s runtime config.

  • These injected agents act as interfaces/proxies.
  • The Child project interacts with the proxy, while the Parent harness handles the message routing to the actual destination project.

7. Compiled Contextualization

Initialization Root: The project directory where the harness is invoked becomes the Primary State Holder.

Asset Flattening: During compilation, the harness recursively resolves all type: project agents, merging their configs and "jailbreaking" their requirements into the primary runtime manifest.

Siloed State: Conversation logs and ephemeral state are not inherited. A sub-project's local state is ignored when it is invoked as a member of a parent project; instead, it operates under the parent's session state.

Consequences

Positive

  • Portability: Sub-projects can be developed and tested in total isolation.
  • Security: Prevents malicious or accidental access to files outside the intended project scope.
  • Flexibility: Local developers can override almost any aspect of the agent behavior via .local.yaml without risking git merge conflicts.
  • Scalability: Large monorepos can be broken down into manageable, nested "Kaged" projects.

Negative / Tech Debt

  • Ordering Logic: Using named objects for ordered lists (like middleware) requires a future-proof strategy for defining weights if key-order proves insufficient.
  • Complexity: Injected "virtual" agents add a layer of indirection that may make debugging cross-project communication more difficult.

Technical Rules Summary

  • Rule 1: Prefix or Fail. (All paths must have a protocol).
  • Rule 2: The project root is the ceiling. (No ../ escapes).
  • Rule 3: Merge via Objects. (No arrays for overridable lists).
  • Rule 4: Parent sets the security max. (Protocol ceiling).

Amendments

2026-05-26 — Project-reference flattening outputs AgentSpec subtree (ADR-0022)

Merge semantics are unchanged (deep merge, nullification, URI prefix protocol, silo boundary). Project-reference flattening output changes from the wrapped _compiled shape to a direct AgentSpec subtree per ADR-0022. After flattening, there is no residual path: or _compiled wrapper — only recursive AgentSpec nodes. Cycle detection and depth limit (16) are unchanged. The §7 Compiled Contextualization section is amended in docs/specs/federated-config.md.