# Chapter 4 — Architecture

## 4.1 Overview

The architecture begins with a relation: a person pursues a purpose through work
whose meaning, grounds and consequences must remain intelligible as agents
contribute. The environment mediates that relation. It shapes what participants
can find, what they can do and which differences become visible. For that reason,
an environment is consequential even when it appears to consist only of prompts,
files and ordinary tools.

Root's architectural proposition is to make those mediating means available as
shared, revisable artifacts and operations. Participants can examine a method,
challenge an instruction, repair a query or retire a duty using the same
practices through which they produce applications. This is a generative capacity:
work can improve its own means without requiring a predetermined orchestration
for every undertaking.

Revision remains bounded by authority and evidence. An agent that discovers a
burdensome rule does not thereby acquire the right to change the owner's
commitments. A change to a representation does not settle what its subject
means. Root must support adaptation without letting its ability to edit its own
machinery become a claim to define its own purpose.

Three relations organize the architecture: work and its representation,
responsibility and permission, and a contribution and the result that consumes it.

## 4.2 The Foundational Decision: Current Artifacts and Derived Views

### 4.2.1 The Graph Model

A representation is useful when it makes a relation available to the next
participant without pretending to replace that participant's assessment. A need
is especially important: it states why one contribution matters to another.
Recording only that two objects are linked loses the condition that gives the
link practical meaning. Recording a global completion label can conceal that
one consumer's need is met while another's is not.

Active project work is organized around deliverable folders. A deliverable's
`ScopeOfWork.md` holds commitments and acceptance criteria. `Design/` holds useful
technical detail. `deliverable.yaml` identifies the deliverable and states its
needs, with optional code paths and check references. A consumer declares what
it needs from a supplier; tools derive reverse links and graph views.

The graph is a representation of declared relationships, not the undertaking
itself. A need can name a deliverable, an external supplier, a document, a
package or an unresolved target. A condition may require interpretation that no
schema check can perform. Cycles can represent mutual interface development or
other legitimate relationships; their presence alone does not establish an
impossible execution order. Selected planning baselines can be DAGs without
requiring every useful relationship to be a DAG edge.

The current query interface provides `neighborhood`, `impact`, `touches`,
`dag-diff` and `check`. Results identify their observed basis and expose unknowns.
They do not mark a deliverable complete or infer acceptance from a merge. The
consumer declarations remain the sources; no generated progress register is
committed as a competing representation.

### 4.2.2 Why the Artifact Choice Matters

The artifact is a shared object around which disagreement can become specific.
Participants can point to a condition, compare a revision, or identify a missing
source. This does not externalize all understanding. It supplies a sufficiently
stable subject for continued interpretation and action across time and between
participants.

Plain, versioned artifacts support direct inspection, meaningful diffs, stable
references and recovery of committed versions. They also let agents use ordinary
file and Git tools instead of relying on a separate coordination service. Keeping
the current meaning in the deliverable reduces the number of places that must
be reconciled after a decision.

These are advantages of the chosen arrangement, not exclusive properties of
files. A database-backed application can also preserve provenance, versions and
attributable decisions. Conversely, a Git repository can contain misleading
claims, incomplete history or inconsistent declarations. A commit identifies
recorded content; it does not establish its correctness, the completeness of the
record or the authenticity of every represented human act.

Purpose and authorization can arise in the conversation. Applications have
operational state, and domain engines maintain models and results in their own
stores. The grounds needed for a particular use must be accessible and
sufficiently identified. Versioned files serve that requirement for development;
other stores serve their adopted application contracts.

### 4.2.3 Scope and Limits of the Filesystem Commitment

Repository commitments, designs and dependency declarations live in files.
Execution services may hold process state, requests, credentials under their
custodian, caches and recoverable session data. Domain applications own their
canonical models and numerical results. These stores have different purposes;
the existence of one does not authorize it to override another.

Derived indexes and caches can improve access when their basis and invalidation
behaviour are understood. There is no philosophical requirement to forbid them.
The design concern is whether a reader can identify what a result is based on,
where current meaning is maintained and how divergence is resolved.

