# Council Design Brief: Decision Archaeology

---

## Council Identification

| Field | Value |
|-------|-------|
| **Council ID** | `council-arch` |
| **Mission** | Navigate the complete UCXL decision graph produced by all DistOS councils and generate human-comprehensible narratives of how every architectural decision was reached. Council-arch is the proof-of-concept for the central claim of the CHORUS experiment: that UCXL makes the complex interactions of hundreds of AI agents legible to human observers. If a human who has never seen this project can read council-arch's outputs and understand *why* DistOS was designed the way it was, the experiment succeeds. |
| **UCXL Base Address** | `ucxl://council-arch:*@DistOS:arch/*^/` |
| **Agent Count** | ~40 agents |
| **Operates From** | Day 1 — council-arch is the first council to activate and the last to conclude |

---

## Scope and Responsibilities

Council-arch's scope is interpretive and narrative. It does not make architectural decisions; it reads, traverses, and explains them. Specifically:

- Continuously monitoring all UCXL streams across all DistOS councils from Day 1, building a real-time map of the decision graph
- Traversing temporal UCXL chains (`*^`, `*~N`, `~~N` syntax) to reconstruct the sequence of decisions that led to any given artifact
- Generating human-readable narratives explaining individual decisions, decision chains, and cross-council conflicts and their resolutions
- Answering the question "why was this decided?" for any architectural choice in DistOS, by tracing the decision chain back through the UCXL graph
- Producing daily and weekly progress summaries accessible to human observers who are not following the per-council streams
- Analysing the downstream impact of decisions: how did decision X made by council-sched affect council-mem, council-fs, and council-sec?
- Producing executive-level summaries for each phase of the project
- Feeding all narrative outputs to council-docs for incorporation into the final specification document's rationale sections
- Conducting the ultimate readability test: are the archaeology outputs sufficient for a newcomer to reconstruct the design rationale?

Council-arch does **not** write technical specifications. It does not evaluate whether decisions are correct — that is council-verify's domain. It does not resolve conflicts — that is council-synth's domain. It only reads, traverses, and narrates.

### Why This Council is the Most Important

The CHORUS project's central hypothesis is that UCXL can preserve the full provenance of AI agent decision-making in a form that humans can later inspect and understand. This has profound implications:

- **Accountability:** If an AI-generated specification contains an error, a human auditor must be able to trace it to the decision that introduced it and understand the reasoning that led there.
- **Verifiability:** If a design decision seems wrong in hindsight, a human must be able to reconstruct the information that was available at the time the decision was made.
- **Maintainability:** A human engineer who must later modify DistOS must be able to understand why things are the way they are, not just what they are.
- **Trust:** The ability for humans to inspect and understand AI reasoning chains is prerequisite for trusting AI-generated specifications in production systems.

Council-arch's outputs are the primary evidence for whether CHORUS achieved its hypothesis.

---

## Research Domains

### 1. UCXL Temporal Navigation

The UCXL addressing scheme provides three mechanisms for temporal navigation:

**`*^` (current head)** — the most recent version of an artifact:
```
ucxl://council-sched:scheduler@DistOS:sched/*^/spec/preemption-policy
```

**`*~N` (N versions before head)** — navigate N steps back in the version chain:
```
ucxl://council-sched:scheduler@DistOS:sched/*~3/spec/preemption-policy
```
This is the version of the preemption policy 3 revisions ago — before the conflict with council-mem was resolved.

**`~~N` (absolute version N)** — navigate to a specific version by sequence number:
```
ucxl://council-sched:scheduler@DistOS:sched/~~7/spec/preemption-policy
```
This is exactly version 7 of the preemption policy, regardless of how many versions now exist.

Council-arch Traversers use these mechanisms to reconstruct decision chains. When a specification artifact changes, the previous version is reachable via `*~1`. The version before that is `*~2`, and so on back to the origin (`~~1`). By traversing this chain and reading the commit message, author agent, and timestamp at each step, a complete chronological narrative of how that artifact evolved can be constructed.

**Decision graph traversal:** Beyond single-artifact chains, council-arch must also navigate cross-artifact dependencies. When artifact A references artifact B, and B changes, A may be affected. Traversers must be capable of:
- Identifying all artifacts that reference a given UCXL address
- Traversing the full transitive dependency graph for any artifact
- Finding the temporal moment at which two artifacts' versions were mutually consistent

