N1ghthill · N1ghthill · Mar 24, 2026 · Mar 24, 2026
@@ -45,8 +45,17 @@ jobs:
       - name: Run unit tests
         run: PYTHONPATH=src python -m unittest discover -s tests
 
-      - name: Run pytest suite
-        run: PYTHONPATH=src python -m pytest -q
+      - name: Run pytest unit suite
+        run: >-
+          PYTHONPATH=src python -m pytest -q tests
+          --ignore tests/test_runtime_policy_integration.py
+          --ignore tests/test_mcp_stdio_integration.py
+
+      - name: Run pytest runtime integration suite
+        run: >-
+          PYTHONPATH=src python -m pytest -q
+          tests/test_runtime_policy_integration.py
+          tests/test_mcp_stdio_integration.py
 
       - name: Compile source tree
         run: python -m compileall src

@@ -76,7 +76,7 @@
 ### Notes
 
 - the repository is still pre-release
-- the current unreleased target is the `0.1.0a2` release candidate documented in `docs/release-candidate-0.1.0a2.md`
+- the current unreleased target is the `0.1.0a2` release candidate documented in `docs/history/release-candidate-0.1.0a2.md`
 - the narrow local CLI MVP is closed for the current alpha baseline
 - the project is not yet a production-ready Linux operations platform
 

@@ -19,7 +19,7 @@ MC is built around three constraints:
 - single-host and local-first by design
 - install path: source checkout plus `install.sh`
 - validated on the maintainer workstation and on a dedicated Debian 13 VPS lab
-- main integration interface: experimental read-only MCP stdio
+- main integration interface: experimental MCP stdio with approval-mediated write flow
 - local administration interface: CLI
 - optional interface: chat/provider path
 - not positioned as a production-ready Linux administration platform, security auditor, or package manager
@@ -56,6 +56,7 @@ If `install.sh` reports that `ensurepip` is unavailable on Debian or Ubuntu, ins
 - host, disk, memory, process, service, and journal inspection
 - process-to-`systemd` correlation and failed-service triage
 - managed config read, write, backup, and restore inside a constrained policy boundary
+- operator-configurable policy through a versioned TOML file with safe defaults and fail-closed load errors
 - recommendation workflow with explicit approval before risky execution
 - repeatable host-profile validation through `mc validate-host-profile`
 - optional heuristic, OpenAI, and Ollama-backed planning on top of the same runtime
@@ -64,9 +65,13 @@ If `install.sh` reports that `ensurepip` is unavailable on Debian or Ubuntu, ins
 
 - [Documentation map](docs/README.md)
 - [Current status](docs/status.md)
+- [Roadmap](docs/roadmap.md)
+- [Runtime + MCP maturation plan](docs/runtime-mcp-maturation-plan.md)
 - [Architecture](docs/architecture.md)
 - [Security model](docs/security-model.md)
+- [Policy guide](docs/policy.md)
 - [Operator workflows](docs/operator-workflows.md)
+- [Runtime integration testing](docs/runtime-integration-testing.md)
 - [Provider setup](docs/providers.md)
 - [Host-profile validation guide](docs/host-profile-validation.md)
 - [Validation evidence](docs/alpha-validation-report.md)

@@ -8,42 +8,46 @@ Use this file to find the right working document, validation record, or planning
 ## Start Here
 
 - `README.md`: GitHub-facing overview, current posture, and quick-start path
-- `docs/status.md`: authoritative snapshot of maturity, implemented scope, and validation baseline
-- `docs/release-candidate-0.1.0a2.md`: current release-candidate record and cut state
+- `docs/status.md`: authoritative snapshot of current maturity, scope, and validation baseline
+- `docs/roadmap.md`: concise phase-level roadmap for the current direction
+- `docs/runtime-mcp-maturation-plan.md`: canonical execution plan for the MCP-first runtime maturation track
 
 ## Product And Operator Guides
 
-- `docs/providers.md`: provider selection, setup, and behavior
-- `docs/operator-workflows.md`: supported operator workflows and follow-up paths
+- `docs/architecture.md`: system structure, scope boundaries, and major flows
+- `docs/security-model.md`: safety model, approval boundaries, and execution constraints
+- `docs/policy.md`: operator-configurable policy file guide
+- `docs/operator-workflows.md`: bounded operator workflows and evidence chains
 - `docs/host-profile-validation.md`: maintainer/operator host validation harness guide
 - `docs/community-host-validation.md`: public submission flow for external host validation
