mdcontext 0.0.1 → 0.2.0

package/research/dogfood/strategy-b/b2-gaps.md

@@ -0,0 +1,258 @@
+# Report: B2 - Gap Finder
+
+## Mission
+
+Find gaps and missing elements in the specification
+
+## Research Question
+
+What's missing from the spec? What gaps were identified?
+
+## Command Log
+
+| #   | Command                                                                                   | Purpose                 | Result                                              | Useful?   |
+| --- | ----------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------- | --------- |
+| 1   | `mdcontext --help`                                                                        | Learn tool              | Showed all commands and examples                    | Yes       |
+| 2   | `mdcontext index`                                                                         | Index markdown files    | 23 docs, 922 sections indexed                       | Yes       |
+| 3   | `mdcontext tree`                                                                          | List all files          | Showed 23 files in docs/, docs.amorphic/, docs.llm/ | Yes       |
+| 4   | `mdcontext search "gaps missing omissions"`                                               | Find gap mentions       | 0 results (semantic)                                | No        |
+| 5   | `mdcontext search "gaps missing omissions" --mode keyword`                                | Find gap mentions       | 0 results                                           | No        |
+| 6   | `mdcontext search "missing" --mode keyword`                                               | Find missing items      | 10 results - found "missing primitive" narrative    | Yes       |
+| 7   | `mdcontext search "gap" --mode keyword`                                                   | Find gap mentions       | 8 results - found "Judgment Gap", "AI fatigue gap"  | Yes       |
+| 8   | `mdcontext search "TODO" --mode keyword`                                                  | Find TODOs              | 1 result (Letta integration)                        | Minimal   |
+| 9   | `mdcontext search "not yet" --mode keyword`                                               | Find incomplete         | 10 results (mostly SPEC.md headers)                 | No        |
+| 10  | `mdcontext search "incomplete" --mode keyword`                                            | Find incomplete         | 2 results                                           | Minimal   |
+| 11  | `mdcontext search "needs" --mode keyword`                                                 | Find needs              | 10 results - coordination, clarification needs      | Yes       |
+| 12  | `mdcontext search "question" --mode keyword`                                              | Find questions          | 10 results                                          | Minimal   |
+| 13  | `mdcontext search "problem" --mode keyword`                                               | Find problems           | 10 results - handoff problem, problem space         | Yes       |
+| 14  | `mdcontext search "issue" --mode keyword`                                                 | Find issues             | 10 results - mostly examples                        | Minimal   |
+| 15  | `mdcontext search "limitation" --mode keyword`                                            | Find limitations        | 3 results - judgment limitation                     | Yes       |
+| 16  | `mdcontext search "concern" --mode keyword`                                               | Find concerns           | 10 results - architecture concerns                  | Minimal   |
+| 17  | `mdcontext search "feedback" --mode keyword`                                              | Find feedback           | 10 results - key evolution doc                      | Yes       |
+| 18  | `mdcontext context docs.llm/feedback.md -t 3000`                                          | Get feedback context    | Truncated summary                                   | Partial   |
+| 19  | `mdcontext search "recommend" --mode keyword`                                             | Find recommendations    | 10 results - recommendation primitive               | Yes       |
+| 20  | `mdcontext search "suggested" --mode keyword`                                             | Find suggestions        | 6 results                                           | Minimal   |
+| 21  | `mdcontext search "should" --mode keyword`                                                | Find should-statements  | 10 results - evolution suggestions                  | Yes       |
+| 22  | `mdcontext context docs/HumanWork-Evolution.md --full`                                    | Get evolution doc       | Full synthesis of all gaps                          | Critical  |
+| 23  | `mdcontext search "security" --mode keyword`                                              | Find security gaps      | 10 results                                          | Minimal   |
+| 24  | `mdcontext search "failure" --mode keyword`                                               | Find failure handling   | 10 results - failure recovery                       | Minimal   |
+| 25  | `mdcontext search "privacy" --mode keyword`                                               | Find privacy gaps       | 2 results - minimal coverage                        | Yes (gap) |
+| 26  | `mdcontext context docs/03-ORG_WORKSPACE_MODEL.md --section "11. Privacy and Visibility"` | Get privacy details     | Very brief - "policy overlay"                       | Yes (gap) |
+| 27  | `mdcontext search "cost" --mode keyword`                                                  | Find cost model         | 10 results - basic cost tracking                    | Yes       |
+| 28  | `mdcontext search "testing" --mode keyword`                                               | Find testing mentions   | 10 results - mostly examples                        | Minimal   |
+| 29  | `mdcontext search "API" --mode keyword`                                                   | Find API spec           | 10 results - no formal API spec                     | Yes (gap) |
+| 30  | `mdcontext context docs/05-MEMORY_MODEL.md --section "15. Implementation Guidance"`       | Get impl guidance       | Technology suggestions only                         | Yes       |
+| 31  | `mdcontext search "evolution" --mode keyword`                                             | Find evolution plans    | 10 results - evolution document                     | Yes       |
+| 32  | `mdcontext context docs/LETTA_INTEGRATION_PLAN.md -t 3000`                                | Get Letta plan          | Integration phases                                  | Yes       |
+| 33  | `mdcontext search "rename" --mode keyword`                                                | Find rename suggestions | 1 result - terminology changes                      | Yes       |
+| 34  | `mdcontext search "replaces" --mode keyword`                                              | Find replacements       | 2 results - Actor/Deliverable                       | Yes       |
+| 35  | `mdcontext stats`                                                                         | Index statistics        | 23 docs, 922 sections, 178K tokens                  | Yes       |
+
+## Findings
+
+### Key Discoveries
+
+The most critical finding is the **HumanWork-Evolution.md** document which synthesizes all feedback into a comprehensive gap analysis. This document reveals 7 major categories of gaps:
+
+#### 1. Terminology/Primitive Gaps
+
+The spec uses outdated or suboptimal terminology:
+
+- "Agent" should become "Actor" (unified human/machine)
+- "Artifact" should become "Deliverable" (business language)
+- "Event Memory" should become "The Ledger" (emphasizes IP capture)
+
+#### 2. Missing Primitives
+
+Several critical primitives are not defined in the spec:
+
+- **Correction Event** - captures human intelligence when modifying outputs
+- **Authority Gradient** - replaces binary control with spectrum
+- **Pattern Crystallization** - organizational learning mechanism
+
+#### 3. Philosophical Framing Gap
+
+The spec frames human control as the end state, but feedback suggests:
+
+- Human control is a **transition phase**, not end state
+- System should extract and crystallize human intelligence
+- Progressive transfer of decision-making to Actors
+
+#### 4. Memory Model Gaps
+
+- No geometric/semantic embeddings in Semantic Memory
+- No Pattern Crystallization operation
+- Missing cognitive telemetry at checkpoints
+
+#### 5. Cost Model Gaps
+
+- Human hours and AI tokens not unified
+- Actor cost attribution not formalized
+- No cost model for Actor.type (Human vs Machine)
+
+#### 6. Privacy/Security Gap
+
+The privacy section is minimal - described as a "policy overlay, not a core feature"
+
+#### 7. API/Implementation Gap
+
+- No formal API specification
+- Implementation guidance is technology suggestions only
+- No concrete schemas or endpoints defined
+
+### Relevant Quotes/Sections Found
+
+> "HumanWork is the missing runtime for Labor - alongside Compute, Storage, and Network."
+> Source: docs/HumanWork-Evolution.md
+
+> "The ultimate goal is human replacement through intelligence crystallization"
+> Source: docs/HumanWork-Evolution.md (citing amorphic feedback)
+
+> "Artifacts suggests archaeological remnants. Deliverables emphasizes work products - measurable, valuable outputs"
+> Source: docs/HumanWork-Evolution.md
+
+> "The System treats Human Labor and AI Agent Labor as a unified data stream"
+> Source: docs/HumanWork-Evolution.md (Amorphic Principle)
+
+> "Checkpoints aren't just governance - they're cognitive capture points"
+> Source: docs/HumanWork-Evolution.md
+
+> "Pure automation optimizes for the known, but work increasingly happens in the spaces between the known - in edge cases, exceptions, and emergent scenarios"
+> Source: docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md, "The Judgment Gap"
+
+> "The timing is critical. Organizations worldwide are struggling with 'AI fatigue' - the gap between AI's promise and its practical integration"
+> Source: docs.amorphic/01-EXECUTIVE_SUMMARY.md, "Market Disruption Potential"
+
+> "This is a **policy overlay**, not a core feature."
+> Source: docs/03-ORG_WORKSPACE_MODEL.md, "11. Privacy and Visibility"
+
+### Answer to Research Question
+
+**What's missing from the spec? What gaps were identified?**
+
+The spec has significant gaps in three areas:
+
+**1. Primitive & Terminology Gaps:**
+
+- Need new primitives: Actor, Deliverable, The Ledger, Correction Event, Authority Gradient, Pattern Crystallization
+- Current terminology (Agent, Artifact, Event Memory) is inadequate
+
+**2. Architectural Gaps:**
+
+- Unified cost model for human/machine labor missing
+- Geometric/semantic embeddings not in Memory Model
+- No formal Pattern Crystallization mechanism
+- Cognitive telemetry at checkpoints undefined
+- Authority Gradient (spectrum of autonomy) not implemented
+
+**3. Implementation/Documentation Gaps:**
+
+- No formal API specification
+- Privacy model is underdeveloped ("policy overlay")
+- Error handling patterns not specified
+- No concrete schemas or data models
+- Missing hw CLI terminal experience positioning
+
+**4. Philosophical Gap:**
+The spec positions "human control" as the goal, but feedback suggests reframing as "intelligence extraction" - where human corrections become portable organizational intelligence that progressively makes Actors more capable.
+
+## Proposed Spec Changes
+
+Based on the feedback synthesis in HumanWork-Evolution.md:
+
+### Immediate (Terminology)
+
+- [ ] Add hw terminal metaphor to README
+- [ ] Rename Artifact -> Deliverable throughout
+- [ ] Rename Event Memory -> The Ledger
+- [ ] Add Actor primitive (replaces Agent with type: Human | Machine)
+- [ ] Add Correction Event primitive
+
+### Near-Term (Architecture)
+
+- [ ] Add Authority Gradient to Execution Model (instructional/consultative/supervisory/exploratory)
+- [ ] Add Pattern Crystallization to Memory Model
+- [ ] Enhance Semantic Memory with geometric embeddings
+- [ ] Add cognitive telemetry to Checkpoints (deliberation_duration, confidence_signal, modification_depth)
+- [ ] Unify cost model for Human + Machine Actors
+
+### Strategic (Philosophy)
+
+- [ ] Reframe "human control" as transition phase, not end state
+- [ ] Position system as intelligence extraction, not just coordination
+- [ ] Emphasize The Ledger as primary asset (IP capture)
+- [ ] Adopt choreography language over orchestration
+- [ ] Develop privacy model beyond "policy overlay"
+- [ ] Create formal API specification
+
+## Tool Evaluation
+
+### What Worked Well
+
+- **Keyword search** was essential - semantic search returned 0 results for "gaps missing omissions"
+- **`mdcontext context --full`** for single large documents (HumanWork-Evolution.md) was extremely valuable
+- **`mdcontext tree`** gave quick overview of document structure
+- **Section-specific context** (`--section`) provided targeted extraction
+- **Stats command** helped understand corpus size (178K tokens across 23 docs)
+- Searching for key terms like "missing", "gap", "limitation", "recommendation" found relevant content
+
+### What Was Frustrating
+
+- **Semantic search yielded no results** for my primary query - had to fall back to keyword mode
+- **Token truncation** meant I couldn't see full context of feedback.md (only 16% shown at 3000 tokens)
+- **False positives in keyword search** - "not yet" returned SPEC.md headers, not actual incomplete items
+- **No way to chain searches** - had to run many separate commands
+- **Context command limits** - wanted to see multiple related sections but had to make separate calls
+- Some search results returned 10 matches but didn't show the most relevant ones first
+
+### What Was Missing
+
+- **Cross-document synthesis** - tool doesn't connect related content across files
+- **Diff/comparison view** - would help see gaps between spec versions
+- **"What's undefined" query** - no way to find terms used but not defined
+- **Relationship/dependency view** - what primitives depend on what
+- **Semantic search tuning** - couldn't adjust semantic similarity threshold
+- **Export/aggregation** - no way to collect all relevant sections into one view
+
+### Confidence Level
+
+[X] High / Medium / Low
+
+The HumanWork-Evolution.md document is a comprehensive synthesis that explicitly answers my research question. The gaps are clearly articulated with specific recommendations. My high confidence comes from:
+
+1. Finding the authoritative evolution document
+2. Corroborating gaps through multiple keyword searches
+3. Direct quotes supporting each gap identified
+
+### Would Use Again? (1-5)
+
+**4** - Very useful for targeted research. The keyword search mode was reliable once I learned semantic search wouldn't work for my query type. The context extraction with section targeting saved significant time. Lost one point because semantic search didn't work as expected and I had to learn workarounds.
+
+## Time & Efficiency
+
+- Commands run: **35**
+- Compared to reading all files: **Much less** - The tool helped me navigate 178K tokens across 23 documents efficiently. Finding HumanWork-Evolution.md alone (7500 tokens of synthesized gaps) would have taken much longer by reading files directly. The keyword searches let me quickly identify which documents contained gap-related content without reading everything.
+
+## Appendix: Critical Gaps from HumanWork-Evolution.md
+
+The most authoritative source of gaps is the evolution document, which proposes three phases:
+
+**Phase 1: Terminology Alignment**
+
+- Agent -> Actor (with type: Human | Machine)
+- Artifact -> Deliverable
+- Event Memory -> The Ledger
+- Add Correction Event, Authority Gradient, Pattern Crystallization
+
+**Phase 2: Architectural Enhancements**
+
+- Semantic Memory uses geometric embeddings
+- Add Pattern Crystallization as memory operation
+- Execution Contexts bind to Actors (not just agents)
+- Checkpoints capture cognitive telemetry
+
+**Phase 3: Philosophical Reframing**
+
+- "Human control" becomes transition phase
+- Position as intelligence extraction
+- Choreography language over orchestration

