docs: expand documentation architecture and workflow coverage

Author: rand

.beads/issues.jsonl

@@ -2,7 +2,7 @@ SHELL := /bin/bash
 
 LOOP_MIN_AVAILABLE_MIB ?= 3072
 
-.PHONY: check lint typecheck test coverage rustdoc-check py-integration-gate ignored-repl-gate proptest-gate claude-adapter-gate review verify
+.PHONY: check lint typecheck test coverage rustdoc-check py-integration-gate ignored-repl-gate proptest-gate claude-adapter-gate docs-check review verify
 
 check: typecheck test
 
@@ -33,6 +33,9 @@ proptest-gate:
 claude-adapter-gate:
 	LOOP_MIN_AVAILABLE_MIB=$(LOOP_MIN_AVAILABLE_MIB) ./scripts/run_vg_claude_adapter_e2e_gate.sh
 
-review: typecheck rustdoc-check
+docs-check:
+	./scripts/check_docs_style.sh
 
-verify: check rustdoc-check py-integration-gate proptest-gate claude-adapter-gate
+review: typecheck rustdoc-check docs-check
+
+verify: check rustdoc-check py-integration-gate proptest-gate claude-adapter-gate docs-check

Makefile

@@ -159,9 +159,11 @@ rlm-core powers these projects:
 ## Documentation
 
 ### Start Here
+- [Documentation Architecture](docs/DOCS-ARCHITECTURE.md) - How docs are organized, maintained, and kept truthful.
 - [Documentation Portal](docs/README.md) - Role-based index and workflow-oriented navigation.
 - [User Guide](docs/user-guide/README.md) - New user to power-user guidance.
 - [Developer Guide](docs/developer-guide/README.md) - Setup, gates, and contribution workflow.
+- [Reference Commands](docs/reference/command-reference.md) - Fast lookup for common workflows.
 - [API Docs Status](docs/developer-guide/api-docs-status.md) - What "documented" currently means, without fiction.
 - [Internals](docs/internals/README.md) - Architecture, OODA flow, and module map.
 - [Troubleshooting](docs/troubleshooting/README.md) - Incident triage and diagnostics checklists.

README.md

