mdcontext 0.0.1 → 0.2.0

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

@@ -0,0 +1,228 @@
+# B-Synth: Strategy B Synthesis
+
+## Executive Summary
+
+The three Strategy B agents collectively identified a mature, self-aware specification that thoroughly documents what NOT to do (anti-patterns, invariants) but has significant gaps in terminology alignment, implementation guidance, and philosophical framing. The most critical finding is the HumanWork-Evolution.md document which already synthesizes feedback into a phased improvement plan - agents B1-B3 largely validated and expanded on this existing gap analysis.
+
+## Cross-Agent Patterns
+
+**Theme 1: Semantic Search Underperformance**
+All three agents found semantic search unreliable for multi-word conceptual queries. All fell back to keyword search frequently. This is the strongest cross-agent signal about the mdcontext tool.
+
+**Theme 2: HumanWork-Evolution.md as Critical Source**
+Both B1 and B2 independently discovered this document as the authoritative source for gaps and critiques, validating its importance.
+
+**Theme 3: Human-First Philosophy with Acknowledged Tensions**
+All agents found the docs emphasize human control, but B2 identified a philosophical gap: the spec frames human control as end-state rather than transition phase toward "intelligence crystallization."
+
+**Theme 4: Section-Level Context Extraction Praised**
+All three agents highlighted the `--section` flag as highly effective for targeted retrieval.
+
+**Theme 5: Checkpoint/Intervention Architecture**
+B1 found checkpoints in anti-patterns, B3 found them in workflow design - the spec heavily emphasizes checkpoints as the key governance mechanism.
+
+## Consolidated Findings
+
+### Architecture Criticisms (from B1)
+
+**External Criticisms (of traditional approaches):**
+
+- Brittleness of pure automation (combinatorial explosion of rules)
+- Coordination Trap (multiplies human translation work)
+- Innovation Strangulation (automation-incompatible approaches avoided)
+- Judgment Gap (80% flawless, 20% chaos)
+- Context Collapse (context as configuration, not conversation)
+- Observability Problem (black-box agents kill trust)
+
+**Self-Imposed Constraints (internal guardrails):**
+
+- 8 Architectural Invariants (no hidden state, no irreversible execution, etc.)
+- 7 Memory Model Anti-Patterns
+- 8 Workflow Anti-Patterns
+
+**Open Questions (acknowledged gaps):**
+
+- Alignment with human values at scale
+- Limits of organizational intelligence
+- Preventing organizational capture (self-perpetuation)
+
+### Gaps Identified (from B2)
+
+**Terminology Gaps:**
+
+- Agent -> Actor (unified human/machine)
+- Artifact -> Deliverable (business language)
+- Event Memory -> The Ledger (IP capture emphasis)
+
+**Missing Primitives:**
+
+- Correction Event (captures human intelligence on modifications)
+- Authority Gradient (replaces binary control)
+- Pattern Crystallization (organizational learning mechanism)
+
+**Architectural Gaps:**
+
+- No geometric/semantic embeddings in Semantic Memory
+- Cost model doesn't unify human hours and AI tokens
+- Privacy model is "policy overlay" only
+- No formal API specification
+
+**Philosophical Gap:**
+
+- Spec positions "human control" as goal
+- Feedback suggests reframing as "intelligence extraction"
+- Human corrections should become portable organizational intelligence
+
+### Workflow Improvements (from B3)
+
+**Core Philosophy:**
+
+- Workflows as "guidance without control"
+- Six concepts: Entry Signals, Roles, Phases, Activities, Checkpoints, Exit Conditions
+- Checkpoints as primary governance mechanism
+
+**Authority Gradient (4 modes):**
+
+1. Instructional: Step-by-step human instructions
+2. Consultative: Human defines goal, agent proposes
+3. Supervisory: Agents execute, humans monitor
+4. Exploratory: Alternating generation/testing
+
+**Intervention Points:**
+
+- Redirect, Override, Inject, Escalate
+
+**Key Patterns:**
+
+- Time Travel and Branching
+- Parallel Exploration
+- Immutable Workflow Versioning
+
+**Organizational Transformation:**
+
+- Choreographic Maturity Model (4 levels)
+- Cultural shifts toward experimental mindsets
+
+## Proposed Spec Changes (Prioritized)
+
+### High Priority
+
+- [ ] Rename Artifact -> Deliverable throughout (B2)
+- [ ] Add Correction Event primitive (B2) - captures IP when humans modify outputs
+- [ ] Add Authority Gradient to Execution Model (B2, B3) - instructional/consultative/supervisory/exploratory
+- [ ] Expand Judgment Gap (80/20 problem) handling beyond "humans intervene" (B1)
+- [ ] Add "Known Limitations and Trade-offs" section (B1) - what HumanWork sacrifices
+- [ ] Unify cost model for Human + Machine Actors (B2)
+
+### Medium Priority
+
+- [ ] Add Actor primitive with type: Human | Machine (B2)
+- [ ] Add Pattern Crystallization to Memory Model (B2)
+- [ ] Rename Event Memory -> The Ledger (B2)
+- [ ] Add cognitive telemetry to Checkpoints (B2) - deliberation_duration, confidence_signal, modification_depth
+- [ ] Document concrete answers to Open Questions or mark as research priorities (B1)
+- [ ] Create decision framework: when DAG-style execution IS appropriate (B1)
+- [ ] Add explicit checkpoint requirements for high-stakes workflows (B3)
+- [ ] Define minimum intervention points per workflow phase (B3)
+
+### Low Priority
+
+- [ ] Enhance Semantic Memory with geometric embeddings (B2)
+- [ ] Add detection guidance for when Status Memory becomes authoritative (B1)
+- [ ] Reframe "human control" as transition phase, not end state (B2)
+- [ ] Adopt choreography language over orchestration (B2)
+- [ ] Develop privacy model beyond "policy overlay" (B2)
+- [ ] Create formal API specification (B2)
+- [ ] Establish choreographic maturity assessment framework (B3)
+- [ ] Create signals taxonomy (activity, outcome, attention, health) (B3)
+
+## Tool Evaluation Synthesis
+
+All three agents used the mdcontext tool extensively (38, 35, and 41 commands respectively = 114 total commands). Their assessments were remarkably consistent.
+
+### Common Praise
+
+- **Section-level context extraction** (`--section`) was universally praised as highly effective
+- **Keyword search** was reliable and essential fallback
+- **Token budget control** (`-t`) helped manage context size
+- **Tree command** gave quick corpus overview
+- **Fast embedding indexing** (~$0.003 cost)
+- **Stats command** useful for understanding corpus size
+
+### Common Frustrations
+
+- **Semantic search returned 0 results** for multi-word conceptual queries (all 3 agents)
+- **Token truncation** without clear indication of what was excluded
+- **No way to chain or aggregate searches** - had to run many separate commands
+- **Multi-word keyword searches failed** (e.g., "issue challenge gap" = 0 results)
+- **False positives** in keyword search
+- **No semantic search threshold adjustment**
+
+### Suggested Improvements
+
+- Add fuzzy/stemmed search (fail vs failure)
+- Add "search within results" / progressive refinement
+- Add context around keyword matches without re-running
+- Add combined semantic+keyword hybrid mode
+- Add cross-document synthesis
+- Add batch context extraction for multiple sections/files
+- Add "related sections" feature
+- Add Boolean operators in keyword mode
+- Add export/save functionality
+- Add "what's undefined" query (terms used but not defined)
+
+### Quantitative Summary
+
+| Agent | Commands | Confidence | Rating |
+| ----- | -------- | ---------- | ------ |
+| B1    | 38       | Medium     | 4/5    |
+| B2    | 35       | High       | 4/5    |
+| B3    | 41       | High       | 4/5    |
+
+All agents rated the tool 4/5 and found it significantly faster than reading all files manually.
+
+## Methodology Assessment
+
+How well did Strategy B (divide by question) work?
+
+### Strengths
+
+- **Clear scope boundaries**: Each agent had a focused research question, avoiding overlap
+- **Efficient parallelization**: Three agents could work simultaneously on different questions
+- **Natural synthesis path**: Findings from each question type combined naturally into a coherent picture
+- **Reduced redundancy**: Agents didn't repeat the same searches (unlike Strategy A file-based division)
+- **Comprehensive coverage**: Architecture + Gaps + Workflows covers the spec from multiple angles
+- **Discovery of key document**: Multiple agents independently found HumanWork-Evolution.md, validating its importance
+
+### Weaknesses
+
+- **Question boundaries can be fuzzy**: "Architecture criticisms" vs "gaps" had some overlap (e.g., observability problem)
+- **Dependent insights split**: Authority Gradient appeared in both B2 (as gap) and B3 (as workflow improvement)
+- **No shared discovery context**: B2 found HumanWork-Evolution.md which would have helped B1's research
+- **Variable scope difficulty**: Some questions (workflows) were more expansive than others (architecture criticisms)
+
+### Would Recommend For
+
+- **Documentation analysis** where questions naturally partition the content
+- **Due diligence reviews** (legal, technical, financial angles)
+- **Research synthesis** where multiple perspectives on same corpus needed
+- **Gap analysis** where "what exists" vs "what's missing" are distinct questions
+- **Any task where questions are more natural than file divisions**
+
+### Not Recommended For
+
+- **Code review** (files matter more than questions)
+- **Tasks where answers span all questions** (high synthesis overhead)
+- **Simple/small corpora** (parallelization overhead not worth it)
+
+## Appendix: Agent Command Efficiency
+
+| Metric              | B1  | B2  | B3  | Total |
+| ------------------- | --- | --- | --- | ----- |
+| Commands run        | 38  | 35  | 41  | 114   |
+| Semantic searches   | 8   | 4   | 12  | 24    |
+| Keyword searches    | 22  | 23  | 0   | 45    |
+| Context extractions | 13  | 9   | 19  | 41    |
+| Tree/Stats/Index    | 3   | 3   | 3   | 9     |
+
+**Key observation**: B3 (workflows) used semantic search exclusively and found it more effective for their domain. B1 and B2 heavily relied on keyword search after semantic search failed. This suggests semantic search may work better for concrete concepts (workflows, collaboration) than abstract critiques (gaps, criticisms).