Git preserves committed history. It does not automatically preserve unsaved
work, external services or every input to an analysis. Recovery requirements must
therefore be stated for the operation in question rather than assumed from the
presence of a repository.

## 4.3 Entity Model and Domain Ontology

### 4.3.1 Project Hierarchy

Root owns shared components in their functional locations: `agents/`,
`workflows/`, `.agents/skills/`, `tools/`, `.github/workflows/` and shared
references. The conversation defines the current Root undertaking. There is no
standing requirement to generate a product decomposition for every shared edit.

Active project deliverables use the following repository convention:

```text
projects/<project>/execution/
└── PKG-nn/
    └── DEL-nn-nn/
        ├── ScopeOfWork.md
        ├── Design/             # where useful
        └── deliverable.yaml
```

Packages group deliverables. The flat layout makes navigation predictable; it
is not a claim that every domain has a naturally flat ontology. An intended
work product is distinct from the folder used to manage it. Source code can live
elsewhere, and several deliverables can be relevant to the same code.

Development, examination and acceptance remain distinct activities even when
their artifacts occupy the same deliverable folder. Their meaning comes from the
work, evidence and applicable acts.

### 4.3.2 Stable Identifiers

Package and deliverable identifiers provide references that survive ordinary
text changes and help tools join declarations. In the active layout they follow
`PKG-nn` and `DEL-nn-nn`. A stable identifier does not establish that a deliverable's
meaning is unchanged: a scope revision can preserve identity while altering a
commitment, and that alteration still requires the appropriate authority.

Code-path mappings express relevance, not exclusive ownership or fulfilment.
An unmapped path produces a partial answer. It is not evidence that the change
has no consumers, nor a reason to initiate a repository-wide metadata exercise.

### 4.3.3 Deliverable Content and Its Home

The three current artifact types divide responsibility without claiming that
all useful content fits a closed schema:

| Artifact | Purpose | What it does not establish |
|---|---|---|
| `ScopeOfWork.md` | Intended result, commitments and acceptance criteria | That the result exists or is accepted |
| `Design/` | Technical reasoning, constraints and relevant sources | That every assumption has been demonstrated |
| `deliverable.yaml` | Needs, conditions and useful code/check pointers | Completion, suitability or an execution schedule |

A decision changes the text it governs. The PR describes the change, its reason,
checks and unresolved matters; Git retains the earlier text. Sources and
references remain where they help the work rather than in compulsory mirror
files. A record is justified by a concrete consumer, acceptance requirement or
recovery need.

### 4.3.4 Structural and Dependency Views

A concrete traversal starts with an affected project deliverable and its
`neighborhood`. Each returned need identifies a source file and index. The agent
reads the condition and the relevant supplier material, rather than treating the
supplier's presence on main as fulfilment. If the work changes that condition,
the consumer declaration changes; reverse links are derived again. An `impact`
query then selects downstream relationships for investigation. This sequence
maintains one declaration while supporting several useful views.

The package tree supports composition and navigation. The dependency graph
supports investigation of inputs and consumers. Neither view alone determines
what can safely proceed. The tool can reveal that two deliverables have no
recorded dependency, while their implementations still share a file, a memory
budget or an unresolved interface.

`impact` follows declared downstream relationships, including non-gating ones.
It identifies candidates for examination, not an automatic list of invalidated
work. `dag-diff` compares declarations against an identified baseline; it does
not accept the new graph. Ordinary authorized dependency updates need no new
acceptance ceremony unless they change a reserved commitment or baseline.

### 4.3.5 The Four Structures

The tree, graph, relationship network and attention discussed in Chapter 3 are
complementary perspectives:

- **Tree:** what the undertaking is composed of at a useful level of detail.
- **Dependency graph:** which contributions need which inputs and conditions.
- **Relationship network:** sources, decisions, shared concepts and other links
  relevant to interpretation, including those outside execution order.
- **Attention:** the activity through which a participant selects, relates and
  synthesizes what matters for the question in hand.