@@ -0,0 +1,99 @@
+# Documentation Architecture
+
+This document defines how documentation in Loop is organized, written, and maintained.
+
+If this file is doing its job, nobody needs to ask "where should this live?" during review.
+
+## Goals
+
+1. Make the project operable for newcomers and maintainers.
+2. Keep behavior docs close to runtime truth.
+3. Provide reliable pathways by role, skill level, and workflow.
+4. Keep writing precise, human, and useful under pressure.
+
+## Audience Map
+
+| Audience | Primary docs | What success looks like |
+|---|---|---|
+| New user | `docs/user-guide/quickstart.md`, `docs/user-guide/learning-paths.md` | Can run first successful checks and avoid common footguns |
+| Returning user | `docs/user-guide/workflow-recipes.md`, `docs/reference/command-reference.md` | Can select and run the right workflow quickly |
+| Power user | `docs/user-guide/power-user-playbook.md` | Can tune depth, cost, and assurance for high-stakes work |
+| Contributor | `docs/developer-guide/setup.md`, `docs/developer-guide/workflow-cookbook.md` | Can ship changes with tests, docs, and evidence |
+| Maintainer | `docs/developer-guide/quality-gates.md`, `docs/troubleshooting/incident-playbook.md` | Can diagnose failures and land safe changes predictably |
+| Runtime debugger | `docs/internals/architecture.md`, `docs/internals/runtime-walkthrough.md`, `docs/internals/module-map.md` | Can trace behavior from symptom to module |
+| Architecture reader | `docs/concepts/mental-model.md`, `docs/concepts/principles.md`, `docs/adr/` | Can explain why system tradeoffs exist |
+
+## Workflow Coverage
+
+| Workflow | Start | Deep dive | Closeout |
+|---|---|---|---|
+| First run | `docs/user-guide/quickstart.md` | `docs/user-guide/learning-paths.md` | `docs/troubleshooting/common-issues.md` |
+| Feature development | `docs/developer-guide/workflow-cookbook.md` | `docs/developer-guide/quality-gates.md` | `docs/developer-guide/contribution-workflow.md` |
+| Adapter behavior changes | `docs/user-guide/claude-code-adapter.md` | `docs/internals/ooda-and-execution.md` | `docs/developer-guide/quality-gates.md` |
+| Spec and formalization work | `docs/user-guide/workflow-recipes.md` | `docs/spec/`, `docs/internals/runtime-walkthrough.md` | `docs/execution-plan/VALIDATION-MATRIX.md` |
+| Incident triage | `docs/troubleshooting/incident-playbook.md` | `docs/troubleshooting/diagnostics-checklist.md` | `docs/troubleshooting/common-issues.md` |
+| Command lookup | `docs/reference/command-reference.md` | `Makefile`, `scripts/` | `docs/execution-plan/evidence/` |
+
+## Document Types
+
+1. Orientation docs:
+   - Explain where to start and how to choose a path.
+   - Examples: `docs/README.md`, section `README.md` files.
+2. Procedure docs:
+   - Provide commands, success criteria, and failure protocol.
+   - Examples: user recipes, developer workflow cookbook, quality gates.
+3. Concept docs:
+   - Explain mental model and tradeoff logic.
+   - Examples: `docs/concepts/*`.
+4. Internals docs:
+   - Explain runtime behavior, module boundaries, and data flow.
+   - Examples: `docs/internals/*`.
+5. Troubleshooting docs:
+   - Turn symptoms into deterministic diagnosis and fixes.
+   - Examples: `docs/troubleshooting/*`.
+6. Reference docs:
+   - Fast lookup material, minimal narrative.
+   - Examples: `docs/reference/*`, `docs/glossary.md`.
+
+## Quality Contract
+
+Every operational document should satisfy:
+
+1. Explicit target reader.
+2. Concrete commands for procedures.
+3. Clear expected outcomes.
+4. Link to adjacent docs instead of copy-paste duplication.
+5. No typographic em dash punctuation.
+6. No aspirational claims without verification path.
+
+## Change Protocol
+
+When behavior changes:
+
+1. Update code and docs in the same change set.
+2. Update the nearest section index if navigation changes.
+3. Record validation evidence for nontrivial claims.
+4. Re-run docs style checks (`make docs-check`).
+
+When docs structure changes:
+
+1. Update `README.md` at repo root.
+2. Update `docs/README.md`.
+3. Update affected section `README.md`.
+4. Add at least one cross-link from an existing high-traffic page.
+
+## Anti-Patterns
+
+1. "TBD" as permanent architecture.
+2. Procedures without success criteria.
+3. Claims that cannot be validated.
+4. New docs that are not linked from any index page.
+5. Deleting old docs without redirecting readers to replacement paths.
+
+## Ownership
+
+- System-wide docs ownership is shared by active maintainers.
+- Every merged behavior change is responsible for its own documentation updates.
+- During review, "works in code but not in docs" counts as incomplete.
+
+Documentation is part of the runtime interface. It just compiles in human brains instead of cargo.

docs/DOCS-ARCHITECTURE.md

@@ -8,39 +8,50 @@ This documentation is organized by audience and workflow, not by who happened to
 
 | If you are... | Start here | Then go to |
 |---|---|---|
-| New to Loop | [User Guide](./user-guide/README.md) | [Workflow Recipes](./user-guide/workflow-recipes.md) |
-| Building features | [Developer Guide](./developer-guide/README.md) | [Quality Gates](./developer-guide/quality-gates.md) |
-| Debugging internals | [Internals](./internals/README.md) | [Troubleshooting](./troubleshooting/README.md) |
-| Looking for architecture rationale | [Concepts](./concepts/README.md) | [ADR Index](./adr/) |
+| New to Loop | [User Guide](./user-guide/README.md) | [Learning Paths](./user-guide/learning-paths.md) |
+| Building features | [Developer Guide](./developer-guide/README.md) | [Workflow Cookbook](./developer-guide/workflow-cookbook.md) |
+| Debugging internals | [Internals](./internals/README.md) | [Runtime Walkthrough](./internals/runtime-walkthrough.md) |
+| Looking for architecture rationale | [Concepts](./concepts/README.md) | [System Principles](./concepts/principles.md) |
+| Looking up exact commands | [Reference](./reference/README.md) | [Command Reference](./reference/command-reference.md) |
 
 ## Documentation Map
 
 ### User-Facing
 - [User Guide](./user-guide/README.md): Start-to-finish guidance by skill level.