package/research/dogfood/strategy-b/b1-architecture.md

@@ -0,0 +1,207 @@
+# Report: B1 - Architecture Critic Hunter
+
+## Mission
+
+Find architecture and design criticisms across all documentation
+
+## Research Question
+
+What architecture and design criticisms exist?
+
+## Command Log
+
+| #   | Command                                                                                                       | Purpose                         | Result                                | Useful? |
+| --- | ------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------- | ------- |
+| 1   | `mdcontext --help`                                                                                            | Learn tool                      | Got full usage guide                  | Yes     |
+| 2   | `mdcontext index --embed --force`                                                                             | Index all files with embeddings | 23 docs, 922 sections, 904 embeddings | Yes     |
+| 3   | `mdcontext search "architecture criticism problems design flaws limitations"`                                 | Semantic search for criticisms  | 1 result (ARCHITECTURAL_FOUNDATIONS)  | Partial |
+| 4   | `mdcontext search "design trade-offs weaknesses concerns issues"`                                             | Semantic search                 | 0 results                             | No      |
+| 5   | `mdcontext search "failure problems complexity challenges"`                                                   | Semantic search                 | 0 results                             | No      |
+| 6   | `mdcontext search "failure" --mode keyword`                                                                   | Keyword search                  | 10 results                            | Yes     |
+| 7   | `mdcontext context docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md -t 3000`                                | Get full failure analysis       | Full document                         | Yes     |
+| 8   | `mdcontext search "limitations" --mode keyword`                                                               | Keyword search                  | 1 result                              | Yes     |
+| 9   | `mdcontext search "problem" --mode keyword`                                                                   | Keyword search                  | 10 results                            | Yes     |
+| 10  | `mdcontext search "risk" --mode keyword`                                                                      | Keyword search                  | 10 results                            | Yes     |
+| 11  | `mdcontext search "anti-pattern" --mode keyword`                                                              | Keyword search                  | 4 results                             | Yes     |
+| 12  | `mdcontext context docs/05-MEMORY_MODEL.md --section "Anti-Patterns"`                                         | Get memory anti-patterns        | 7 forbidden patterns                  | Yes     |
+| 13  | `mdcontext context docs/06-WORKFLOWS.md --section "Anti-Patterns"`                                            | Get workflow anti-patterns      | 8 forbidden patterns                  | Yes     |
+| 14  | `mdcontext search "concern" --mode keyword`                                                                   | Keyword search                  | 10 results                            | Yes     |
+| 15  | `mdcontext search "brittle" --mode keyword`                                                                   | Keyword search                  | 10 results                            | Yes     |
+| 16  | `mdcontext search "complexity" --mode keyword`                                                                | Keyword search                  | 9 results                             | Yes     |
+| 17  | `mdcontext search "overhead" --mode keyword`                                                                  | Keyword search                  | 7 results                             | Yes     |
+| 18  | `mdcontext search "design patterns architecture decision"`                                                    | Semantic search                 | 10 results                            | Yes     |
+| 19  | `mdcontext context docs.amorphic/03-ARCHITECTURAL_FOUNDATIONS.md -t 2000`                                     | Get architectural foundations   | Full document                         | Yes     |
+| 20  | `mdcontext context docs.amorphic/05-TECHNICAL_IMPLEMENTATION_PATTERNS.md -t 2500`                             | Get implementation patterns     | Full document                         | Yes     |
+| 21  | `mdcontext search "gap" --mode keyword`                                                                       | Keyword search                  | 8 results                             | Yes     |
+| 22  | `mdcontext context docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md --section "Judgment Gap"`               | Get judgment gap section        | Detailed section                      | Yes     |
+| 23  | `mdcontext search "forbidden" --mode keyword`                                                                 | Keyword search                  | 5 results                             | Yes     |
+| 24  | `mdcontext search "corrupt" --mode keyword`                                                                   | Keyword search                  | 5 results                             | Yes     |
+| 25  | `mdcontext tree docs/01-ARCHITECTURE.md`                                                                      | Get document outline            | 47 sections                           | Yes     |
+| 26  | `mdcontext context docs/01-ARCHITECTURE.md --section "Why This Architecture Works"`                           | Get rationale                   | Brief justification                   | Yes     |
+| 27  | `mdcontext context docs/01-ARCHITECTURE.md --section "Architectural Invariants"`                              | Get invariants                  | 8 invariants                          | Yes     |
+| 28  | `mdcontext search "fail" --mode keyword`                                                                      | Keyword search                  | 10 results                            | Yes     |
+| 29  | `mdcontext context docs/00-README.md --section "What Problem"`                                                | Get problem statement           | Core problem                          | Yes     |
+| 30  | `mdcontext search "cost" --mode keyword`                                                                      | Keyword search                  | 10 results                            | Yes     |
+| 31  | `mdcontext context docs.llm/feedback.md -t 3000`                                                              | Get feedback document           | Chat feedback analysis                | Yes     |
+| 32  | `mdcontext search "traditional" --mode keyword`                                                               | Keyword search                  | 10 results                            | Yes     |
+| 33  | `mdcontext tree docs.llm/amorphic.md`                                                                         | Get amorphic outline            | Full outline                          | Yes     |
+| 34  | `mdcontext context docs.llm/amorphic.md --section "Open Questions"`                                           | Get open questions              | 3 open questions                      | Yes     |
+| 35  | `mdcontext context docs.llm/amorphic.md --section "Paradox of Automation"`                                    | Get paradox section             | Detailed section                      | Yes     |
+| 36  | `mdcontext search "wrong" --mode keyword`                                                                     | Keyword search                  | 6 results                             | Yes     |
+| 37  | `mdcontext context docs.amorphic/04-THE_HUMAN-AGENT_COLLABORATION_MODEL.md --section "Observability Problem"` | Get observability problem       | Key issue identified                  | Yes     |
+| 38  | `mdcontext search "scale" --mode keyword`                                                                     | Keyword search                  | 10 results                            | Yes     |
+
+## Findings
+
+### Key Discoveries
+
+#### 1. Criticisms of Traditional/Pure Automation (Major Theme)
+
+The documentation extensively critiques traditional automation approaches:
+
+- **Brittleness**: "The system becomes brittle not because any individual rule is wrong, but because the combinatorial explosion of rules creates a rigid lattice that cannot bend without breaking."
+- **Coordination Trap**: Pure automation "multiplies coordination requirements by forcing human work into machine-readable formats that require constant translation and synchronization."
+- **Innovation Strangulation**: "Teams avoid innovative approaches not because they're technically inferior, but because they're automation-incompatible."
+- **Human Bottleneck Paradox**: Attempting to eliminate humans creates new bottlenecks in system configuration and exception handling.
+- **Context Collapse**: Traditional systems treat "context as configuration rather than conversation."
+- **Judgment Gap**: "Systems that handle 80% of cases flawlessly but create chaos in the remaining 20%."
+
+#### 2. Agent System Criticisms (Self-Aware)
+
+The documentation acknowledges problems with current agent systems:
+
+> "Most agent systems fail at real work because they optimize for demos, single-shot tasks, and autonomous execution. They become opaque, brittle, hard to interrupt, impossible to rewind, and unsafe to scale."
+> Source: docs/00-README.md
+
+#### 3. Observability Problem
+
+> "Most agent systems are black boxes. You send a request, wait, and get a result - with no visibility into what happened in between. When something goes wrong, you're left debugging phantom processes and mysterious failures. This opacity kills trust."
+> Source: docs.amorphic/04-THE_HUMAN-AGENT_COLLABORATION_MODEL.md
+
+#### 4. Anti-Patterns Explicitly Forbidden
+
+**Memory Model Anti-Patterns:**
+
+- Storing mutable state in Event Memory
+- Treating Status Memory as authoritative
+- Letting Semantic Memory drive execution
+- Hiding Events from humans
+- Creating circular dependencies between layers
+- Bypassing Event Memory for "performance"
+- Hard-deleting critical audit events
+
+**Workflow Anti-Patterns:**
+
+- Workflows that execute directly
+- Workflows that mutate artifacts
+- Workflows that allocate cost
+- Workflows that own agents
+- Hidden workflow state
+- Workflows that become Turing-complete
+- Mandatory workflows (at system level)
+- Workflows that bypass Control Plane
+
+#### 5. Architectural Invariants (Design Constraints)
+
+The system explicitly maintains these constraints to avoid known issues:
+
+- No hidden mutable state
+- No irreversible execution
+- No unobservable progress
+- No agent-owned memory
+- No loss of human authority
+- No concurrent mutation of the same scope
+- No execution without a Workspace
+- No automatic flow from Org to Workspace
+
+#### 6. Open Questions (Acknowledged Gaps)
+
+> "How do we ensure HumanWork organizations remain aligned with human values as they become more autonomous?"
+> "What are the limits of organizational intelligence? Are there problems that fundamentally require individual rather than collective cognition?"
+> "How do we prevent organizational capture - scenarios where HumanWork systems optimize for their own perpetuation rather than their intended purposes?"
+> Source: docs.llm/amorphic.md
+
+#### 7. Substrate Problem
+
+> "Implementation details leak into the conceptual model, making the workflow harder to reason about and modify."
+> Source: docs.amorphic/03-ARCHITECTURAL_FOUNDATIONS.md
+
+### Relevant Quotes/Sections Found
+
+> "Pure automation assumes complete knowledge of the problem space. It requires that all possible states, transitions, and edge cases be enumerable at design time. This works beautifully for manufacturing widgets or processing financial transactions - domains where the rules are well-understood and the exceptions are genuinely exceptional. But knowledge work exists in a different regime entirely."
+> Source: docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md, The Brittleness of Complete Systems
+
+> "The paradox emerges when pure automation, in attempting to eliminate human bottlenecks, creates new bottlenecks in the form of system configuration, exception handling, and cross-system integration."
+> Source: docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md, The Human Bottleneck Paradox
+
+> "Traditional workflow systems model execution as directed acyclic graphs (DAGs) - nodes representing tasks, edges representing dependencies. This works well for batch processing and pipeline scenarios where the structure is known in advance. But it breaks down when workflows need to adapt their structure based on runtime conditions or accumulated learning."
+> Source: docs.amorphic/03-ARCHITECTURAL_FOUNDATIONS.md, Component Relationships
+
+> "If Status Memory cannot be rebuilt, it has become a source of truth and the system is corrupted."
+> Source: docs/05-MEMORY_MODEL.md, The Hard Rule
+
+### Answer to Research Question
+
+**What architecture and design criticisms exist?**
+
+The documentation contains extensive, self-aware architectural criticism organized into three categories:
+
+1. **Criticisms of Traditional Approaches (external):** The docs thoroughly critique pure automation, traditional workflow systems (DAGs), black-box agent systems, and context-as-configuration approaches. These criticisms justify the HumanWork design decisions.
+
+2. **Self-Imposed Constraints (internal guardrails):** The architecture explicitly forbids specific anti-patterns for both memory and workflows. These represent lessons learned about what NOT to do - treating them as "corrupted" states if they appear.
+
+3. **Acknowledged Open Questions (honest gaps):** The documentation admits uncertainty about alignment with human values at scale, limits of organizational intelligence, and preventing organizational capture.
+
+The architectural philosophy is defensive - explicitly naming what can go wrong and building constraints to prevent it. The invariants and anti-patterns serve as architectural "unit tests" against known failure modes.
+
+## Proposed Spec Changes
+
+- [ ] Add section on "Known Limitations and Trade-offs" to acknowledge what HumanWork architecture sacrifices (e.g., raw execution speed for observability)
+- [ ] Expand on how the Judgment Gap (80/20 problem) is specifically addressed beyond "humans intervene"
+- [ ] Document concrete answers to the Open Questions or mark them as research priorities
+- [ ] Add guidance on detecting when Status Memory has "become authoritative" before corruption
+- [ ] Create decision framework for when DAG-style execution IS appropriate vs. adaptive execution
+
+## Tool Evaluation
+
+### What Worked Well
+
+- Keyword search (`--mode keyword`) was highly effective for finding specific terms like "failure", "brittle", "anti-pattern"
+- Section-targeted context (`--section "X"`) efficiently extracted exactly what I needed
+- The `tree` command helped understand document structure before diving in
+- Embedding indexing was fast and one-time cost
+- Token budget control (`-t`) helped manage context size
+
+### What Was Frustrating
+
+- Semantic search often returned 0 results for multi-word queries that should have matched
+- Semantic search for "design trade-offs weaknesses concerns issues" returned nothing
+- Semantic search for "failure problems complexity challenges" returned nothing
+- Had to fall back to keyword search frequently after semantic failed
+- Multi-word keyword searches didn't work (e.g., "issue challenge gap" = 0 results)
+- Boolean operators in keyword mode unclear if supported
+
+### What Was Missing
+
+- No fuzzy/stemmed search (had to search "fail" vs "failure" separately)
+- No "search within results" or progressive refinement
+- No way to get context around keyword matches without re-running with `context`
+- Semantic search threshold/sensitivity adjustment not available
+- No combined semantic+keyword hybrid mode
+- Difficult to search for concepts without exact terms
+
+### Confidence Level
+
+[X] Medium
+
+The keyword search found the explicit criticisms comprehensively. However, I may have missed implicit criticisms or design concerns that don't use obvious negative terminology. Semantic search underperformed expectations.
+
+### Would Use Again? (1-5)
+
+**4** - Good for structured documentation analysis. Keyword search is reliable. Would use again but with clearer expectations that semantic search needs more work. The section-level context extraction is genuinely useful for targeted retrieval.
+
+## Time & Efficiency
+
+- Commands run: **38**
+- Compared to reading all files: **Much less** - Would have taken 30+ minutes to read all docs manually. Tool-based search took approximately 15 minutes to find all relevant criticisms.
+- Token efficiency: Reduced ~150k tokens of docs to targeted extracts totaling ~15k tokens of relevant content