package/research/dogfood/strategy-b/b3-workflows.md

@@ -0,0 +1,250 @@
+# Report: B3 - Workflow Analyst
+
+## Mission
+
+Find workflow and process improvement suggestions
+
+## Research Question
+
+What workflow and process improvements are suggested?
+
+## Command Log
+
+| #   | Command                                                                                                        | Purpose                        | Result                                       | Useful?  |
+| --- | -------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------- | -------- |
+| 1   | mdcontext --help                                                                                               | Learn tool capabilities        | Showed commands, workflows, options          | Yes      |
+| 2   | mdcontext tree                                                                                                 | List all markdown files        | Found 23 files across 3 folders              | Yes      |
+| 3   | mdcontext index --force                                                                                        | Re-index all files             | Indexed 922 sections, 904 vectors            | Yes      |
+| 4   | mdcontext search "workflow improvement"                                                                        | Find workflow improvements     | 2 results (versioning, team review)          | Moderate |
+| 5   | mdcontext search "process automation"                                                                          | Find automation content        | 10 results (failure of automation, paradox)  | Yes      |
+| 6   | mdcontext search "human agent collaboration"                                                                   | Find collaboration patterns    | 10 results (71.6% top match)                 | Yes      |
+| 7   | mdcontext search "execution model"                                                                             | Find execution concepts        | 10 results                                   | Yes      |
+| 8   | mdcontext search "best practices"                                                                              | Find best practices            | 4 results                                    | Moderate |
+| 9   | mdcontext search "transformation organizational"                                                               | Find org transformation        | 10 results (62.7% top)                       | Yes      |
+| 10  | mdcontext search "intervention points human decision"                                                          | Find human intervention points | 10 results (68.7% top)                       | Yes      |
+| 11  | mdcontext context docs/06-WORKFLOWS.md -t 3000                                                                 | Get workflows overview         | Core workflow concepts extracted             | Yes      |
+| 12  | mdcontext context docs/06-WORKFLOWS.md --section "Workflow Design Principles"                                  | Get design principles          | Do/Don't guidelines                          | Yes      |
+| 13  | mdcontext context docs.amorphic/04-THE_HUMAN-AGENT_COLLABORATION_MODEL.md --section "Intervention Points"      | Get intervention details       | Redirect, override, inject, escalate         | Yes      |
+| 14  | mdcontext context docs.amorphic/06-ORGANIZATIONAL_TRANSFORMATION.md -t 3000                                    | Get org transformation         | Roles, culture, governance, implementation   | Yes      |
+| 15  | mdcontext context docs.amorphic/02-THE_FAILURE_OF_PURE_AUTOMATION.md -t 2500                                   | Get automation failures        | Brittleness, context collapse, judgment gap  | Yes      |
+| 16  | mdcontext context docs/04-EXECUTION_MODEL.md --section "Execution Philosophy"                                  | Get execution philosophy       | Scoped, disposable attempts                  | Yes      |
+| 17  | mdcontext context docs/04-EXECUTION_MODEL.md --section "Key Execution Patterns"                                | Get execution patterns         | Ad-hoc, guided, long-running, parallel       | Yes      |
+| 18  | mdcontext search "continuous improvement feedback loop"                                                        | Find feedback loops            | 3 results (learning loop)                    | Moderate |
+| 19  | mdcontext context docs/06-WORKFLOWS.md --section "Learning Loop"                                               | Get learning loop details      | Metrics feed refinement                      | Moderate |
+| 20  | mdcontext context docs.llm/feedback.md -t 2500                                                                 | Get feedback concepts          | Hybrid intelligence, resonance               | Yes      |
+| 21  | mdcontext search "checkpoint governance approval"                                                              | Find checkpoint content        | 5 results (executive decision)               | Moderate |
+| 22  | mdcontext context docs/07-EXAMPLE_WORKFLOWS.md -t 3000                                                         | Get example workflows          | Individual idea exploration example          | Yes      |
+| 23  | mdcontext search "versioning iteration reuse"                                                                  | Find versioning content        | 6 results                                    | Moderate |
+| 24  | mdcontext context docs/06-WORKFLOWS.md --section "Workflow Versioning"                                         | Get versioning details         | Immutable versioning model                   | Yes      |
+| 25  | mdcontext search "human override control interrupt"                                                            | Find human control             | 3 results (Human Interrupts)                 | Yes      |
+| 26  | mdcontext context docs/01-ARCHITECTURE.md --section "Human Interrupts"                                         | Get interrupt flow             | Control plane directive flow                 | Moderate |
+| 27  | mdcontext search "memory workspace context"                                                                    | Find memory concepts           | 10 results (Workspace Memory top)            | Yes      |
+| 28  | mdcontext context docs/05-MEMORY_MODEL.md -t 2500                                                              | Get memory model               | Three-layer architecture                     | Yes      |
+| 29  | mdcontext search "parallel exploration concurrent"                                                             | Find parallel patterns         | 10 results (67% match)                       | Yes      |
+| 30  | mdcontext context docs/04-EXECUTION_MODEL.md --section "Parallel Exploration"                                  | Get parallel pattern           | Fan-out/fan-in pattern                       | Yes      |
+| 31  | mdcontext search "audit trail transparency accountability"                                                     | Find audit content             | 6 results (67.1% match)                      | Yes      |
+| 32  | mdcontext context docs.amorphic/04-THE_HUMAN-AGENT_COLLABORATION_MODEL.md --section "Audit Trails That Matter" | Get audit trails               | Immutable records that tell stories          | Yes      |
+| 33  | mdcontext search "decision making recommendation suggestions"                                                  | Find recommendations           | 1 result (Recommendation primitive)          | Moderate |
+| 34  | mdcontext context docs/02-PRIMITIVES.md --section "Recommendation"                                             | Get recommendation definition  | Ranked suggestions with confidence           | Yes      |
+| 35  | mdcontext context docs/03-ORG_WORKSPACE_MODEL.md -t 2500                                                       | Get org/workspace model        | Two-tier identity model                      | Yes      |
+| 36  | mdcontext search "time travel rollback branching"                                                              | Find branching concepts        | 8 results (62.6% match)                      | Yes      |
+| 37  | mdcontext context docs/05-MEMORY_MODEL.md --section "Time Travel and Branching"                                | Get time travel details        | Rewind, compare, branch capabilities         | Yes      |
+| 38  | mdcontext search "compliance governance regulation"                                                            | Find compliance content        | 8 results                                    | Yes      |
+| 39  | mdcontext context docs/07-EXAMPLE_WORKFLOWS.md --section "Example 5: Enterprise-Compliance Review"             | Get compliance example         | Full enterprise workflow example             | Yes      |
+| 40  | mdcontext context docs/02-PRIMITIVES.md --section "Signal"                                                     | Get signal primitive           | Activity, outcome, attention, health signals | Yes      |
+| 41  | mdcontext context docs.amorphic/04-THE_HUMAN-AGENT_COLLABORATION_MODEL.md -t 3000                              | Get full collaboration model   | Authority gradient, spectrum of modes        | Yes      |
+
+## Findings
+
+### Key Discoveries
+
+#### 1. Workflow Philosophy: Guidance Without Control
+
+The documentation emphasizes workflows as **reusable coordination patterns that shape how work unfolds, without prescribing execution logic**. This is a fundamental process improvement over rigid automation.
+
+#### 2. Six Core Workflow Concepts
+
+Every workflow consists of exactly six concepts:
+
+1. **Entry Signals** - Conditions that suggest relevance (not trigger automatically)
+2. **Roles** - Perspectives needed (enables agent replacement, human participation)
+3. **Phases** - Conceptual stages (ordered but not strictly enforced, skippable)
+4. **Activities** - What kind of work happens (not how to do it)
+5. **Checkpoints (Guardrails)** - Deliberate pauses for human re-engagement
+6. **Exit Conditions** - When workflow naturally concludes
+
+#### 3. Human-Agent Collaboration Model
+
+The "Authority Gradient" enables dynamic adjustment of human involvement:
+
+- **Instructional Mode**: Step-by-step human instructions
+- **Consultative Mode**: Human defines goal, agent proposes approaches
+- **Supervisory Mode**: Agents execute with autonomy, humans monitor
+- **Exploratory Mode**: Humans and agents alternate generating/testing ideas
+
+#### 4. Intervention Points (Critical Process Improvement)
+
+Humans can:
+
+- **Redirect** an agent mid-task
+- **Override** a decision before execution
+- **Inject** new requirements during planning
+- **Escalate** when complexity exceeds thresholds
+
+#### 5. The Failure of Pure Automation (Anti-Patterns)
+
+The docs identify key problems with pure automation:
+
+- **Brittleness**: Works until it doesn't (80% flawless, 20% chaos)
+- **Context Collapse**: Treats context as configuration, not conversation
+- **Coordination Trap**: Multiplies coordination by forcing machine-readable formats
+- **Judgment Gap**: Absence of contextual fluency
+- **Innovation Strangulation**: Cannot accommodate work that hasn't been done before
+
+#### 6. Three-Layer Memory Architecture
+
+- **Event Memory**: Immutable, append-only source of truth
+- **Status Memory**: Derived, mutable projection of current situation
+- **Semantic Memory**: Knowledge graph for understanding and recommendations
+
+#### 7. Time Travel and Branching
+
+Powerful process improvement enabling:
+
+- Rewind to any point in time
+- Compare states (diff artifacts, trace decisions)
+- Branch for safe experimentation
+- Parallel hypotheses without loss
+
+#### 8. Parallel Exploration Pattern
+
+Multiple execution contexts can run concurrently:
+
+- Distinct scopes (no mutual exclusion)
+- Produce parallel alternatives
+- Resolution is explicit, separate act
+- Human reviews and merges
+
+#### 9. Workflow Versioning
+
+- Immutable versioning model
+- Specific version pinning or "latest" reference
+- Active workflows never upgrade mid-execution
+- Human approval for version upgrades
+
+#### 10. Organizational Transformation Framework
+
+- **Choreographic Maturity Model** (4 levels):
+  1. Tool Usage
+  2. Workflow Integration
+  3. Adaptive Choreography
+  4. Organizational Intelligence
+- **Cultural Shifts**: Experimental mindsets, transparent feedback, distributed decision-making
+
+### Relevant Quotes/Sections Found
+
+> "Workflows are reusable coordination patterns that shape how work unfolds, without prescribing execution logic."
+> Source: docs/06-WORKFLOWS.md, Workflow Philosophy
+
+> "Checkpoints are where: Human control is enforced, Cost is consciously acknowledged, Autonomy is bounded, Trust is built. Most agent systems lack this concept entirely."
+> Source: docs/06-WORKFLOWS.md, Checkpoints (Guardrails)
+
+> "A human can: Redirect an agent mid-task, Override a decision before execution, Inject new requirements during planning, Escalate when complexity exceeds thresholds. The system doesn't break-it adapts."
+> Source: docs.amorphic/04-THE_HUMAN-AGENT_COLLABORATION_MODEL.md, Intervention Points
+
+> "The goal isn't to minimize human involvement, but to optimize the unique contributions each participant brings. The most sophisticated choreographed intelligence systems often appear less automated than simpler ones."
+> Source: docs.amorphic/06-ORGANIZATIONAL_TRANSFORMATION.md, The Paradox of Automation
+
+> "Every event creates an immutable record, but unlike traditional logs, these records tell a story. They capture not just what happened, but why it happened, who was involved, and what alternatives were considered."
+> Source: docs.amorphic/04-THE_HUMAN-AGENT_COLLABORATION_MODEL.md, Audit Trails That Matter
+
+> "Recommendations are computed, explainable, optional, support override, and carry no authority."
+> Source: docs/02-PRIMITIVES.md, Recommendation
+
+> "HumanWork treats execution as a series of scoped, disposable attempts guided by durable intent."
+> Source: docs/04-EXECUTION_MODEL.md, Execution Philosophy
+
+### Answer to Research Question
+
+**What workflow and process improvements are suggested?**
+
+The documentation suggests a comprehensive framework of workflow and process improvements centered on **human-first design with intelligent agent collaboration**:
+
+1. **From Rigid to Adaptive Workflows**: Replace prescriptive automation with coordination patterns that guide without controlling. Workflows suggest structure, surface activities, and enforce checkpoints while allowing human override at any point.
+
+2. **Checkpoint-Driven Governance**: Insert frequent, deliberate pauses (checkpoints) where humans re-engage, confirm direction, and make explicit decisions about cost and autonomy. This builds trust and prevents runaway automation.
+
+3. **Dynamic Authority Gradient**: Enable seamless transitions between different collaboration modes (instructional, consultative, supervisory, exploratory) based on context, confidence, and stakes.
+
+4. **Granular Intervention Points**: Allow humans to redirect, override, inject, or escalate at every event boundary without breaking the system or restarting workflows.
+
+5. **Event-Sourced Memory**: Use immutable event logs as source of truth, enabling time travel, branching, safe experimentation, and complete audit trails.
+
+6. **Parallel Exploration**: Support concurrent execution of multiple approaches with distinct scopes, enabling humans to compare alternatives before committing.
+
+7. **Semantic Discovery**: Layer a knowledge graph on top of facts to enable natural language queries, pattern recognition, and recommendations without giving it control authority.
+
+8. **Versioned, Reusable Workflows**: Capture proven patterns as immutable, versioned workflows that can be shared across teams and evolved without disrupting active work.
+
+9. **Transparency Architecture**: Make every decision, action, and state change observable in real-time. Transform audit trails from archaeology into documentation.
+
+10. **Organizational Choreography**: Develop choreographic capabilities as competitive advantage - context-dependent, relationship-based, continuously evolving collaboration patterns.
+
+## Proposed Spec Changes
+
+Based on findings, consider these additions to any spec:
+
+- [ ] Add explicit checkpoint requirements for all high-stakes workflows
+- [ ] Define minimum intervention points per workflow phase
+- [ ] Require confidence levels on all recommendations (strongly/moderately/weakly supported)
+- [ ] Mandate immutable event logging as source of truth
+- [ ] Support branching and time travel for exploratory work
+- [ ] Enable parallel execution contexts for comparative analysis
+- [ ] Implement workflow versioning with upgrade approval gates
+- [ ] Create signals taxonomy (activity, outcome, attention, health)
+- [ ] Design interfaces supporting seamless collaboration mode transitions
+- [ ] Establish choreographic maturity assessment framework
+
+## Tool Evaluation
+
+### What Worked Well
+
+- Semantic search was effective at finding conceptually related content across multiple documents
+- Match percentages gave useful confidence signals (71.6% for human-agent collaboration was spot-on)
+- Section-level context extraction worked excellently (--section flag)
+- Token budget control prevented context overflow
+- Index with embeddings was fast and cost-effective (~$0.003)
+- Tree command gave quick overview of all files
+- Search results showed which docs were most relevant
+
+### What Was Frustrating
+
+- Some searches returned 0 results when content definitely existed (e.g., "efficiency productivity scaling team")
+- Token truncation warnings didn't always indicate which sections were excluded clearly
+- No way to search across multiple specific sections at once
+- Had to run many searches to explore different concept angles
+- Some duplicate content between docs/ and docs.llm/ folders inflated results
+
+### What Was Missing
+
+- No way to get "all sections mentioning X" in one command
+- No comparative search (find docs that mention A AND B vs A OR B semantically)
+- No export/save functionality for search results
+- Would benefit from a "related sections" feature after finding one
+- No batch context extraction for multiple files in one command
+- Could use a "summarize all findings" aggregation feature
+
+### Confidence Level
+
+[X] High / [ ] Medium / [ ] Low
+
+The tool successfully surfaced the core workflow and process improvement concepts from the documentation. Semantic search found relevant sections across all three document folders, and the context extraction provided sufficient detail to answer the research question comprehensively.
+
+### Would Use Again? (1-5)
+
+**4** - Very useful for document exploration and targeted extraction. The semantic search with embeddings is significantly better than keyword grep. Main limitation is the manual iteration required to explore multiple concept angles. Would be 5/5 with batch operations and better result aggregation.
+
+## Time & Efficiency
+
+- Commands run: 41
+- Compared to reading all files: **Much less** - Would have taken 2-3x longer to manually read and synthesize 23 documents (8,000+ lines estimated). The tool allowed targeted extraction of exactly the sections needed.