+- [Learning Paths](./user-guide/learning-paths.md): Guided progression for beginners through power users.
 - [Claude Code Adapter Guide](./user-guide/claude-code-adapter.md): Capability envelope, limits, and OODA behavior.
 - [Workflow Recipes](./user-guide/workflow-recipes.md): End-to-end task playbooks.
 - [Power User Playbook](./user-guide/power-user-playbook.md): Performance, scale, and control.
 
 ### Developer-Facing
 - [Developer Guide](./developer-guide/README.md): Build and change Loop safely.
 - [Setup](./developer-guide/setup.md): Environment bootstrap.
+- [Workflow Cookbook](./developer-guide/workflow-cookbook.md): Change-type specific contribution runbooks.
 - [Quality Gates](./developer-guide/quality-gates.md): Tests, checks, governance.
 - [Contribution Workflow](./developer-guide/contribution-workflow.md): Branch-to-merge routine.
 
 ### Architecture and Internals
 - [Concepts](./concepts/README.md): Mental models and design vocabulary.
+- [System Principles](./concepts/principles.md): Decision criteria and tradeoff posture.
 - [Internals](./internals/README.md): Runtime architecture and module boundaries.
 - [Architecture](./internals/architecture.md): System structure and data flow.
 - [OODA + Execution Flow](./internals/ooda-and-execution.md): Observe/Orient/Decide/Act mapping.
+- [Runtime Walkthrough](./internals/runtime-walkthrough.md): Step-by-step request lifecycle trace.
 - [Python Orchestrator Swap Analysis](./internals/python-orchestrator-swap-analysis.md): Tradeoffs and decision framework for full Python orchestrator migration.
 - [Module Map](./internals/module-map.md): Where behavior actually lives.
 
 ### Operational and Recovery
 - [Troubleshooting](./troubleshooting/README.md): Fast diagnosis and fix paths.
+- [Incident Playbook](./troubleshooting/incident-playbook.md): Severity-based response and closure criteria.
 - [Common Issues](./troubleshooting/common-issues.md): Known failure patterns.
 - [Diagnostics Checklist](./troubleshooting/diagnostics-checklist.md): Structured incident capture.
 
+### Reference
+- [Reference Index](./reference/README.md): Quick lookup section.
+- [Command Reference](./reference/command-reference.md): Canonical command map by workflow.
+
 ### Reference and Specifications
+- [Documentation Architecture](./DOCS-ARCHITECTURE.md): How docs are structured and maintained.
 - [Specification Set](./spec/): Canonical feature contracts (SPEC-20 through SPEC-27).
 - [Spec Lineage Status](./spec/SPEC-LINEAGE-STATUS.md): How origin-era design/migration specs map to current live status.
 - [Execution Plan](./execution-plan/README.md): Program-level planning, evidence, and governance.
@@ -59,10 +70,11 @@ This documentation is organized by audience and workflow, not by who happened to
 ## Suggested Reading Order
 
 1. [Concepts: Mental Model](./concepts/mental-model.md)
-2. [User Guide](./user-guide/README.md)
-3. [Developer Setup](./developer-guide/setup.md)
-4. [Internals Architecture](./internals/architecture.md)
-5. [Troubleshooting](./troubleshooting/README.md)
+2. [Concepts: System Principles](./concepts/principles.md)
+3. [User Guide](./user-guide/README.md)
+4. [Developer Setup](./developer-guide/setup.md)
+5. [Internals Architecture](./internals/architecture.md)
+6. [Troubleshooting](./troubleshooting/README.md)
 
 ## Scope Note
 

docs/README.md

@@ -5,13 +5,15 @@ This section explains how to think about Loop before you care about where any sp
 ## Start Here
 
 - [Mental Model](./mental-model.md)
+- [System Principles](./principles.md)
 
 ## Conceptual Layers
 
 1. **Intent Layer**: User goals and jobs-to-be-done.
 2. **Orchestration Layer**: Complexity classification, decomposition, and execution strategy.
 3. **Evidence Layer**: Memory, traces, and verification artifacts.
 4. **Assurance Layer**: Tests, policy gates, compatibility checks, and release controls.
+5. **Decision Layer**: Principle-driven tradeoffs under real constraints.
 
 ## Why This Matters
 