+- `docs/providers.md`: provider setup and behavior for the optional planner layer
 - `docs/release-checklist.md`: release execution checklist
 
 ## Validation And Evidence
 
-- `docs/alpha-validation-report.md`: main alpha-track validation summary
-- `docs/vps-validation-report.md`: dedicated Debian 13 VPS lab validation evidence
+- `docs/alpha-validation-report.md`: main validation summary for the current pre-1.0 baseline
+- `docs/runtime-integration-testing.md`: runtime and MCP contract validation guide
+- `docs/vps-validation-report.md`: dedicated Debian VPS validation evidence
 - `docs/vps-validation-runbook.md`: repeatable runbook for the maintainer-controlled VPS lab
-- `docs/call-for-testers.md`: maintainer-facing outreach copy for collecting more validation evidence
+- `docs/call-for-testers.md`: outreach copy for collecting more host-validation evidence
 
-## Architecture And Security
+## Supporting Engineering Docs
 
-- `docs/architecture.md`: system structure, scope boundaries, and major flows
-- `docs/security-model.md`: safety model, approval boundaries, and execution constraints
+- `docs/core-interfaces-refactor-plan.md`: supporting engineering brief for the remaining code-ownership cleanup
+- `docs/beta-readiness-gate.md`: beta gate criteria and release blockers
 - `docs/adrs/`: architectural decision records
 - `docs/diagrams/README.md`: diagram index and rendering notes
 
-## Plans And Release Management
+## Historical Records
 
-- `docs/core-interfaces-refactor-plan.md`: canonical working brief for the runtime-first refactor
-- `docs/roadmap.md`: high-level sequence of work and milestone framing
-- `docs/beta-readiness-gate.md`: beta gate criteria and current release blockers
-- `docs/beta-resume-plan.md`: short-horizon maintainer execution record
-- `docs/mvp-plan.md`: original MVP definition
-- `docs/mvp-evolution-plan.md`: MVP evolution and closeout record
-- `docs/mvp-closeout-backlog.md`: deferred backlog after MVP closeout
-- `docs/post-mvp-evolution-plan.md`: longer-horizon post-MVP planning
-- `docs/alpha-release-notes.md`: current alpha-facing release notes
+- `docs/history/README.md`: index of historical planning and release records
+- `docs/history/release-candidate-0.1.0a2.md`: historical cut record for the current public pre-release
+- `docs/history/alpha-release-notes.md`: historical alpha release notes
+- `docs/history/beta-resume-plan.md`: historical beta-prep execution record
+- `docs/history/mvp-plan.md`: original MVP framing kept for traceability
+- `docs/history/mvp-evolution-plan.md`: MVP closeout sequencing record
+- `docs/history/mvp-closeout-backlog.md`: MVP closeout completion record
+- `docs/history/post-mvp-evolution-plan.md`: previous planning record kept for context
 
 ## Contribution And Repository Docs
 
@@ -55,6 +59,8 @@ Use this file to find the right working document, validation record, or planning
 - `README.md` stays short and GitHub-facing
 - `docs/README.md` is the canonical document map
 - `docs/status.md` records the current reality; it is not the marketing page
+- `docs/roadmap.md` and `docs/runtime-mcp-maturation-plan.md` are the current planning references
+- historical documents stay available for traceability, but they are not authoritative for current direction
 - validation reports record evidence and should avoid private host coordinates or internal-only access details
-- planning documents keep maintainer context; stable operator instructions belong in focused guides
+- stable operator instructions belong in focused guides
 - when you add, rename, or repurpose a document, update this map
@@ -23,7 +23,7 @@ The authoritative direction is now runtime-first: the conversational path is an
 - treat MCP as the main integration interface on top of the runtime
 - keep the CLI as the local operator and administration interface
 - preserve the existing chat/provider path as an optional interface
-- keep an experimental read-only MCP bridge on top of the same runtime
+- keep an experimental MCP bridge with approval-mediated write flow on top of the same runtime
 - persist local state and audit data in SQLite
 - keep the codebase modular, but inside one deployable process
 
