mdcontext 0.0.1 → 0.2.0

package/research/dogfood/strategy-c/c-synthesis.md

@@ -0,0 +1,451 @@
+# Strategy C Synthesis: Two-Phase Explore-Then-Dive
+
+## 1. Executive Summary
+
+Strategy C employed a **Two-Phase Explore-Then-Dive** methodology to comprehensively analyze the HumanWork documentation set (23 documents, 179K tokens, 924 sections).
+
+**Phase 1** (C1 Explorer) mapped the documentation landscape, identified the structural organization across three folders (docs/, docs.amorphic/, docs.llm/), and prioritized five themes for deep investigation.
+
+**Phase 2** deployed five specialized divers (C2-C6) who each conducted deep explorations into their assigned themes using the mdcontext tool.
+
+### Key Framework Discovery
+
+HumanWork is a framework for human-AI collaboration that explicitly rejects the "fully autonomous agent" paradigm. Its core innovations are:
+
+1. **Three-Layer Memory Architecture** - Event Memory (immutable facts), Status Memory (derived state), Semantic Memory (knowledge graph) enabling time travel, branching, and perfect resumability
+2. **Control Plane with Preemptive Authority** - Humans retain authority over all execution at all times
+3. **Execution Model** - Jobs (intent), Execution Contexts (disposable actors), Workflows (guidance not execution)
+4. **Org-Workspace Hierarchy** - Clear containment, cost attribution, and governance overlay architecture
+
+### Collective Verdict
+
+The HumanWork specification is **comprehensive, internally consistent, and architecturally sound**. The documentation clearly articulates both the philosophical "why" (failure analysis) and technical "what" (primitives, guarantees, anti-patterns). All six agents achieved high confidence in their findings.
+
+---
+
+## 2. Phase 1 Summary: Explorer Mapping
+
+**Agent**: C1 Explorer
+**Commands Run**: 37
+**Coverage**: All 23 documents mapped
+
+### Documentation Structure Identified
+
+| Folder         | Files | Tokens | Character                                               |
+| -------------- | ----- | ------ | ------------------------------------------------------- |
+| docs/          | 10    | ~40K   | Formal specification (primitives, architecture, models) |
+| docs.amorphic/ | 9     | ~21K   | Philosophy and vision (narrative, failure analysis)     |
+| docs.llm/      | 3     | ~89K   | Aggregated versions for LLM consumption                 |
+
+### Themes Identified for Deep-Dive
+
+1. **Three-Layer Memory Architecture** - Most referenced, most complex
+2. **Human-Agent Control Model** - Core differentiator from autonomous frameworks
+3. **Failure of Pure Automation** - Explains design decisions
+4. **Execution Model** - Operational complexity
+5. **Org-Workspace Model** - Enterprise governance angle
+
+### Additional Themes Noted (Not Assigned to Divers)
+
+- Letta Integration (docs/LETTA_INTEGRATION_PLAN.md)
+- Observability & Transparency
+- 20 Formal Primitives (docs/02-PRIMITIVES.md)
+
+---
+
+## 3. Phase 2 Diver Findings
+
+### C2: Memory Architecture
+
+**Commands Run**: 27
+**Key File**: docs/05-MEMORY_MODEL.md (6.8K tokens, 17 sections)
+
+#### Core Findings
+
+| Layer           | Purpose                     | Authority                          | Tech Examples     |
+| --------------- | --------------------------- | ---------------------------------- | ----------------- |
+| Event Memory    | Immutable log of all events | **Source of truth**                | EventStoreDB, WAL |
+| Status Memory   | Derived operational state   | Ephemeral, recomputable            | Redis, PostgreSQL |
+| Semantic Memory | Knowledge graph             | Advisory only, never authoritative | Neo4j, Graphiti   |
+
+#### Key Insights
+
+- **Event Memory is the single source of truth** - All other layers can be rebuilt from it
+- **Hard Rule**: "Status Memory must be fully derivable from Event Memory"
+- **Non-Authoritative Rule**: "Semantic Memory advises but never controls"
+- **Time travel is a query, not a feature** - Natural consequence of immutable events
+- **5-Step Context Resumption Pattern**: Query Events -> Artifacts -> Status -> Semantic -> Assemble
+
+#### Critical Quote
+
+> "Memory is the connective tissue that enables long-running, interruptible human work with perfect continuity and trust."
+
+---
+
+### C3: Human-Agent Control Model
+
+**Commands Run**: 30
+**Key Files**: docs/01-ARCHITECTURE.md, docs.amorphic/04-THE_HUMAN-AGENT_COLLABORATION_MODEL.md
+
+#### Core Findings
+
+| Mechanism          | Description                                                  |
+| ------------------ | ------------------------------------------------------------ |
+| Control Plane      | Central authority with preemptive control over all execution |
+| Authority Gradient | Dynamic spectrum from instructional to supervisory           |
+| Checkpoints        | Deliberate pauses for human re-engagement                    |
+| Override Principle | Every suggestion overridable, logged, not penalized          |
+
+#### Four Collaboration Modes
+
+1. **Instructional** - Step-by-step human direction
+2. **Consultative** - Human makes decisions with agent input
+3. **Supervisory** - Broad autonomy with monitoring
+4. **Exploratory** - Open-ended investigation
+
+#### Key Insight
+
+Humans can move anywhere along the authority gradient **at any moment, even mid-execution**.
+
+#### Architectural Invariant
+
+> "No loss of human authority" - explicitly listed as a system-wide invariant
+
+---
+
+### C4: Failure Analysis
+
+**Commands Run**: 20
+**Key File**: docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md (2.8K tokens)
+
+#### Six Failure Modes of Pure Automation
+
+| #   | Failure Mode             | Core Problem                                             |
+| --- | ------------------------ | -------------------------------------------------------- |
+| 1   | Brittleness              | Combinatorial rule explosion creates rigid systems       |
+| 2   | Coordination Trap        | Tools become the work, not enablers of work              |
+| 3   | Innovation Strangulation | System optimizes for processable, not valuable work      |
+| 4   | Human Bottleneck Paradox | Automating around humans creates new bottlenecks         |
+| 5   | Context Collapse         | Context is conversational, not configurable              |
+| 6   | Judgment Gap             | 80% flawless, 20% chaos - and the 20% often matters most |
+
+#### Key Insight
+
+Enterprise adoption has stalled due to two core issues: **Opacity** (we don't know how the agent works) and **Risk** (we can't trust it to run unsupervised).
+
+#### Solution: Human-AI Symbiosis
+
+> "This isn't about making AI more human or humans more machine-like. Instead... genuine cognitive partnerships where each intelligence type contributes its strengths."
+
+---
+
+### C5: Execution Model
+
+**Commands Run**: 32 (100% useful)
+**Key Files**: docs/04-EXECUTION_MODEL.md (7.4K tokens), docs/06-WORKFLOWS.md (8.5K tokens)
+
+#### Model Components
+
+| Component          | Role                          | Key Property                                        |
+| ------------------ | ----------------------------- | --------------------------------------------------- |
+| Jobs               | Human-meaningful coordination | Survives execution attempts, NO stored state        |
+| Execution Contexts | Disposable actors             | Emit permanent records but are themselves temporary |
+| Workflows          | Guidance patterns             | Do NOT execute - only coordinate                    |
+| Steps              | Atomic units                  | Owned by role, emit progress                        |
+| Agents             | Stateless workers             | Receive assembled context, fully replaceable        |
+
+#### Hard Concurrency Rule
+
+> "No two Execution Contexts may concurrently mutate the same scope of work."
+
+#### Key Insight
+
+Because the system is fully immutable:
+
+- Contexts do not mutate - they produce new artifacts
+- "Conflict" is just parallel alternatives
+- Resolution is a separate, explicit act
+
+> "This transforms conflicts from correctness problems into choice problems."
+
+#### Seven System Guarantees
+
+1. Single-scope coherence
+2. Human control (always interruptible)
+3. Deterministic replay
+4. Cost attribution
+5. No hidden state
+6. Agent replaceability
+7. Workflow interoperability
+
+---
+
+### C6: Org-Workspace Model
+
+**Commands Run**: 29
+**Key Files**: docs/03-ORG_WORKSPACE_MODEL.md, docs/07-EXAMPLE_WORKFLOWS.md
+
+#### Two-Tier Hierarchy
+
+```
+Org (identity, ownership, learning)
+  |
+Workspace (execution boundary, strict isolation)
+  |
+Jobs -> Execution Contexts -> Steps/Agents
+  |
+Artifacts/Records (immutable facts)
+```
+
+#### Key Invariant
+
+> "Authority never flows downward" - Org-level artifacts can be suggested but never auto-attach, auto-execute, or auto-override.
+
+#### Cost Attribution Model
+
+| Level             | Tracks                                 |
+| ----------------- | -------------------------------------- |
+| Execution Context | Tokens, tool calls, compute time       |
+| Job               | Aggregated contexts, visible to humans |
+| Workspace         | All jobs, org-level reporting          |
+
+#### Agent Limitations (Explicit)
+
+Agents **cannot**:
+
+- Create Workspaces
+- Promote artifacts
+- Invite users
+- Have Org-level roles
+
+> "Keeps humans firmly in control"
+
+#### Governance Philosophy
+
+Default is **permissive** (trust-by-default). Enterprise controls are **optional policy overlays**.
+
+---
+
+## 4. Cross-Theme Patterns
+
+Recurring themes that appeared across multiple divers:
+
+### 4.1 Immutability as Foundation
+
+| Agent          | Observation                                          |
+| -------------- | ---------------------------------------------------- |
+| C2 (Memory)    | Event Memory is append-only, never mutated           |
+| C3 (Control)   | Immutable records enable guaranteed interruptibility |
+| C5 (Execution) | Contexts produce new artifacts, never mutate         |
+| C6 (Org)       | Audit trail via immutable events                     |
+
+### 4.2 Human Authority Preserved
+
+| Agent          | Observation                                             |
+| -------------- | ------------------------------------------------------- |
+| C3 (Control)   | "No loss of human authority" as architectural invariant |
+| C4 (Failure)   | Addresses "Opacity and Risk" barriers                   |
+| C5 (Execution) | Human control guarantee in system guarantees            |
+| C6 (Org)       | Agents explicitly excluded from org-level authority     |
+
+### 4.3 Derivation Hierarchy (No Circular Dependencies)
+
+| Agent          | Observation                                     |
+| -------------- | ----------------------------------------------- |
+| C2 (Memory)    | Event -> Status -> Semantic (clean derivation)  |
+| C5 (Execution) | Jobs derive status from signals, don't store it |
+| C6 (Org)       | Knowledge Graph is derived, not authoritative   |
+
+### 4.4 Disposable Execution, Durable Intent
+
+| Agent          | Observation                              |
+| -------------- | ---------------------------------------- |
+| C2 (Memory)    | Status Memory can be deleted and rebuilt |
+| C5 (Execution) | Contexts are disposable, Jobs survive    |
+| C6 (Org)       | Dormant Workspaces incur minimal cost    |
+
+### 4.5 Advisory vs Authoritative Distinction
+
+| Agent          | Observation                                  |
+| -------------- | -------------------------------------------- |
+| C2 (Memory)    | Semantic Memory advises but never controls   |
+| C5 (Execution) | Workflows guide but do not execute           |
+| C6 (Org)       | Org artifacts suggested, never auto-attached |
+
+---
+
+## 5. Proposed Spec Changes
+
+Consolidated and prioritized from all agents:
+
+### High Priority (Mentioned by 2+ Agents)
+
+| Proposal                                                                       | Source(s) |
+| ------------------------------------------------------------------------------ | --------- |
+| Add comparison table: HumanWork vs other frameworks (LangGraph, AutoGPT, etc.) | C3, C4    |
+| Document the Control Plane API/interface concretely                            | C3, C5    |
+| Add diagrams for hierarchies (Memory layers, Job->Context->Steps->Agents)      | C2, C5    |
+| Clarify checkpoint enforcement mechanisms (how is "required" enforced?)        | C3, C5    |
+| Define retention/archival policies                                             | C2, C6    |
+
+### Medium Priority (Unique but Significant)
+
+| Proposal                                                                           | Source |
+| ---------------------------------------------------------------------------------- | ------ |
+| Clarify Event Memory vs Artifact Store distinction                                 | C2     |
+| Add concrete Record type schemas with examples                                     | C2     |
+| Specify max acceptable latency for Status Memory queries                           | C2     |
+| Add "Human Authority Guarantees" section listing all control mechanisms            | C3     |
+| Add authority gradient transition examples (Supervisory -> Instructional mid-task) | C3     |
+| Add "Failure Modes Addressed" section mapping features to failure modes            | C4     |
+| Document the "tools become the work" anti-pattern as key problem statement         | C4     |
+| Add "Opacity and Risk" as top-level enterprise adoption barriers                   | C4     |
+| Add glossary entry clarifying "scope" types                                        | C5     |
+| Add guidance on when to use parallel vs serial execution patterns                  | C5     |
+| Clarify Semantic Memory's contribution to context resumption                       | C5     |
+| Add scope conflict resolution workflow example                                     | C5     |
+| Add cost budget alerts/limits API to Cost Model section                            | C6     |
+| Define formal promotion workflow stages (propose, review, approve, publish)        | C6     |
+| Clarify how Org Knowledge Graph surfaces in Workspace UX                           | C6     |
+| Define multi-Org scenarios and cross-Org patterns                                  | C6     |
+| Add monitoring/dashboard primitives for cost visibility                            | C6     |
+
+---
+
+## 6. Tool Evaluation Synthesis
+
+### 6.1 Aggregate Scores
+
+| Agent        | Would Use Again (1-5) | Confidence Level |
+| ------------ | --------------------- | ---------------- |
+| C1 Explorer  | 4                     | High             |
+| C2 Memory    | 4                     | High             |
+| C3 Control   | 4                     | High             |
+| C4 Failure   | 4                     | High             |
+| C5 Execution | **5**                 | High             |
+| C6 Org       | 4                     | High             |
+
+**Average Score**: 4.17/5
+**Confidence**: 6/6 High
+
+### 6.2 Common Praise (What Worked Well)
+
+| Feature                                                       | Mentions | Details                                                 |
+| ------------------------------------------------------------- | -------- | ------------------------------------------------------- |
+| `mdcontext tree <file>` - Document outlines with token counts | 6/6      | "Perfect for planning", "Invaluable for prioritization" |
+| `mdcontext context --section` - Precise section extraction    | 5/6      | "Game-changer for deep dives", "Surgical extraction"    |
+| `mdcontext search` - Fast keyword discovery                   | 6/6      | "Found relevant content quickly", "Good context lines"  |
+| `mdcontext context --sections` - Section listing              | 4/6      | "Essential for finding exact section names"             |
+| `mdcontext stats` - Quick index overview                      | 3/6      | "Instant scope understanding"                           |
+| Token budgeting (`-t` flag)                                   | 2/6      | "Respects limits while showing included/excluded"       |
+| Boolean operators (OR, AND)                                   | 2/6      | "Worked as expected"                                    |
+
+### 6.3 Common Frustrations (Pain Points)
+
+| Issue                                           | Mentions | Details                                                                  |
+| ----------------------------------------------- | -------- | ------------------------------------------------------------------------ |
+| Multi-word search returns 0 results             | 5/6      | "failure automation", "job context", "pause resume terminate" all failed |
+| Search results capped at 10                     | 4/6      | "No pagination", "Sometimes wanted more matches"                         |
+| Section name requires exact match               | 3/6      | "Had to list sections first", "Numbering prefix required"                |
+| No embeddings/semantic search                   | 4/6      | "Would help with concept exploration"                                    |
+| Context command syntax confusion                | 3/6      | Initial failures with positional arguments vs flags                      |
+| Default context truncation unclear              | 2/6      | "36% shown with no explicit warning"                                     |
+| Cannot search within specific file              | 2/6      | "Had to search globally then filter mentally"                            |
+| Cannot request multiple sections in one command | 2/6      | "Had to call once per section"                                           |
+
+### 6.4 Suggested Improvements with Frequency
+
+| Improvement                               | Mentions |
+| ----------------------------------------- | -------- |
+| Enable semantic search (embeddings)       | 4/6      |
+| Support multi-word phrase search          | 5/6      |
+| Increase or remove search result limit    | 4/6      |
+| Add fuzzy/partial section name matching   | 3/6      |
+| Allow file-scoped search                  | 2/6      |
+| Allow multiple `--section` flags          | 2/6      |
+| Add duplicate content detection           | 1/6      |
+| Add cross-file relationship detection     | 1/6      |
+| Show explicit "section won't fit" warning | 1/6      |
+
+### 6.5 Overall Verdict on mdcontext Tool
+
+**Highly Effective for Structured Documentation Research**
+
+The mdcontext tool enabled efficient exploration of a large documentation corpus (179K tokens) that would be impossible to read directly. The **tree-search-context workflow** emerged as the optimal pattern:
+
+1. `mdcontext tree <file>` - See structure and token counts
+2. `mdcontext context --sections <file>` - Get exact section names
+3. `mdcontext context <file> --section "X"` - Extract needed sections
+4. `mdcontext search "term"` - Find cross-references
+5. Repeat as needed
+
+**Strengths**: Excellent for systematic exploration of well-structured markdown. Section-level extraction is a major differentiator. Token-aware budgeting enables efficient context management.
+
+**Weaknesses**: Keyword search limitations (multi-word phrases, result caps) and lack of semantic search reduce effectiveness for conceptual exploration.
+
+**Verdict**: Would recommend for structured documentation research. The 4.17/5 average with 100% high confidence indicates the tool successfully supported deep investigative work.
+
+---
+
+## 7. Methodology Assessment
+
+### How Well Did Explore-Then-Dive Work?
+
+**Very Effective** - The two-phase approach yielded comprehensive coverage with manageable cognitive load.
+
+### Phase 1 Effectiveness
+
+| Aspect               | Assessment                                                    |
+| -------------------- | ------------------------------------------------------------- |
+| Theme identification | Excellent - 5 themes covered all major architectural concerns |
+| Prioritization       | Good - Memory and Control emerged as correctly prioritized    |
+| Discovery efficiency | High - 37 commands mapped 23 documents                        |
+| Handoff quality      | Good - Clear search hints and key files for divers            |
+
+### Phase 2 Effectiveness
+
+| Aspect                | Assessment                                       |
+| --------------------- | ------------------------------------------------ |
+| Coverage depth        | Excellent - All divers achieved high confidence  |
+| Finding consistency   | High - Cross-theme patterns emerged naturally    |
+| Spec change proposals | Comprehensive - 20+ actionable suggestions       |
+| Tool evaluation       | Detailed - Clear patterns for future improvement |
+
+### Methodology Strengths
+
+1. **Reduced duplication** - Explorer mapped landscape once, divers didn't repeat
+2. **Parallel investigation** - Divers could work independently on themes
+3. **Cross-pollination** - Cross-theme patterns emerged from synthesis
+4. **Cognitive efficiency** - Each agent had focused, manageable scope
+
+### Methodology Weaknesses
+
+1. **Theme boundaries** - Some overlap (e.g., Control appears in both C3 and C5)
+2. **Missing themes** - Letta Integration, Primitives not deeply explored
+3. **No iteration** - Divers couldn't request Explorer to map additional areas
+
+### Recommendations for Future Use
+
+1. **Explorer should flag potential overlaps** - Help divers coordinate shared concepts
+2. **Include iteration cycle** - Allow divers to request additional exploration
+3. **Consider 6-8 themes** - 5 themes left some areas shallow
+4. **Assign cross-cutting themes** - One diver could track recurring patterns
+
+---
+
+## Appendix: Command Statistics
+
+| Agent        | Commands | Useful        | Highly Useful  |
+| ------------ | -------- | ------------- | -------------- |
+| C1 Explorer  | 37       | 35 (95%)      | N/A            |
+| C2 Memory    | 27       | 25 (93%)      | 20+            |
+| C3 Control   | 30       | 30 (100%)     | 20+            |
+| C4 Failure   | 20       | 18 (90%)      | 15+            |
+| C5 Execution | 32       | 32 (100%)     | 20 (63%)       |
+| C6 Org       | 29       | 28 (97%)      | 20+            |
+| **Total**    | **175**  | **168 (96%)** | **~100 (57%)** |
+
+---
+
+_Synthesis generated from Strategy C reports (C1-C6)_
+_Total documentation corpus: 23 files, 179K tokens, 924 sections_