Key references:
- Lampson, B. W. (1983). "Hints for Computer System Design." SOSP 1983. (Provenance and audit trails in system design.)
- Lomet, D. B. (2001). "The Case for Always Full Logging." VLDB 2001. (Temporal database principles applicable to UCXL versioning.)
- Snodgrass, R. T. (1999). Developing Time-Oriented Database Applications in SQL. Morgan Kaufmann. (Temporal querying patterns directly applicable to UCXL navigation.)

### 2. Narrative Generation from Decision Chains

Converting a sequence of UCXL artifacts and their diffs into a coherent human-readable narrative is a non-trivial task. Council-arch Narrators must:

- Identify the decision points (moments when a meaningful choice was made between alternatives)
- Identify the context that existed at the time (what other artifacts were current, what constraints were known)
- Explain the alternatives that were not chosen (from proposal artifacts)
- Explain the rationale that was recorded (from decision artifacts and quorum records)
- Write this as a story that a human reader finds comprehensible and that correctly represents the technical content

The narrative must not editorialize or second-guess decisions. It must represent what actually happened in the decision-making process, sourced entirely from UCXL-addressed artifacts.

**Narrative structure for a single decision:**
```
Decision: [What was decided, in plain language]
Context: [What was the state of the system design when this decision was made?]
Trigger: [What prompted this decision? A conflict? A new constraint? A proposal?]
Alternatives Considered: [What other options were on the table, from proposal artifacts]
Reasoning: [What logic was applied, sourced from deliberation artifacts]
Decision Makers: [Which agents/councils made this decision, with their UCXL addresses]
Impact: [Which other artifacts were updated as a result of this decision]
UCXL Source Chain: [The UCXL addresses of every artifact in this decision chain]
```

Key references:
- Bruner, J. (1986). Actual Minds, Possible Worlds. Harvard University Press. (Narrative as a cognitive mode for understanding complex sequences of events.)
- van Dijk, T. A., & Kintsch, W. (1983). Strategies of Discourse Comprehension. Academic Press. (How humans comprehend complex information through narrative macrostructure.)
- Klein, G. (2008). "Naturalistic Decision Making." Human Factors 50(3). (How decision narratives support sensemaking in complex domains.)

### 3. Conflict Resolution Storytelling

Cross-council conflicts are the most complex decision chains to narrate. When council-sched proposes a scheduling policy that conflicts with a memory guarantee claimed by council-mem, a series of events unfolds:

