Initial DistOS project constitution and council design briefs
12 council design briefs for distributed OS specification project targeting 1024-node Hopper/Grace/Blackwell GPU cluster with Weka parallel filesystem. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
anthonyrawlins
531
councils/12-decision-archaeology.md
Normal file
531
councils/12-decision-archaeology.md
Normal file
@@ -0,0 +1,531 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user