Attention is not another mandatory stored graph. Nor must every relationship
be extracted into metadata before work can proceed. A machine-readable link is
useful when a real query needs it; otherwise a clear reference in the relevant
design may suffice. These views assist reckoning and human judgment without
exhausting situated understanding.

## 4.4 Work, Evidence and Acceptance

### 4.4.1 Conditions of Work

Availability, suitability, examination and acceptance concern different relations.
A supplier may be usable for one consumer while inadequate for another. A review
may apply to one revision or purpose; acceptance identifies a person's particular
commitment. These distinctions guide action through their actual conditions and
evidence. [Appendix E](appendix_e_development_history.md) records the development
of this representation of work.

### 4.4.2 Actions and Authority

The current operating model separates ordinary action from reserved decisions.
Agents can investigate, implement, examine, repair and integrate within the
owner's authorization and the host's permissions. Changes to commitments or
acceptance criteria, releases, risk acceptance and explicit holds remain owner
matters. The repository's standing Git grant permits authorized integration
under its verification conditions; a merge is not acceptance for professional
reliance.

Human judgment is situated, committed engagement throughout the undertaking.
It shapes purpose, distinctions, evidence and what the person will stand behind.
An acceptance is one expression of that engagement, not its entire content.
Neither a lifecycle transition nor a record can perform judgment for the person.

### 4.4.3 Stage Gates and Useful Checkpoints

A project can require an accepted baseline, a release decision or another
consequential checkpoint. Its purpose, subject and authority must be clear.
Those needs do not justify a human gate at every internal agent handoff or
ordinary implementation step.

The current architecture therefore permits project-specific checkpoints while
rejecting a universal development lifecycle. A tool may enforce objective
preconditions for an operation; passing them is evidence about those conditions,
not permission to claim professional approval.

### 4.4.4 Observable Facts Instead of Stored Progress

The question “what can proceed here?” draws on current conditions, available
inputs, relevant checks, in-flight changes and resource constraints. It is not
answered by a single stored status. A file's presence may establish availability
but say nothing about whether it contains the required interface. A passing
check establishes only the behaviour it exercises under its tested conditions.

Agents assess suitability using these facts and report uncertainty when it
matters. This assessment is part of their reckoning; it does not transfer the
person's accountable judgment to the query tool or agent.

### 4.4.5 Warrant and Revision

A claim's grounds, its examination and the reliance accepted on it can change
independently. A citation can be irrelevant; a reviewed claim can later be
contradicted; an authenticated result can be wrong. Several claims in one
artifact can have different grounds and limits.

The operative questions are what supports the claim, whether that support is
appropriate here, what remains uncertain, and who accepts which reliance.
They require inspectable grounds, not a
second obligatory lifecycle register.

## 4.5 Roles and Responsibility

### 4.5.1 Structural Overview

Roles answer a risk in collective work: a needed responsibility can disappear
between individually completed assignments. Someone must preserve purpose,
someone must make intent concrete, and someone must connect contributions into
a result. Naming those responsibilities makes the gap discussable. It does not
follow that each needs a separate person or process.

The current role definitions offer four contributions:

| Role | Type | Contribution |
|---|---|---|
| HELP_HUMAN | 0 | Purpose, alignment and continuity with the owner |
| HELPS_HUMANS | 1 | Make intent concrete through design |
| WORKING_ITEMS | 1 | Own implementation, contributors and integration |
| TASK | 2 | Carry one bounded assignment through ordinary repairs; no delegation |

The agent working with the person holds Agent 0's continuity responsibilities,
whatever role it entered through. A session can perform substantial work without
delegation. Managers and contributors are engaged when their contribution helps;
the types do not constitute a required staffing chart.

### 4.5.2 Authority Properties

A role describes responsibility. The assignment and host determine available
tools and write scope. HELP_HUMAN is not intrinsically read-only. TASK's
no-delegation rule remains a deliberate role boundary; a TASK can report an
opportunity to divide work to its caller without creating another hierarchy.

No role grants a right to override an explicit hold or make an owner-reserved
decision. Conversely, ordinary refinement of design within authorized work is
not automatically a reason to escalate. Relevant escalation concerns commitments,
consequential shared assumptions, interfaces outside the assignment or a reserved
choice.

