Architecture Routing: From Intent to Layer, Capability, and External Project¶
This page converges "where should an architecture requirement land" into a mechanically-reusable decision order and routing table. It serves new agents who, without reading the source code end-to-end, quickly obtain a verifiable answer: does this requirement belong to Foundation, in which layer (Contracts/Harness/Kit/Profile), with which stable entry point, what semantics remain owned by the caller, and when should it be handed off to an external project.
Decision Order¶
Judge in order by number, stopping at the first match:
- Does it contain domain semantics, a business state machine, or an audit oracle? If yes, keep it with the consumer; Foundation connects only business-neutral mechanisms.
- Is it structure, a protocol, a stable error code, or an object Schema? → Contracts (contract authority).
- Is it a cross-skill-family reusable Node mechanism? → Harness (Node implementation of the Contracts mechanism protocol).
- Is it the engineering-phase scaffold/adopt-plan/projection/check, or a concrete host Profile injection? → Kit / Profile.
- Does it involve publishing remote state? → release-skill.
- Does it involve tasks, retries, rework, acceptance, or self-iteration? → loop-agent.
- Does it involve artifact relationships, context, packet, or version-lock? → artifact-graph.
- Does it have only one consumer, or has cross-two-real-consumer duplication not been proven? Keep it with the consumer by default; do not expand Foundation.
Step 8 is the expansion gate. Any new component must justify: deleting it would force two or more real consumers to re-implement it, and this is verified by an independent fixture. Otherwise keep it on the consumer side.
Routing Table¶
The table below gives the preferred capability and the forbidden misuse for common architecture intents. Each preferred capability can be looked up in capability-catalog.json by id for its entry points, side effects, and failure semantics.
| Architecture intent | Preferred capability | Forbidden misuse |
|---|---|---|
| Validate a Foundation contract object | Contracts / Harness validation (foundation.contracts.object-validation, foundation.harness.contract-validation) |
Do not replace the consumer's business Schema |
| Safe file access and atomic write | Harness path / atomic API (foundation.harness.path-containment, foundation.harness.atomic-write) |
Do not put file-selection business rules into Harness |
| Generate a deterministic human report | Harness report or Kit report sub-action (foundation.harness.report, foundation.kit.report) |
Do not freely author reports from open business outputs |
| Durable events and derived snapshot | Harness state-store (foundation.harness.state-store) |
Do not define a workflow state machine in Foundation |
| New-project skeleton | Kit scaffold (foundation.kit.scaffold) |
Do not overwrite a non-empty existing repository |
| Existing-repository adoption inventory | Kit adopt-plan (foundation.kit.adopt-plan) |
Do not write files, do not auto-migrate |
| Managed projection | Kit projection + Profile (foundation.kit.projection) |
Do not overwrite handwritten files |
| Engineering diagnostics | Kit check (foundation.kit.check) |
Do not auto-fix |
| Publishing | release-skill | Foundation does not own remote writes |
| Tasks/retries/rework | loop-agent | Foundation does not own a business state machine |
| Artifact relationships/version-lock | artifact-graph | Foundation does not own the artifact graph |
Layer-Location Quick Reference¶
The dependency direction is fixed as Contracts → Harness → Engineering Kit; Profile declares horizontally, and the public core does not depend in reverse on a concrete Profile.
- Contracts: structure, protocols, error codes, protocol-name registry; 18 top-level object kinds, 9 mandatory rules.
- Harness: the thin Node mechanism runtime of Contracts; implements only business-neutral mechanisms, owning no semantics.
- Engineering Kit: the four engineering commands (scaffold, adopt-plan, projection, check) and their read-only / restricted-write boundaries.
- Profile: the declarative SPI for host and project-shape differences; implements only the stable SPI, injecting no business semantics.
- External projects: release-skill (publishing), loop-agent (task lifecycle), artifact-graph (artifact relationships), independent audit consumer (domain semantics).
Typical Misrouting and Correction¶
- Misrouting a domain Schema to Foundation: the domain Schema is owned by the consumer; Foundation provides only a generic validation mechanism (
foundation.contracts.object-validation). - Misrouting a workflow state machine to Foundation: state-store provides only the event-log and snapshot substrate; reducer transitions and terminal states are owned by the caller (
foundation.unsupported.business-state-machine). - Misrouting a publish write to Foundation: remote writes belong to release-skill; Foundation contains no publish/remote-write entry point (
foundation.unsupported.remote-publish). - Misrouting an audit oracle to Foundation: the audit surface only performs deterministic serialization; domain conclusions belong to external review (
foundation.unsupported.domain-audit-semantics).
The honest boundary of routing judgment: structural checks only prove byte/structural consistency (provable in-repo); ordinary prose semantics and the final accept/reject conclusion belong to external independent review; no second gate is maintained within the target repository.