@@ -205,7 +205,7 @@ Its planners, providers, summaries, and rendering helpers are interface logic, n
 
 ### MCP
 
-An experimental read-only MCP stdio bridge now exists.
+An experimental MCP stdio bridge now exists with approval-mediated write operations.
 It is the main integration interface for exposing runtime capabilities to external AI clients without duplicating policy, audit, or execution logic.
 Broader capability exposure remains intentionally deferred until the runtime boundary is easier to own.
 

@@ -9,7 +9,8 @@ This document defines the minimum bar for moving Master Control from the current
 It is not a feature wishlist.
 It is a release gate.
 
-Use `docs/beta-resume-plan.md` for short-horizon execution order.
+Use `docs/roadmap.md` and `docs/runtime-mcp-maturation-plan.md` for current planning.
+`docs/history/beta-resume-plan.md` remains available as a historical execution record.
 Use this document only to decide whether beta claims and tagging are actually justified.
 
 ## Gate Summary

@@ -58,7 +58,7 @@ Master Control `0.1.0a2` is available as a preview build for real Linux host tes
 
 The project already has:
 
-- a bounded CLI-first operator workflow
+- a bounded local-first runtime for host operations
 - typed diagnostics and approval-gated mutations
 - a repeatable host-validation harness
 - a redacted bundle flow for submitting validation reports