### 4.5.3 Classification and Capability

Root separates responsibility, method selection and authorization. The role file
states what contribution is being undertaken. The selected workflow supplies a
method. The assignment identifies the authorized work, and the host supplies
actual capabilities. None can silently stand in for another: a workflow name
cannot grant writes, and a broad host capability cannot widen the assignment.

Type numbers identify responsibilities, not model assignments or levels of
intelligence. Skills and workflows are methods selected for the work. A host's
ability to spawn agents does not itself authorize TASK to delegate, and a
permissive role description cannot expand a read-only host.

The repository resolver represents this distinction in policy construction. Its
[implementation](../../tools/workflow_runtime/resolve_workflow.py) explicitly
states that it reports policy rather than acting as a sandbox. A host must
actually enforce the relevant permissions. App v4's product settings have their
own adopted basis; repository role changes do not silently amend them.

## 4.6 Write Scope and Containment

### 4.6.1 Assignment-Specific Scope

A writing assignment needs a usable boundary: the intended changes, affected
objects and prohibited areas. The required precision depends on the operation.
A code change may span source, tests and a design note; it need not fit one
folder merely because the older role catalog assigned folder-based categories.

Missing authorization does not imply unrestricted writes. Explicit read-only
conditions remain effective. Where a tool accepts paths, normalized containment
and symlink handling are concrete implementation concerns, separate from the
agent's willingness to follow instructions.

### 4.6.2 Shared Work and Protected Objects

Concurrent contributors should have disjoint writes, or one owner must integrate
shared changes. A read-only review can overlap production when its basis remains
clear. Independence in the dependency graph is an opportunity to investigate
concurrency, not proof that shared writes or resources are absent.

Domain applications add stronger object-level restrictions. The adopted
[product boundaries](../PRODUCT_BOUNDARIES.md) reserve protected domain changes
to the declared engine-controlled path. The engine owns canonical model state;
this is a storage and operation authority, not a guarantee of engineering truth.
Applicable proposal, validation and human-acceptance requirements remain product
contracts. Removing repository record duties does not remove those contracts.

### 4.6.3 What Can Be Enforced

| Mechanism | Bounded contribution | Limit |
|---|---|---|
| Assignment and instructions | State objective, scope and prohibited actions | Following prose is not guaranteed |
| Resolver and schema validation | Reject malformed declarations and some escaping paths | Do not inspect every real effect of an arbitrary command |
| Host permissions | Restrict actions on the enforced execution path | Depend on implementation and coverage of alternative paths |
| Domain operation validation | Check specified model constraints before application | Does not establish all physical or professional adequacy |
| Review and targeted checks | Detect selected errors and assess evidence | Can share assumptions or miss unexamined failures |

This allocation is more precise than saying that instructions themselves create
fault containment. A claimed enforced property needs an identified mechanism,
its coverage and appropriate evidence.

### 4.6.4 Fault Containment and Its Costs

Containment can limit the consequences of an error, but path separation alone
does not isolate shared assumptions, resource exhaustion or misleading outputs.
Worktrees reduce some write conflicts; they do not make integration automatic.
Additional layers can also create stale permissions, waiting and duplicated
state. Their value must be assessed against the failures they address and the
burden they impose.

## 4.7 Commitments, Design Hypotheses and Evidence

### 4.7.1 Three Kinds of Claim

The analysis distinguishes:

1. **Normative commitments:** what responsibility and values the undertaking
   chooses to preserve, such as attributable human acceptance.
2. **Design hypotheses:** how an arrangement is expected to serve those
   commitments, such as identifying the exact subject of an acceptance.
3. **Observed outcomes:** what inspection, tests or use establish about a
   particular implementation and basis.

An acceptance commitment does not prove that a SHA-binding mechanism is sufficient
for it. A successful test of that mechanism does not establish that the person
understood the subject. Appendix A retains the historical identifiers for
comparison and points to adopted product contracts where they still apply.

### 4.7.2 Assurance and the Limits of Layering