docs/concepts/README.md

@@ -46,3 +46,6 @@ A healthy Loop workflow has:
 - Reproducible quality checks.
 
 Or, put differently: fewer mysteries and fewer surprises during push.
+
+Next read:
+- `principles.md` for decision criteria when tradeoffs appear.

docs/concepts/mental-model.md

@@ -0,0 +1,85 @@
+# System Principles
+
+These principles explain how Loop is intended to behave when design tradeoffs appear.
+
+If two choices both look reasonable, this file is the tie-breaker.
+
+## 1. Evidence Beats Confidence
+
+Claims about behavior should be backed by:
+
+1. Passing checks and tests.
+2. Reproducible command output.
+3. Artifact paths for nontrivial validations.
+
+Why:
+- Confidence is cheap and usually wrong at scale.
+- Evidence survives context switching.
+
+## 2. Determinism Over Heroics
+
+Operational workflows should prefer deterministic outcomes over fragile brilliance.
+
+Examples:
+- Policy gates with machine-readable JSON output.
+- Stable command sequences in user and developer docs.
+- Explicit failure protocols in troubleshooting docs.
+
+## 3. Contracts Before Convenience
+
+External surfaces are contract-sensitive.
+Internal implementations can evolve, but behavioral contracts need deliberate change control.
+
+Examples:
+- Compatibility helper surfaces for Python integration.
+- Feature contracts under `docs/spec/`.
+- Adapter efficacy gates that guard real scenarios.
+
+## 4. Bounded Autonomy
+
+Loop automates aggressively, but not infinitely.
+Activation, mode escalation, and memory use are bounded and observable.
+
+Why:
+- Unbounded autonomy is just expensive drift.
+- Bounded systems are easier to debug and trust.
+
+## 5. Practical Formalism
+
+Formal methods are used where they add safety and leverage, not as decoration.
+
+Examples:
+- Tiered formalization depth (`Types`, `Invariants`, `Contracts`, `FullProofs`).
+- Proof and sync paths integrated with governance gates.
+
+## 6. Documentation Is Runtime Surface
+
+Docs are part of the product interface.
+If behavior changes and docs do not, users still experience a bug.
+
+Required habits:
+
+1. Update docs in the same change set as behavior.
+2. Keep navigation indexes current.
+3. Keep procedures command-driven and falsifiable.
+
+## 7. Friction Where It Matters
+
+Loop adds process friction at high-risk boundaries:
+
+1. Pre-commit and pre-push policy enforcement.
+2. Coverage and adapter efficacy gates.
+3. Evidence logging for significant changes.
+
+That friction is intentional. It costs minutes now to save days later.
+
+## Decision Questions
+
+When unsure, ask:
+
+1. Does this change improve reproducibility?
+2. Does it reduce hidden risk for users or maintainers?
+3. Can another engineer validate the same outcome independently?
+4. Is the behavior clear in both code and docs?
+
+If the answer is mostly "no," it is not ready yet.

docs/concepts/principles.md

@@ -5,9 +5,10 @@ This guide is for contributors changing code in Loop itself.
 ## Start Here
 
 1. [Setup](./setup.md)
-2. [Quality Gates](./quality-gates.md)
-3. [Contribution Workflow](./contribution-workflow.md)
-4. [API Docs Status](./api-docs-status.md)
+2. [Workflow Cookbook](./workflow-cookbook.md)
+3. [Quality Gates](./quality-gates.md)
+4. [Contribution Workflow](./contribution-workflow.md)
+5. [API Docs Status](./api-docs-status.md)
 
 ## Development Contract
 
@@ -22,3 +23,4 @@ This guide is for contributors changing code in Loop itself.
 - Runtime planning and multi-session execution rules: `docs/execution-plan/`
 - Feature contracts: `docs/spec/`
 - Architecture rationale: `docs/adr/`
+- Fast command lookup: `docs/reference/command-reference.md`

docs/developer-guide/README.md

@@ -18,7 +18,8 @@ A disciplined path from idea to merged, reproducible change.
 
 1. Run targeted tests during development.
 2. Run `make check` before commit.
-3. Run governance gates before push.
+3. Run `make docs-check` for docs/style safety.
+4. Run governance gates before push.
 
 ## 4. Close Work Properly