package/research/dogfood/strategy-c/c1-explorer.md

@@ -0,0 +1,192 @@
+# Report: C1 - Explorer
+
+## Mission
+
+Map the documentation landscape and identify themes for deep-dive.
+
+## Command Log
+
+| #   | Command                                                | Purpose                    | Result                                       | Useful? |
+| --- | ------------------------------------------------------ | -------------------------- | -------------------------------------------- | ------- |
+| 1   | `mdcontext --help`                                     | Learn tool                 | Full help with commands, examples, workflows | Yes     |
+| 2   | `mdcontext index --force`                              | Force reindex              | Ran in background                            | N/A     |
+| 3   | `mdcontext index`                                      | Index files                | Ran in background                            | N/A     |
+| 4   | `mdcontext stats`                                      | Understand scope           | 23 docs, 179K tokens, 924 sections           | Yes     |
+| 5   | `mdcontext tree docs/`                                 | See docs structure         | 10 files listed                              | Yes     |
+| 6   | `mdcontext tree docs.amorphic/`                        | See amorphic structure     | 9 files listed                               | Yes     |
+| 7   | `mdcontext tree docs.llm/`                             | See llm structure          | 3 files (one massive 56K)                    | Yes     |
+| 8   | `mdcontext tree docs/00-README.md`                     | Outline of README          | Clear structure                              | Yes     |
+| 9   | `mdcontext tree docs/01-ARCHITECTURE.md`               | Outline of arch            | 17 major sections                            | Yes     |
+| 10  | `mdcontext tree docs/02-PRIMITIVES.md`                 | Outline of primitives      | 20 primitives defined                        | Yes     |
+| 11  | `mdcontext tree docs/05-MEMORY_MODEL.md`               | Outline of memory          | 17 sections, deep                            | Yes     |
+| 12  | `mdcontext tree docs.amorphic/01-EXECUTIVE_SUMMARY.md` | Outline exec summary       | Vision/market focus                          | Yes     |
+| 13  | `mdcontext tree docs.amorphic/02-THE_FAILURE...md`     | Outline failure doc        | 6 failure modes                              | Yes     |
+| 14  | `mdcontext tree docs.amorphic/04-THE_HUMAN-AGENT...md` | Outline collab model       | Trust architecture                           | Yes     |
+| 15  | `mdcontext tree docs.llm/spec.md`                      | Outline combined spec      | 56K tokens - full spec combined              | Yes     |
+| 16  | `mdcontext tree docs.llm/amorphic.md`                  | Outline amorphic combined  | 21K tokens                                   | Yes     |
+| 17  | `mdcontext tree docs.llm/feedback.md`                  | Outline feedback           | 11K tokens - landing pages, BDI              | Yes     |
+| 18  | `mdcontext search "human"`                             | Find human-centric content | 10 hits, core principle                      | Yes     |
+| 19  | `mdcontext search "memory"`                            | Find memory content        | 10 hits, three-layer arch                    | Yes     |
+| 20  | `mdcontext search "workflow"`                          | Find workflow content      | 10 hits, guidance model                      | Yes     |
+| 21  | `mdcontext search "agent"`                             | Find agent content         | 10 hits, replaceable agents                  | Yes     |
+| 22  | `mdcontext search "control"`                           | Find control content       | 10 hits, Control Plane key                   | Yes     |
+| 23  | `mdcontext search "org OR workspace"`                  | Find org model             | 10 hits, multi-layer                         | Yes     |
+| 24  | `mdcontext search "failure OR problem..."`             | Find problems              | 10 hits                                      | Yes     |
+| 25  | `mdcontext search "collaboration"`                     | Find collaboration         | 10 hits, multi-human                         | Yes     |
+| 26  | `mdcontext search "transparency OR observability"`     | Find observability         | 10 hits, core principle                      | Yes     |
+| 27  | `mdcontext search "Letta"`                             | Find Letta integration     | 10 hits, integration plan                    | Yes     |
+| 28  | `mdcontext search "event"`                             | Find event-driven content  | 10 hits, Event Memory                        | Yes     |
+| 29  | `mdcontext search "immutable"`                         | Find immutability          | 10 hits, core principle                      | Yes     |
+| 30  | `mdcontext search "cost"`                              | Find cost management       | 10 hits, workspace-level                     | Yes     |
+| 31  | `mdcontext search "automation OR autonomous"`          | Find automation critique   | 10 hits, failure theme                       | Yes     |
+| 32  | `mdcontext tree docs/HumanWork-Evolution.md`           | Check evolution doc        | 7500 tokens, no sections                     | Partly  |
+| 33  | `mdcontext tree docs.amorphic/05-TECHNICAL...md`       | Check tech patterns        | 5 key patterns                               | Yes     |
+| 34  | `mdcontext tree docs.amorphic/06-ORGANIZATIONAL...md`  | Check org transformation   | 13 sections                                  | Yes     |
+| 35  | `mdcontext tree docs.amorphic/08-FUTURE...md`          | Check future directions    | Research agenda                              | Yes     |
+| 36  | `mdcontext search "time travel OR branching"`          | Find temporal features     | 10 hits, core feature                        | Yes     |
+| 37  | `mdcontext search "semantic"`                          | Find semantic layer        | 10 hits, knowledge graph                     | Yes     |
+
+## Landscape Overview
+
+### docs/ Structure (Original Spec)
+
+**10 files, ~40K tokens, highly structured**
+
+Core documentation for the HumanWork framework:
+
+- **00-README.md** (1.6K tokens): Mission statement, core principles (Human Control, Immutability, Observability, Metadata-Driven, Replaceable Agents)
+- **01-ARCHITECTURE.md** (5K tokens): 17 architectural layers from Control Plane to Memory
+- **02-PRIMITIVES.md** (6.8K tokens): 20 formal primitives with definitions, properties, guarantees, lifecycle
+- **03-ORG_WORKSPACE_MODEL.md**: Identity, cost, authority model
+- **04-EXECUTION_MODEL.md**: Jobs, contexts, workflows execution
+- **05-MEMORY_MODEL.md** (6.8K tokens): Three-layer memory (Event, Status, Semantic)
+- **06-WORKFLOWS.md**: Workflow philosophy and definition format
+- **07-EXAMPLE_WORKFLOWS.md**: 5 concrete scenarios (Individual, Team, Research, Engineering, Enterprise)
+- **HumanWork-Evolution.md** (7.5K tokens): Evolution ideas - single section, less structured
+- **LETTA_INTEGRATION_PLAN.md**: Memory system integration plan with Letta/MemGPT
+
+### docs.amorphic/ Structure (Chat Analysis)
+
+**9 files, ~21K tokens, narrative style**
+
+Philosophy and vision documents (more prose, less formal):
+
+- **00-INDEX.md**: Table of contents with section previews
+- **01-EXECUTIVE_SUMMARY.md** (1.7K tokens): Core innovation, market disruption potential
+- **02-THE_FAILURE_OF_PURE_AUTOMATION.md** (2.8K tokens): 6 failure modes of current approaches
+- **03-ARCHITECTURAL_FOUNDATIONS.md**: Substrate problem, geometric memory, component relationships
+- **04-THE_HUMAN-AGENT_COLLABORATION_MODEL.md** (2.8K tokens): Authority gradient, collaboration modes, trust architecture
+- **05-TECHNICAL_IMPLEMENTATION_PATTERNS.md** (2.3K tokens): 5 foundational patterns
+- **06-ORGANIZATIONAL_TRANSFORMATION.md** (4K tokens): Cultural shifts, governance, maturity models
+- **08-FUTURE_IMPLICATIONS_AND_RESEARCH_DIRECTIONS.md** (1.8K tokens): Research frontiers, open questions
+- **\_0.BLURB.md**: Marketing/pitch content
+
+### docs.llm/ Structure (Combined Files)
+
+**3 files, ~89K tokens - aggregated versions**
+
+- **spec.md** (56K tokens): All docs/ files concatenated - massive single-file version
+- **amorphic.md** (21K tokens): All docs.amorphic/ files concatenated
+- **feedback.md** (11.6K tokens): Landing page copy, BDI concepts, installation, philosophy
+
+## Themes Identified for Deep-Dive
+
+### 1. **Three-Layer Memory Architecture**
+
+- Why: Central innovation. Event Memory (immutable facts), Status Memory (derived state), Semantic Memory (knowledge graph) - enables time travel, branching, and replay. Referenced in nearly every document.
+- Search hints: `memory`, `event`, `semantic`, `immutable`, `time travel OR branching`
+- Key files: docs/05-MEMORY_MODEL.md, docs/01-ARCHITECTURE.md sections 11-12
+
+### 2. **Human-Agent Control Model**
+
+- Why: Core differentiator from "autonomous agent" frameworks. Control Plane with preemptive authority, explicit human decision points, interruptibility guarantees. The "why" of the entire system.
+- Search hints: `control`, `human`, `authority`, `interrupt`, `preemptive`
+- Key files: docs/00-README.md, docs/01-ARCHITECTURE.md (Control Plane), docs.amorphic/04-THE_HUMAN-AGENT_COLLABORATION_MODEL.md
+
+### 3. **Failure of Pure Automation (Critical Analysis)**
+
+- Why: docs.amorphic/ provides rich analysis of WHY current agent frameworks fail - brittleness, coordination trap, innovation strangulation, context collapse, judgment gap. Understanding these failure modes is crucial for evaluating the solution.
+- Search hints: `failure`, `automation`, `autonomous`, `brittleness`, `coordination`
+- Key files: docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md, docs.amorphic/01-EXECUTIVE_SUMMARY.md
+
+### 4. **Execution Model (Jobs, Contexts, Workflows)**
+
+- Why: Complex model with Jobs (intent over time), Execution Contexts (disposable actors), Workflows (guidance not execution). Parallel execution patterns, context resumption, scope-based coordination.
+- Search hints: `workflow`, `job`, `context`, `execution`, `scope`
+- Key files: docs/04-EXECUTION_MODEL.md, docs/06-WORKFLOWS.md, docs/07-EXAMPLE_WORKFLOWS.md
+
+### 5. **Org-Workspace-Cost Model**
+
+- Why: Hierarchical containment (Org > Workspace > Job > Context), cost attribution and visibility, cross-workspace learning promotion. Enterprise governance angle.
+- Search hints: `org OR workspace`, `cost`, `promotion`, `governance`
+- Key files: docs/03-ORG_WORKSPACE_MODEL.md, docs/01-ARCHITECTURE.md (sections 4-5)
+
+## Additional Notable Themes (Considered but Not Primary)
+
+- **Letta Integration**: docs/LETTA_INTEGRATION_PLAN.md shows concrete integration plans with MemGPT memory blocks
+- **Observability & Transparency**: Strong theme in amorphic docs, core principle
+- **Primitive Definitions**: 20 formal primitives in docs/02-PRIMITIVES.md
+
+## Tool Evaluation
+
+### What Worked Well
+
+- `mdcontext stats` gave instant overview of scope (23 docs, 179K tokens, 924 sections)
+- `mdcontext tree [file]` showing document outlines with token counts was extremely valuable for prioritization
+- `mdcontext tree [folder]` listing all files was quick way to understand structure
+- Boolean search operators (OR, AND) worked well when used
+- Keyword search results showed context (lines before/after) which helped understand relevance
+- Search results included section headers with token counts - useful for prioritization
+
+### What Was Frustrating
+
+- Keyword search requires exact terms - multi-word phrases like "human control authority" returned 0 results
+- Search limited to 10 results max (or at least only showed 10) - no pagination visible
+- No way to increase result limit in search output
+- `mdcontext index` commands ran in background unexpectedly, making it unclear when indexing completed
+- No embeddings by default - would need `--embed` for semantic search
+- docs.llm/ contains mostly duplicated content (aggregated files) - no way to detect this automatically
+
+### What Was Missing
+
+- Semantic search (would require `--embed` indexing)
+- Cross-file relationship detection (e.g., which docs reference which primitives)
+- Token budget for search results (like context command has)
+- Ability to search within specific folders only
+- Duplicate content detection
+- Section-level content preview (tree shows structure but not content snippets)
+
+### Confidence Level
+
+[X] High / Medium / Low
+
+**Justification**: Tree command with token counts and section headers gave excellent structural overview. Keyword search confirmed theme patterns across documents. Main uncertainty is whether I missed nuanced content that would only surface with semantic search.
+
+### Would Use Again? (1-5)
+
+**4** - Very useful for rapid mapping of large doc sets. The combination of `tree` for structure and `search` for theme confirmation worked well. Would be 5/5 with semantic search enabled.
+
+## Time & Efficiency
+
+- Commands run: 37
+- Compared to reading all files: **Much less** - 179K tokens would be impossible to read directly; mdcontext enabled mapping in ~10 minutes
+- Key efficiency: `tree [file]` with token counts let me prioritize which areas need deep investigation
+
+## Summary for Divers
+
+The documentation describes **HumanWork**, a framework for human-AI collaboration that explicitly rejects the "fully autonomous agent" paradigm. Key innovations:
+
+1. **Three-layer memory** enabling replay, time travel, branching
+2. **Control Plane** with preemptive human authority over all execution
+3. **Workspace isolation** for cost attribution and parallel exploration
+4. **Workflows as guidance** (not rigid automation)
+
+The docs.amorphic/ folder contains the philosophical "why" (failure analysis), while docs/ contains the formal "what" (primitives, architecture). The docs.llm/ folder appears to be aggregated versions for LLM consumption.
+
+Recommended diver priorities:
+
+1. Memory Architecture (most referenced, most complex)
+2. Human Control Model (core differentiator)
+3. Failure Analysis (explains design decisions)
+4. Execution Model (operational complexity)
+5. Org-Workspace Model (enterprise governance angle)