@@ -79,7 +79,7 @@ Full guide: docs/community-host-validation.md
 ```text
 I am looking for Linux testers for Master Control.
 
-It is a CLI-first host admin agent with typed diagnostics, approval-gated actions, and a built-in validation flow.
+It is a local-first runtime for controlled Linux host operations, with typed diagnostics, approval-gated actions, and a built-in validation flow.
 
 If you can run a quick validation on your own Linux host and send the generated redacted report, that would help broaden the real-host evidence base beyond the first validated profiles.
 

@@ -118,4 +118,4 @@ See also:
 
 - `docs/host-profile-validation.md`
 - `docs/beta-readiness-gate.md`
-- `docs/beta-resume-plan.md`
+- `docs/roadmap.md`
@@ -297,14 +297,14 @@ These documents contain useful evidence or historical execution context and shou
 - `docs/alpha-validation-report.md`
 - `docs/vps-validation-report.md`
 - `docs/vps-validation-runbook.md`
-- `docs/release-candidate-0.1.0a2.md`
-- `docs/alpha-release-notes.md`
+- `docs/history/release-candidate-0.1.0a2.md`
+- `docs/history/alpha-release-notes.md`
 - `docs/beta-readiness-gate.md`
-- `docs/beta-resume-plan.md`
-- `docs/mvp-plan.md`
-- `docs/mvp-evolution-plan.md`
-- `docs/mvp-closeout-backlog.md`
-- `docs/post-mvp-evolution-plan.md`
+- `docs/history/beta-resume-plan.md`
+- `docs/history/mvp-plan.md`
+- `docs/history/mvp-evolution-plan.md`
+- `docs/history/mvp-closeout-backlog.md`
+- `docs/history/post-mvp-evolution-plan.md`
 - `docs/community-host-validation.md`
 - `docs/host-profile-validation.md`
 

@@ -0,0 +1,16 @@
+# Historical Docs
+
+This directory contains documents kept for traceability.
+
+These files are not the current product brief or roadmap.
+Use `docs/status.md`, `docs/roadmap.md`, and `docs/runtime-mcp-maturation-plan.md` for current guidance.
+
+## Contents
+
+- `alpha-release-notes.md`: alpha release notes record
+- `beta-resume-plan.md`: beta-prep execution record
+- `mvp-plan.md`: original MVP framing
+- `mvp-evolution-plan.md`: MVP closeout sequencing record
+- `mvp-closeout-backlog.md`: MVP closeout completion record
+- `post-mvp-evolution-plan.md`: previous planning record
+- `release-candidate-0.1.0a2.md`: pre-release cut record
@@ -1,5 +1,11 @@
 # Alpha Release Notes
 
+> Historical document
+>
+> This file is kept for traceability of the alpha release line.
+> It is not the current product brief or roadmap.
+> Use `docs/status.md`, `docs/roadmap.md`, and `docs/runtime-mcp-maturation-plan.md` for current guidance.
+
 Version target: `0.1.0a2` local CLI alpha release candidate
 
 Snapshot date: 2026-03-18
@@ -95,4 +101,4 @@ mc tool service_status --arg name=ollama-local.service --arg scope=user
 ## Validation reference
 
 See `docs/alpha-validation-report.md` and `docs/vps-validation-report.md` for the current real-host validation snapshots behind this alpha baseline.
-See `docs/release-candidate-0.1.0a2.md` for the current cut status and remaining release work.
+See `docs/history/release-candidate-0.1.0a2.md` for the current cut status and remaining release work.
@@ -1,5 +1,11 @@
 # Beta Resume Plan
 
+> Historical document
+>
+> This file is kept for traceability of earlier beta-prep execution work.
+> It is not the current product brief or roadmap.
+> Use `docs/status.md`, `docs/roadmap.md`, and `docs/runtime-mcp-maturation-plan.md` for current guidance.
+
 Snapshot date: 2026-03-20
 
 ## Purpose
@@ -140,7 +146,7 @@ Status:
 Near-term tasks:
 
 - summarize the dedicated VPS report in `docs/alpha-validation-report.md`
-- update `docs/beta-readiness-gate.md`, `docs/status.md`, `docs/roadmap.md`, and `docs/release-candidate-0.1.0a2.md`
+- update `docs/beta-readiness-gate.md`, `docs/status.md`, `docs/roadmap.md`, and `docs/history/release-candidate-0.1.0a2.md`
 - decide whether to tag now or keep the build in private-preview language a little longer
 - keep the community submission path simple enough that external testers can still contribute broader host diversity reports
 

@@ -1,5 +1,11 @@
 # MVP Closeout Backlog
 
+> Historical document
+>
+> This file is kept as the MVP closeout completion record.
+> It is not the current product brief or roadmap.
+> Use `docs/status.md`, `docs/roadmap.md`, and `docs/runtime-mcp-maturation-plan.md` for current guidance.
+
 Snapshot date: 2026-03-18
 
 ## Purpose
@@ -24,7 +30,7 @@ Completed milestones:
 - Milestone 3: operator utility and approval UX, completed on 2026-03-18
 - Milestone 4: alpha hardening and release baseline, completed on 2026-03-18
 
-The higher-level completion record remains in `docs/mvp-evolution-plan.md`.
+The higher-level completion record remains in `docs/history/mvp-evolution-plan.md`.
 
 ## Closed scope
 

@@ -1,5 +1,11 @@
 # MVP Evolution Plan
 
+> Historical document
+>
+> This file is kept as the MVP closeout sequencing record.
+> It is not the current product brief or roadmap.
+> Use `docs/status.md`, `docs/roadmap.md`, and `docs/runtime-mcp-maturation-plan.md` for current guidance.
+
 Snapshot date: 2026-03-18
 
 ## Purpose
@@ -8,9 +14,9 @@ This document now serves as the completion record for the delivery plan that clo
 
 It remains the canonical reference for how the repository's closeout documents relate to each other:
 
-- `docs/mvp-plan.md`: stable MVP contract and exit criteria
-- `docs/mvp-evolution-plan.md`: milestone sequencing and completion record
-- `docs/mvp-closeout-backlog.md`: closed execution backlog record
+- `docs/history/mvp-plan.md`: stable MVP contract and exit criteria
+- `docs/history/mvp-evolution-plan.md`: milestone sequencing and completion record
+- `docs/history/mvp-closeout-backlog.md`: closed execution backlog record
 - `docs/status.md`: current implementation snapshot
 - `docs/roadmap.md`: phase-level roadmap beyond the closed MVP
 

@@ -1,5 +1,11 @@
 # MVP Plan
 
+> Historical document
+>
+> This file preserves the original MVP framing for traceability.
+> It is not the current product brief or roadmap.
+> Use `docs/status.md`, `docs/roadmap.md`, and `docs/runtime-mcp-maturation-plan.md` for current guidance.
+
 ## Target MVP definition
 
 Master Control MVP means:
@@ -19,9 +25,9 @@ This MVP does not require web UI, daemon mode, plugins, or remote multi-user dep
 
 To avoid legacy planning drift, use the documents this way:
 
-- `docs/mvp-plan.md`: stable MVP contract and exit criteria
-- `docs/mvp-evolution-plan.md`: milestone sequencing and closeout completion record
-- `docs/mvp-closeout-backlog.md`: closed execution backlog record for the MVP closeout
+- `docs/history/mvp-plan.md`: stable MVP contract and exit criteria
+- `docs/history/mvp-evolution-plan.md`: milestone sequencing and closeout completion record
+- `docs/history/mvp-closeout-backlog.md`: closed execution backlog record for the MVP closeout
 - `docs/status.md`: current implementation snapshot
 - `docs/roadmap.md`: phase-level view of the post-closeout roadmap
 
@@ -39,7 +45,7 @@ The MVP should only be called complete when all of these are true:
 
 ## Current delta to close
 
-The narrow local CLI MVP closeout is complete. `docs/mvp-evolution-plan.md` now serves as the completion record for that delivery plan.
+The narrow local CLI MVP closeout is complete. `docs/history/mvp-evolution-plan.md` now serves as the completion record for that delivery plan.
 
 ### Workstream 1: Correctness and context hardening
 

@@ -1,5 +1,11 @@
 # Post-MVP Evolution Plan
 
+> Historical document
+>
+> This file is kept as a previous planning record for traceability.
+> It is not the current product brief or roadmap.
+> Use `docs/status.md`, `docs/roadmap.md`, and `docs/runtime-mcp-maturation-plan.md` for current guidance.
+
 Snapshot date: 2026-03-18
 
 ## Purpose
@@ -8,9 +14,9 @@ This document starts the next planning track after the narrow local CLI MVP clos
 
 It does not replace the closed MVP records:
 
-- `docs/mvp-plan.md`: stable contract for the narrow local CLI MVP
-- `docs/mvp-evolution-plan.md`: closed sequencing record for the MVP closeout
-- `docs/mvp-closeout-backlog.md`: closed backlog record for the MVP closeout
+- `docs/history/mvp-plan.md`: stable contract for the narrow local CLI MVP
+- `docs/history/mvp-evolution-plan.md`: closed sequencing record for the MVP closeout
+- `docs/history/mvp-closeout-backlog.md`: closed backlog record for the MVP closeout
 
 Instead, this file defines the next professional engineering track for turning Master Control from a validated late-alpha baseline into a more functional, operator-useful product.
 
@@ -445,7 +451,7 @@ Use the repository docs as operational artifacts with these roles:
 
 - `docs/status.md`: current implemented state only
 - `docs/roadmap.md`: phase-level direction and sequencing only
-- `docs/post-mvp-evolution-plan.md`: active planning record for the current post-MVP track
+- `docs/history/post-mvp-evolution-plan.md`: active planning record for the current post-MVP track
 - `docs/operator-workflows.md`: bounded operator journeys, smoke commands, and workflow safety notes
 - `docs/beta-readiness-gate.md`: release gate for moving from late alpha to beta-oriented scope
 - `docs/alpha-validation-report.md` or future validation docs: validation evidence only

@@ -1,5 +1,11 @@
 # Release Candidate 0.1.0a2
 
+> Historical document
+>
+> This file is kept for traceability of the `0.1.0a2` release cut.
+> It is not the current product brief or roadmap.
+> Use `docs/status.md`, `docs/roadmap.md`, and `docs/runtime-mcp-maturation-plan.md` for current guidance.
+
 Snapshot date: 2026-03-20
 
 ## Purpose
@@ -97,5 +103,5 @@ Related GitHub issues:
 1. attach or summarize the VPS report in `docs/alpha-validation-report.md`
 2. update `docs/beta-readiness-gate.md`, `docs/status.md`, and `docs/roadmap.md` to reflect that multi-host evidence now exists
 3. rerun the local baseline one final time
-4. confirm `CHANGELOG.md`, `docs/alpha-release-notes.md`, and the release wording are still aligned with the actual scope
+4. confirm `CHANGELOG.md`, `docs/history/alpha-release-notes.md`, and the release wording are still aligned with the actual scope
 5. decide whether to tag `0.1.0a2` immediately or keep the build in private-preview language a little longer