Examination is justified by the claim that matters to a consumer. Its purpose is
to expose a consequential mistake or establish a missing ground, not to certify
that work has traversed enough reviewers. A contribution can be consistent with
its test suite and still inherit a mistaken premise shared by every test author.
The basis of agreement sometimes needs examination more than another instance
of agreement does.

Instructions, deterministic checks, host enforcement and human examination can
complement one another. They can also share the same mistaken premise. Merely
counting layers provides no assurance that one failure cannot compromise the
result.

Verification is selected by consequence and detectability. Routine reversible
changes can be inspected; ordinary implementation receives a focused check;
numerical meaning, persistence, permissions and destructive operations warrant
targeted regression checks and independent scrutiny. The repository's required
`harness` result aggregates the checks selected for the candidate. Passing CI
is bounded evidence for integration, not a certificate of product correctness.

The cost of control belongs in this assessment. Repeated records and checks can
consume the attention needed for substantive examination. Conversely, a cheap
numerical oracle that consistently passes can remain valuable because it detects
a consequential failure that would otherwise remain silent.

## 4.8 Coordination and Continuing Ownership

The relation developed in the
[shared introduction](INTRODUCTION.md#iteration-as-learning) has an architectural
consequence: a correction must reach its actual consumer. A revised method needs
an adoption path into the App; an engineering finding needs a path back to the
relevant model, operation or design criterion. Root's sources and queries support
that investigation, while the receiving application owns its operations and
checks. A shared source establishes neither adoption nor domain adequacy.

The [illustrative support-arrangement revision](WORKED_EXAMPLE.md) follows that
relationship across physical intent, operation, calculation, alternatives and
choice. It supplies no measured numerical result or proof of implementation.

### 4.8.1 Contributions Rather Than a Spawning Chart

Ownership through repair connects production to consequences. An author who
leaves at the first return can transfer interpretive work to a reviewer or
coordinator without making that transfer visible. Continuing ownership preserves
context while another perspective examines the result. The relevant division is
between contribution and scrutiny, not necessarily between every production step.

The [coordinated-knowledge-work workflow](../../workflows/coordinated-knowledge-work/WORKFLOW.md)
organizes purpose, integration, production and independent examination. An agent
can carry several responsibilities when the work permits. Separate contributors
are useful for parallel lines, different expertise or independent scrutiny;
creating the largest possible agent tree is not itself an outcome.

Independent work need not wait behind an unresolved branch. Shared writes,
resource limits, review capacity and integration costs can still justify
sequencing. These are properties of the undertaking, not universal serial or
parallel defaults.

### 4.8.2 Continuity and Recovery

Continuity concerns the intelligibility of what remains to be done. Exhaustive
transcription cannot guarantee it: a large history may leave the next participant
unable to identify the current question. A current source and a precise unresolved
condition can preserve more useful continuity than a chronology of every action.

Continuity comes primarily from current artifacts, the conversation, tool queries
and the existing change history. A replaceable recovery note is useful when
those sources do not suffice across an interruption. It is not a routine second
work graph or a record of every action.

A resumed participant does not acquire the earlier participant's whole situated
understanding by reading a file. Recovery must be tested against an actual task:
can the participant identify the current objective, basis, unresolved matters and
next authorized action without repeating or losing consequential work?

### 4.8.3 The Working Cycle

Consider a change to a reusable workflow. The producer locates its package and
actual consumers, follows `create-workflow`, edits the method and rebuilds the
workflow index when its consumed metadata changes. An affected App bundle is
updated only where the product actually adopts the changed source. Examination
then follows that connecting path. Merely posting a notice neither updates the
consumer nor establishes what it will execute.

The same principle governs review. A reviewer needs the actual candidate,
applicable source basis and existing evidence. A stale synopsis, a prior preview
or an inherited statement that a test passed cannot replace inspection of the
claim at issue. A source correction reaches the governed text and affected
implementation; valid unrelated evidence remains usable.

The current repository cycle is to establish the objective and authorization,
locate affected artifacts, query inputs and consumers, perform and examine the
work, update current meaning where necessary, and return the usable result.
Ownership continues through ordinary repairs and integration. The agent stops
when the agreed result is established rather than inventing administrative
closeout.

The cycle can proceed under standing authority. It does not require a human
confirmation at each iteration. An unresolved owner-reserved decision pauses the
affected action, while independent authorized work can continue.

### 4.8.4 App Exemplar and Domain Application

Root produces and revises reusable meanings and methods. The App expresses
Chirality inside an application: workflow authoring lets people develop, try,
inspect and improve methods through the human–agent relationship. It provides
a first exemplar whose subject is close to Root's own work. That does not make
Root the App's executable runtime or oblige every product to adopt the same
process arrangement.

SWBPIPE instantiates the approach at the level of a particular application
category. Physical and analytical models, operations, numerical results and
engineering interpretation introduce meanings that a general authoring App
cannot supply. Human and agent entry points are intended to reach common domain
operations. Their correctness belongs to the application, not to Root's method
library.

The transfer therefore preserves selected relationships rather than a complete
software topology. The [App thesis](../../projects/chirality-app-v4/docs/thesis/README.md)
examines hosting and workflow authoring; the
[SWBPIPE thesis](../../projects/chirality-piping/docs/thesis/README.md) examines
piping-domain instantiation. A shared kernel gives them an orientation. It does
not discharge either application's evidence obligations.

Successive App versions illustrate re-derivation from a current PRD. Requirements
constrain the result; prior implementation, failures, useful interactions and
supplier changes inform the design. Root helps make those sources accessible.
It does not mechanically compile them into one correct application. Earlier
Apps, Runtime and PEC remain recoverable through
[projects/FROZEN.md](../../projects/FROZEN.md), without current development duties.

## 4.9 Assignment and Result Interfaces

### 4.9.1 The Assignment

An assignment can be the conversation. It needs sufficient purpose, context,
boundaries and expected result for its recipient to act. Reusable tools may need
strict schemas; that does not make every agent brief a fixed parameter table.
The current repository requires a dispatched brief to be given in full in the
dispatch and to refer to repository sources, avoiding hidden instruction sets in
scratch space or host-side persona files.

Identical inputs do not guarantee equivalent model outputs. Repeatability claims
must identify the actual execution and assessment conditions. Missing information
is handled according to its significance: report a real blocker, investigate a
resolvable uncertainty, and continue unaffected work.

### 4.9.2 The Result

A return gives the result location, checks, material findings and unresolved
choices. Contributors inspect returns through the host's actual completion
mechanism. A separate return file, receipt or tool-root snapshot is not a general
requirement.

Some outputs need durable records: an accepted artifact, numerical evidence,
recoverable operation outcome or release package. Their form follows the
consumer's need. Machine-generated execution history can be useful for debugging
and recovery without requiring agents to duplicate it in authored summaries.

### 4.9.3 Historical Preservation and Current Meaning

Current documents are edited in place when their meaning changes. Git preserves
committed versions, while selected tags identify baselines and recovery points.
A tag that records an owner decision must accurately identify that decision; its
creation is not the decision itself.

Retention follows the actual consumer, acceptance or recovery need. Identifying
the relied-upon version and recovering an interrupted action are different needs
and may require different mechanisms. [Appendix E](appendix_e_development_history.md)
records the snapshot convention used during development.

## 4.10 Summary

The Root architecture joins current artifacts, selective method access, bounded
tools, continuing ownership and appropriate examination. Its immediate result is
a usable environment for producing work and revising that environment itself.
The architecture preserves distinctions among need, availability, suitability,
execution, outcome and acceptance without requiring a separate status system to
stand for each.

The four perspectives become practical questions along these paths: what object
or commitment changes, what supports the change, how it reaches its consumer,
and whether its benefits justify its consequences and costs. Agent reckoning
can perform substantial work within this arrangement; human judgment remains
situated commitment throughout the undertaking.

The App and SWBPIPE test different receiving contexts. Root's success does not
establish their usability, numerical adequacy or professional suitability.
Likewise, a productive application does not prove every shared procedure useful.
The relation supports mutual examination while leaving each claim with its
actual subject and evidence.