1. The conflict is detected (by whom? council-synth's monitoring, or by a council agent encountering an inconsistency?)
2. The conflict is escalated (what channel? what UCXL addresses are involved?)
3. Proposals are made by each side
4. Council-synth mediates
5. A resolution is reached
6. Both councils update their specifications to reflect the resolution

Council-arch must narrate this entire arc in a way that explains:
- Why the conflict arose in the first place (what assumptions each council was making)
- What was at stake (what would have been lost by each possible resolution)
- How the resolution was reached (what compromise or synthesis was found)
- What the long-term consequences of the resolution are (which downstream decisions were affected)

**Worked example: Scheduling vs. Memory Conflict**

Suppose council-sched proposes preemptive GPU kernel migration as a scheduling mechanism, and council-mem objects that this requires GPU memory to remain addressable after the kernel context is suspended — violating their isolation model. The conflict resolution narrative must explain:

- The scheduling motivation: why preemptive migration is necessary for fair scheduling at 1024-node scale
- The memory motivation: why cross-context memory addressability is a security boundary violation
- The resolution: perhaps a restricted migration model where memory is remapped but not cross-accessible during migration
- The compromise cost: the migration overhead is higher than the pure preemptive model, requiring scheduler adjustments

This narrative is the intellectual history of a design trade-off. It is the most valuable content council-arch produces.

Key references:
- Fischer, M. J., Lynch, N. A., & Paterson, M. S. (1985). "Impossibility of Distributed Consensus with One Faulty Process." JACM 32(2). (The archetypal example of why distributed system design involves irreducible trade-offs — understanding the FLP impossibility theorem requires understanding the chain of reasoning that leads to it.)
- Lamport, L. (1978). "Time, Clocks, and the Ordering of Events in a Distributed System." CACM 21(7). (Decision chains in distributed systems require temporal reasoning that Lamport's original narrative illuminates.)
- Brooks, F. P. (1975). The Mythical Man-Month. Addison-Wesley. Chapter 2: The Tar Pit. (The intellectual history of design decisions in complex systems.)

### 4. Decision Impact Analysis

When a decision changes, its impact propagates through the dependency graph. Council-arch Impact Analysts must quantify and narrate this propagation.

**Impact analysis process:**
1. Identify the changed artifact at its UCXL address
2. Query the cross-reference registry (maintained by council-docs) for all artifacts that reference this address
3. For each dependent artifact, determine whether the change constitutes a breaking change (the dependent artifact's assumptions are violated) or a compatible change
4. Trace the transitive impact: do any of the immediately affected artifacts in turn affect further artifacts?
5. Produce an impact map showing the full propagation graph
6. Write a narrative explaining which systems are affected and why

**UCXL impact query pattern:**
```
# Find all artifacts that reference a changed artifact
ucxl://council-sched:scheduler@DistOS:sched/*~1/spec/preemption-policy
# (version before the change)
→ find-references: which artifacts cited this version?
→ for each: does the change break the citing artifact's assumptions?
```

Key references:
- Lehman, M. M., & Belady, L. A. (1985). Program Evolution: Processes of Software Change. Academic Press. (How changes propagate through complex software systems — directly applicable to specification change propagation.)
- Parnas, D. L. (1972). "On the Criteria to be Used in Decomposing Systems into Modules." CACM 15(12). (Information hiding and the management of change impact in system design.)

### 5. Visualisation of Decision Graphs

Decision chains are not linear — they branch, merge, and form complex directed acyclic graphs (or occasionally cyclic graphs when councils revisit earlier decisions). Council-arch must produce visual representations of these graphs.

**Decision graph elements:**
- Nodes: individual decision events (a council making a choice between alternatives)
- Edges: causal relationships (decision A enabled or constrained decision B)
- Temporal dimension: the sequence in which decisions were made
- Council dimension: which councils were involved in each decision
- Conflict markers: points where cross-council disagreement occurred
- Resolution markers: points where council-synth resolved a conflict

**Graph visualisation standards:**
- DOT language (Graphviz) for machine-generated decision graphs
- D3.js-compatible JSON for interactive browser-based exploration
- Static PNG/SVG exports for inclusion in documentation

The decision graph for the entire DistOS project — all councils, all phases — is the single most valuable artifact council-arch produces. It is the complete intellectual history of the specification in visual form.

Key references:
- Sugiyama, K., Tagawa, S., & Toda, M. (1981). "Methods for Visual Understanding of Hierarchical System Structures." IEEE Transactions on Systems, Man, and Cybernetics 11(2). (Foundational algorithm for laying out directed graphs — the Sugiyama framework is standard in Graphviz and similar tools.)
- Battista, G. D., Eades, P., Tamassia, R., & Tollis, I. G. (1999). Graph Drawing: Algorithms for the Visualization of Graphs. Prentice Hall.

### 6. The "Why Was This Decided?" Query Interface

Council-arch must support an interactive query capability: given any artifact or decision in DistOS, a human should be able to ask "why was this decided this way?" and receive a clear, sourced answer.

**Query answering process:**
1. Receive a natural language query referencing a DistOS decision
2. Identify the relevant UCXL artifact(s) using temporal addressing
3. Traverse the decision chain that produced that artifact
4. Retrieve related deliberation artifacts, proposal artifacts, and conflict resolution records
5. Synthesise a narrative answer that cites specific UCXL-addressed sources
6. Present the answer with full provenance: every claim is linked to a UCXL artifact

Example query: "Why does the DistOS scheduler use work-stealing rather than centralised queuing for GPU job distribution?"

Expected answer structure:
```
The DistOS scheduler uses work-stealing because:

[1] On Day 4, council-sched initially proposed centralised queuing 
    (ucxl://council-sched:scheduler@DistOS:sched/~~3/proposal/scheduling-model-v1).
    
[2] Council-net raised a scalability concern: centralised queuing 
    at 1024 nodes requires the queue coordinator to handle ~50k 
    scheduling decisions per second, exceeding its modelled capacity
    (ucxl://council-net:scalability-analyst@DistOS:net/~~5/objection/queue-throughput).
    
[3] Council-synth mediated and proposed work-stealing as an alternative,
    citing the Cilk scheduler as a reference implementation
    (ucxl://council-synth:mediator@DistOS:synth/~~8/resolution/scheduling-model).
    
[4] Council-sched accepted the resolution and updated the scheduling 
    specification on Day 5
    (ucxl://council-sched:scheduler@DistOS:sched/~~7/spec/scheduling-model).

The work-stealing choice trades centralised visibility for distributed
scalability. The implications for fairness guarantees are documented in
ADR-047 (ucxl://council-docs:formatter@DistOS:docs/~~23/adr/ADR-047).
```

### 7. Daily and Weekly Progress Summaries

Council-arch produces structured summaries at regular intervals:

**Daily summary (end of each project day):**
- Decisions made across all councils in the past 24 hours
- Conflicts opened and their current status
- Conflicts resolved and the resolution narratives
- New artifacts published and their significance
- Key open questions that remain unresolved

**Phase summary (at each phase boundary):**
- Major architectural decisions made in this phase
- How the design evolved from the start to the end of the phase
- Unresolved issues carried forward
- How phase deliverables relate to the overall DistOS design

**Final summary (Day 14):**
- The complete intellectual history of DistOS in narrative form
- The 10 most consequential decisions and why they shaped the design
- The 5 hardest conflicts and how they were resolved
- What CHORUS and UCXL proved about AI agent collective design

---

## Agent Roles

| Role | Count | Responsibilities |
|------|-------|-----------------|
| **Narrators** | 15 | Write human-readable decision stories from UCXL artifact chains; produce daily summaries; write conflict resolution narratives; maintain narrative consistency across the full project arc |
| **Traversers** | 10 | Continuously navigate UCXL temporal graphs across all councils; extract decision paths; identify when artifacts change and trace the causal chain; maintain the live decision graph database |
| **Impact Analysts** | 10 | Trace how decisions propagate through the dependency graph; identify breaking changes; produce impact maps when significant decisions are made; flag unresolved downstream consequences to council-synth |
| **Summarisers** | 5 | Produce executive-level overviews at phase boundaries; write the "why was this decided?" query responses; generate the final project summary; support council-docs with rationale sections |

**Total: 40 agents**

---

## Key Deliverables

| Deliverable | UCXL Address | Due Phase |
|-------------|--------------|-----------|
| UCXL Traversal Methodology | `ucxl://council-arch:traverser@DistOS:arch/*^/spec/traversal-methodology` | Phase 1 |
| Narrative Template Library | `ucxl://council-arch:narrator@DistOS:arch/*^/template/narrative-templates` | Phase 1 |
| Decision Graph Schema | `ucxl://council-arch:traverser@DistOS:arch/*^/spec/decision-graph-schema` | Phase 2 |
| Live Decision Graph (continuous) | `ucxl://council-arch:traverser@DistOS:arch/*^/graph/decision-graph-live` | Phase 2 (continuous) |
| Daily Progress Summary — Day 1 | `ucxl://council-arch:summariser@DistOS:arch/*^/summary/day-01` | Phase 1 |
| Daily Progress Summary — Day N | `ucxl://council-arch:summariser@DistOS:arch/~~N/summary/day-{N}` | Daily |
| Phase 1 Summary | `ucxl://council-arch:summariser@DistOS:arch/*^/summary/phase-01` | End of Day 3 |
| Phase 2 Summary | `ucxl://council-arch:summariser@DistOS:arch/*^/summary/phase-02` | End of Day 6 |
| Phase 3 Summary | `ucxl://council-arch:summariser@DistOS:arch/*^/summary/phase-03` | End of Day 10 |
| Phase 4 Summary | `ucxl://council-arch:summariser@DistOS:arch/*^/summary/phase-04` | End of Day 12 |
| Conflict Resolution Narratives (all) | `ucxl://council-arch:narrator@DistOS:arch/*^/narrative/conflict-resolutions` | Continuous |
| Impact Analysis Reports (all) | `ucxl://council-arch:impact-analyst@DistOS:arch/*^/analysis/impact-reports` | Continuous |
| "Why Was This Decided?" Query Archive | `ucxl://council-arch:summariser@DistOS:arch/*^/query/why-archive` | Continuous |
| Decision Graph Visualisation | `ucxl://council-arch:traverser@DistOS:arch/*^/diagram/decision-graph-full` | Phase 4 |
| Final Project Narrative | `ucxl://council-arch:narrator@DistOS:arch/*^/narrative/final-project-narrative` | Phase 5 |
| CHORUS Experiment Assessment | `ucxl://council-arch:summariser@DistOS:arch/*^/assessment/chorus-experiment` | Phase 5 |

---

## Decision Points

### DA-01: Traversal Depth Limit
**Question:** How deep should UCXL traversal go when constructing a decision narrative? Some decision chains may be very long (a scheduling policy that changed 15 times over 14 days, each change referencing multiple earlier artifacts).

**Options:**
- A. Traverse the complete chain back to the origin for every narrative — maximum completeness, potentially very long narratives
- B. Traverse to a configurable depth (default: 5 versions back) and provide a "view full chain" link
- C. Summarise long chains: provide the origin, the current state, and the 3 most significant changes, with full chain available on request

**Implications:** Option A produces the most complete narratives but may overwhelm readers. Option C requires Traversers to make judgements about which changes are "most significant" — introducing interpretive risk.

### DA-02: Narrative Granularity Levels
**Question:** Should council-arch produce narratives at a single level of detail, or at multiple granularity levels for different audiences?

**Options:**
- A. Single level: engineer-grade narratives with full UCXL references throughout
- B. Two levels: executive summary + engineer detail, for each major decision
- C. Three levels: one-paragraph executive brief + section-length engineer narrative + complete UCXL chain listing

**Implications:** Option C serves the broadest audience but requires 3x the narrative production effort.

### DA-03: Real-Time vs. Batched Narrative Production
**Question:** Should Narrators write narratives immediately as each decision is made (real-time) or in batches (e.g., end of each day)?

**Options:**
- A. Real-time: narratives produced within minutes of each decision artifact being published
- B. End-of-day batches: narratives produced once per day covering all decisions in the preceding 24 hours
- C. Hybrid: real-time narratives for P0 conflicts and phase-boundary decisions; daily batches for routine decisions

**Implications:** Option A provides the most current view of the project state but may produce premature narratives for decisions that are subsequently revised. Option B risks losing context if the reasoning behind a decision is not recorded promptly.

### DA-04: The Readability Test Methodology
**Question:** How is the ultimate test of council-arch's success — "a human who has never seen the project can understand why the system was designed the way it was" — operationalised?

**Options:**
- A. Internal assessment: Summarisers evaluate whether their own narratives would be comprehensible to a newcomer
- B. Blind test: At Day 14, a set of novel DistOS design questions is posed to an agent who has access only to council-arch's outputs (not the underlying technical specs). If the agent can answer correctly, the test passes.
- C. Human review: The final project narrative is reviewed by a human reader who evaluates comprehensibility

**Implications:** Option B is the most rigorous test of UCXL's information preservation claims. Option C introduces human review into the timeline but provides the most authentic signal.

### DA-05: Conflict Narrative Attribution
**Question:** When narrating a conflict resolution, should the narrative attribute positions to specific agent roles (e.g., "the council-sched Preemption Specialist argued...") or to councils as collective bodies?

**Options:**
- A. Agent-role attribution: name specific roles and their UCXL addresses
- B. Council attribution: treat each council as a single voice
- C. Position attribution: describe positions without attributing to any agent ("the preemption camp argued... the isolation camp argued...")

**Implications:** Option A provides maximum accountability and traceability but may make narratives harder to read. Option C may obscure the council structure. Option B is a readable compromise.

---

## Dependencies on Other Councils

| Council | Dependency Type | What Council-Arch Needs |
|---------|----------------|------------------------|
| **ALL councils** | Critical upstream | Real-time access to all UCXL artifact streams; read access to all decision, proposal, deliberation, and resolution artifacts |
| **council-synth** | Priority upstream | Conflict resolution records are the most narratively significant events; council-synth's mediation artifacts are council-arch's primary source for conflict resolution stories |
| **council-verify** | Upstream | Formal spec evolution history; particularly when invariants are revised in response to conflicts or discoveries |
| **council-qa** | Upstream | Defect discovery events often trigger important decision chains; the story of "how a QA finding changed the architecture" is a key narrative type |
| **council-docs** | Downstream (primary) | Council-arch's narratives feed directly into the documentation council's rationale sections and ADR content |
| **council-docs** | Upstream (cross-reference registry) | Council-arch queries the cross-reference registry to identify which artifacts reference any given UCXL address |

**Unique access requirement:** Council-arch requires read access to ALL UCXL streams across ALL councils. This is the broadest access scope of any council in DistOS, justified by council-arch's function as the universal observer. Council-arch does not write to other councils' namespaces — it only reads.

**The mutual dependency with council-docs:** Council-arch and council-docs have a deeply symbiotic relationship. Council-arch produces narratives; council-docs formats and publishes them. Council-docs raises editorial queries; council-arch answers them by traversing the UCXL record. When an Editor in council-docs encounters a specification section that lacks obvious rationale, the correct action is to query council-arch's narrative archive before raising an editorial query to the technical council.

---

## WHOOSH Configuration

```yaml
council: council-arch
whoosh:
  formation:
    strategy: observer-pattern
    # council-arch operates as a continuous observer of all other councils
    # with internal specialisation by narrative type
    teams:
      - name: traversal-team
        roles: [traverser]
        size: 10
        operation: continuous-monitoring
        # Traversers run 24/7 from Day 1, monitoring all UCXL streams
        trigger: on-any-artifact-change
      - name: narrative-team
        roles: [narrator]
        size: 15
        operation: event-driven
        trigger: on-significant-decision-or-conflict
      - name: impact-team
        roles: [impact-analyst]
        size: 10
        operation: event-driven
        trigger: on-artifact-change-in-referenced-document
      - name: summary-team
        roles: [summariser]
        size: 5
        operation: scheduled
        schedule: end-of-day + end-of-phase + on-query

  quorum:
    narrative-publication: 2/3-narrators  # Two Narrators must agree on a conflict narrative before publication
    impact-assessment: 2/3-impact-analysts
    # Note: council-arch does not vote on technical decisions — quorum here governs narrative quality only

  subchannels:
    - id: ucxl-monitor
      description: Incoming artifact change events from all councils
      subscribers: [council-arch-traversers, council-arch-impact-analysts]
      source: all-councils
      retention: full-history
    - id: narratives-published
      description: Completed narrative artifacts broadcast to consumers
      subscribers: [council-docs, council-synth]
      retention: full-history
    - id: impact-alerts
      description: High-impact decision propagation alerts
      subscribers: [council-synth, affected-councils, council-docs]
      retention: full-history
    - id: daily-summaries
      description: Daily progress summaries
      subscribers: [all-councils]
      retention: full-history
    - id: query-responses
      description: Responses to "why was this decided?" queries
      subscribers: [querying-party, council-docs]
      retention: full-history
    - id: readability-test
      description: Outputs used in the Day 14 readability assessment
      subscribers: [council-docs, designated-assessor]
      retention: full-history

  continuous_monitoring:
    # council-arch monitors everything
    monitor_pattern: "ucxl://*:*@DistOS:*/*"
    # Do not follow external references — DistOS namespace only
    scope: DistOS
    # Trigger narrative generation for significant events
    significance_threshold:
      - event: conflict-opened
        action: queue-conflict-narrative-immediately
      - event: conflict-resolved
        action: queue-resolution-narrative-immediately
      - event: specification-revised
        action: queue-impact-analysis
      - event: new-artifact-published
        action: update-decision-graph
      - event: artifact-deprecated
        action: trace-and-update-cross-references
```

---

## Success Criteria

Council-arch's execution is successful when all of the following are met:

1. **Complete decision graph:** Every decision event across all 12+ councils is represented in the decision graph, with full UCXL provenance. No orphaned decisions exist (decisions that appear in specifications but have no traceable decision chain).

2. **Conflict narrative coverage:** Every cross-council conflict and its resolution has a corresponding narrative in the archaeology record. The narrative correctly identifies the parties, the positions, the resolution, and the UCXL artifacts involved.

3. **Impact analysis coverage:** Every specification change with downstream dependencies has a corresponding impact analysis. No significant breaking change went unanalysed.

4. **Daily summary completeness:** A daily summary was published for every project day, covering all significant decisions of that day.

5. **Phase summary quality:** Each phase summary gives a newcomer sufficient context to understand what was accomplished in that phase and how it advanced the overall design.

6. **Query answering:** The "why was this decided?" query archive contains responses for all major DistOS architectural decisions. A newcomer should be able to find the answer to "why did DistOS choose approach X?" for every significant design choice.

7. **The Readability Test (primary success criterion):** The Final Project Narrative, produced by council-arch and formatted by council-docs, is presented to an evaluator who has not participated in the DistOS design process. The evaluator is asked to answer a set of questions about the rationale behind 10 significant DistOS design decisions. The test passes if the evaluator can correctly explain the reasoning behind at least 8 of the 10 decisions, citing specific evidence from the narrative.

8. **UCXL hypothesis validation:** Every claim in council-arch's narratives is directly traceable to a specific UCXL-addressed artifact. No narrative statement exists without a UCXL source citation. This validates that UCXL preserved enough information for meaningful retrospective analysis.

9. **CHORUS experiment assessment:** The final CHORUS Experiment Assessment document articulates what the DistOS experiment proved about multi-agent AI collaboration: what worked, what failed, what was surprising, and what the implications are for future CHORUS deployments.

---

## Timeline Mapping

| Phase | Days | Council-Arch Activities |
|-------|------|------------------------|
| **Phase 1: Research** | 1–3 | UCXL monitoring infrastructure active from Hour 1 of Day 1; build traversal tooling; define narrative templates; begin decision graph with initial council formation events; publish Day 1, Day 2, Day 3 summaries; produce Phase 1 summary at Day 3 |
| **Phase 2: Architecture** | 3–6 | Narrate the emergence of the core architecture from council-synth's synthesis work; capture early conflict events; produce impact analyses as the first cross-council dependencies form; first "why was this decided?" entries; Phase 2 summary at Day 6 |
| **Phase 3: Formal Specification** | 6–10 | Highest-intensity phase for council-arch: formal specification is being written, conflicts are frequent, specifications are being revised; narrate each conflict resolution in real time; continuous impact analysis; daily summaries every day; Phase 3 summary at Day 10 |
| **Phase 4: Integration** | 10–12 | Narrate cross-subsystem integration decisions; trace how integration testing findings propagate back to specifications; work with council-docs on ADR rationale content; Phase 4 summary at Day 12 |
| **Phase 5: Documentation** | 12–14 | Produce Final Project Narrative; complete decision graph visualisation; compile "why was this decided?" query archive; conduct readability test; write CHORUS Experiment Assessment; support council-docs in final specification publication |

---

## Appendix: UCXL Traversal Examples

The following examples illustrate how council-arch Traversers use UCXL temporal syntax to reconstruct decision chains.

### Example 1: Tracing a Specification Revision

A Traverser observes that the preemption policy specification has been revised:
```
New:  ucxl://council-sched:scheduler@DistOS:sched/*^/spec/preemption-policy
Old:  ucxl://council-sched:scheduler@DistOS:sched/*~1/spec/preemption-policy
```

The Traverser retrieves both versions, computes the diff, and reads the commit metadata:
- Author: `council-sched:preemption-specialist`
- Timestamp: Day 7, 14:23 UTC
- Change reference: `ucxl://council-synth:mediator@DistOS:synth/*~2/resolution/scheduling-memory-conflict`

The Traverser follows the reference to the conflict resolution and retrieves the full conflict chain:
```
ucxl://council-mem:memory-guardian@DistOS:mem/~~12/objection/preemption-memory-violation
ucxl://council-sched:scheduler@DistOS:sched/~~8/proposal/restricted-migration-model
ucxl://council-synth:mediator@DistOS:synth/~~15/resolution/scheduling-memory-conflict
```

This chain is handed to a Narrator to produce the conflict resolution story.

### Example 2: Impact Analysis After a Change

An Impact Analyst observes that the Weka FS consistency claim has been revised:
```
ucxl://council-fs:fs-architect@DistOS:fs/*^/spec/consistency-model
```

The Impact Analyst queries the cross-reference registry for all artifacts that cite this address. The registry returns:
- `ucxl://council-mem:checkpoint-designer@DistOS:mem/~~9/spec/checkpoint-procedure` — depends on the FS consistency model
- `ucxl://council-qa:chaos-engineer@DistOS:qa/~~6/spec/test-strategy` — references the FS consistency claims for test design
- `ucxl://council-verify:model-checker@DistOS:verify/~~11/spec/fs-invariants` — formal invariants depend on FS consistency model

The Impact Analyst evaluates whether the change is breaking for each dependent:
- Checkpoint procedure: breaking (the consistency model was weakened; checkpoint write atomicity assumptions must be revised)
- QA test strategy: non-breaking (tests become more stringent, which is conservative)
- Formal invariants: breaking (invariants must be re-proved under the weaker consistency model)

The Impact Analyst publishes an alert to the `impact-alerts` subchannel and notifies council-synth that council-mem and council-verify have breaking dependencies on the FS consistency change.

---

*Council Design Brief v1.0 — DistOS Project — council-arch*
*Generated: 2026-02-24*
