docs: enrich runtime-adjacent docs (OPERATIONS, AGENTS, ROADMAP, logs) — closes #3

AGENTS.md

@@ -2,7 +2,7 @@
 
 This repository is the canonical operating layer for agents.
 
-If an agent starts in this repository, it must orient by these files, not by hidden chat history or target-project documents.
+If an agent starts in this repository, it must orient by these files — not by hidden chat history or target-project documents.
 
 ## Read Order
 
@@ -32,10 +32,23 @@ If runtime files are missing, create them without asking the user:
 
 The scripts call the shared bootstrap path automatically. A fresh agent should run `./smoke-runtime.sh` or any runtime command before declaring the system unusable.
 
+## Channels
+
+- `inbox/for-executor.md`
+- `inbox/for-auditor.md`
+- `outbox/for-orchestrator.md`
+- `outbox/metrics.log`
+- `auditor_logs/events.log`
+
 ## Main Rules
 
 - Keep this repository generic; committed files must not depend on a specific target product.
 - Use local target-packs for real target repositories unless a human explicitly asks to publish one.
 - Do not copy chat history into task context.
 - Every system-level decision leaves an artifact: task, dispute, roadmap entry, issue or PR.
+- If a task is connected to an external repository, determine the active target-pack from `STATE.md` or an explicit `targets/<name>.md` first.
 - If a fresh agent cannot continue from committed docs plus local runtime state, continuity is broken.
+
+## Legacy Boundary
+
+Documents outside `multiagentsystem` may be read as reference-only sources, but not treated as live canon without an explicit decision.

OPERATIONS.md

@@ -1,10 +1,23 @@
-# Operations
+# Operations Guide
 
 ## First Principle
 
-An agent should not ask the user to create missing runtime files. If `STATE.md`, channels, logs or local runtime folders are absent, create them through the scripts or by applying the documented templates.
+An agent must not ask the user to create missing runtime files. If `STATE.md`, channels, logs, or local runtime folders are absent, create them through the scripts or by applying the documented templates.
 
-## Fresh Clone
+## 1. What This Runtime Is
+
+`multiagentsystem` is a file-based IPC layer for multi-agent coordination:
+
+- `watchdog.sh` delivers dispatch files to live agent sessions;
+- `coordinator.sh` routes signals, reviews and retries;
+- `STATE.md` holds live short-form state;
+- `tasks/` stores the recoverable task lifecycle;
+- `targets/` connects external repositories via target-packs;
+- `auditor_logs/` records critical events and disputes.
+
+## 2. Setup
+
+### Fresh Clone
 
 Run:
 
@@ -15,46 +28,243 @@ Run:
 
 Both commands call the shared bootstrap path and create local runtime files as needed.
 
-## Optional Config
+### Optional: Local Config
 
 ```bash
 cp config/agents.env.example config/agents.env
 ```
 
-`config/agents.env` is local and ignored by git.
+`config/agents.env` is local and ignored by git. It can be used to:
 
-## Target-Pack Workflow
+- change agent session names;
+- set executor and auditor launch commands;
+- disable auto-cron;
+- enable a default target-pack.
 
-Create a local target-pack:
+### Verify Setup
 
 ```bash
-cp targets/TARGET_TEMPLATE.md targets/example.local.md
+./smoke-runtime.sh
+./start.sh --dry-run
 ```
 
-Fill in absolute paths, then activate:
+## 3. Starting the Runtime
+
+```bash
+./start.sh
+./ws-status.sh
+```
+
+`start.sh`:
+
+- creates runtime dirs and logs;
+- creates or reuses executor and auditor sessions;
+- starts `watchdog.sh`;
+- adds `coordinator.sh` to cron if auto-cron is enabled;
+- activates the default target-pack if configured.
+
+If a local agent CLI is not found automatically, the script still raises a shell session and leaves it ready for manual agent launch.
+
+## 4. Stopping the Runtime
 
 ```bash
-./set-target.sh targets/example.local.md
+./stop.sh
 ```
 
-Local target-packs are ignored by git by default.
+`stop.sh`:
+
+- stops the watchdog;
+- removes the cron entry for this project;
+- terminates only the executor/auditor sessions belonging to this runtime.
 
-## Task Workflow
+## 5. Creating a Task
+
+Quick method:
 
 ```bash
 ./new-task.sh "Short task title"
+```
+
+Optionally specify a target explicitly:
+
+```bash
+./new-task.sh --target my-project "Investigate dashboard index drift"
+```
+
+After creating a task:
+
+1. Open the generated `tasks/TASK-XXX.md`;
+2. Clarify goal, criteria and context;
+3. Check the dispatch envelope;
+4. Leave `STATUS QUEUED`.
+
+The coordinator picks up the first `QUEUED` task automatically when no task is active.
+
+## 6. Activating a Target-Pack
+
+If work is tied to a specific repository:
+
+```bash
+./set-target.sh targets/<name>.md
+```
+
+This updates `STATE.md` and makes the target the current system context.
+
+To clear the target:
+
+```bash
+./set-target.sh --clear
+```
+
+Create a local target-pack from the template:
+
+```bash
+cp targets/TARGET_TEMPLATE.md targets/example.local.md
+```
+
+Fill in absolute paths, then activate as above. Local target-packs are ignored by git by default.
+
+## 7. Channels
+
+### inbox
+
+- `inbox/for-executor.md`
+- `inbox/for-auditor.md`
+
+### outbox
+
+- `outbox/for-orchestrator.md`
+- `outbox/metrics.log`
+- `outbox/coordinator.log`
+- `outbox/watchdog.log`
+
+## 8. Task Statuses
+
+- `QUEUED`
+- `IN_PROGRESS`
+- `REVIEW`
+- `DONE`
+- `BLOCKED`
+
+Retry after audit failure is tracked through task notes and the transition `REVIEW -> IN_PROGRESS`.
+
+## 9. Working with a Target Repository
+
+Before working on a target repository, read:
+
+1. `targets/README.md`
+2. The active `targets/<name>.md`
+3. `README.md` of the active repository
+4. `ROADMAP.md` or equivalent of the active repository
+5. Recovery anchors from the target-pack if needed
+
+Key rules:
+
+- Do not carry over old chat history;
+- Validate target docs against current repository contents;
+- Record significant gaps between code, indexes, reports and docs in task or audit notes.
+
+## 10. Stall Recovery
+
+If a task is stuck:
+
+```bash
 ./ws-status.sh
+tail -40 outbox/coordinator.log
+tail -40 outbox/metrics.log
+```
+
+If watchdog or sessions are dead:
+
+```bash
+./stop.sh
+./start.sh
+```
+
+## 11. Automation Report Coverage
+
+Check whether the audit/improve layer has fallen behind execution:
+
+```bash
+./automation-report-status.sh
+./automation-report-status.sh --json
 ```
 
-Task files are local operational state unless promoted intentionally.
+For gate-checking in automation:
+
+```bash
+./automation-report-status.sh --strict
+```
+
+If status is `audit_lag`, an audit loop over the latest execution report must run first. If status is `improvement_lag`, the improve loop must read the latest audit report and create a timestamped improvement report, even if the conclusion is no-op.
+
+A `filename_warning` status means a report with a non-canonical filename exists in `automation_reports/*/`. Such a file does not participate in coverage decisions; the next improve loop must either create a correct canonical report or leave an explicit remediation note. The correct filename format is: `YYYY-MM-DDTHHMMSSZ_<kind>.md`.
+
+## 12. Automation Run Guard
+
+Before performing real execution work, acquire a lock and confirm the report chain is closed:
+
+```bash
+./automation-run-guard.sh acquire <lock-name> --require-status ok
+trap './automation-run-guard.sh release <lock-name>' EXIT
+```
+
+If the guard returns `guard_blocked`, the execution loop must not modify the target repository. In that case, write a short blocker report or wait for the audit/improve loop if the cause is `audit_lag` / `improvement_lag`.
+
+Check lock state:
+
+```bash
+./automation-run-guard.sh status <lock-name>
+```
+
+A lock older than `AUTOMATION_LOCK_STALE_MIN` minutes is considered stale and may be cleared by the guard automatically. Default value: `45`.
+
+## 13. Automation Hygiene
+
+If subagent/parallel role verification is unavailable due to an external error, the report must explicitly state:
+
+- which role was requested;
+- which infrastructure error was received;
+- which shell checks replaced independent verification;
+- that this is a limitation, not a full independent review.
+
+Automation loops must not run broad scans across the entire workspace without a bounded scope. By default, search only within the active target repository, `multiagentsystem`, or specific recovery anchors from the target-pack.
+
+If a broad search is genuinely required, the report must specify:
+
+- the exact scope;
+- why restriction to target-pack paths is insufficient;
+- a timeout/cleanup strategy;
+- confirmation that no long-running processes remain.
+
+## 14. When to Open a DISPUTE
+
+If the problem is not "a script won't start" but "we disagree on which contract is correct", open a `DISPUTE`.
+
+## 15. What Counts as a Successful Runtime
+
+- `smoke-runtime.sh` is green;
+- `start.sh --dry-run` is green;
+- `ws-status.sh` sees the runtime;
+- a target-pack can be activated without manually rewriting documents;
+- a fresh agent understands the read-order without consulting legacy docs.
+
+## 16. Automation Reports Quarantine
+
+`automation_reports/quarantine/` holds files moved there due to format or content errors.
+
+Files in `quarantine/` do not participate in coverage decisions (`automation-report-status.sh` ignores them).
 
-## Runtime Commands
+A file ends up in quarantine when:
+- it has a `filename_warning` that was not fixed within 2+ cycles;
+- the report has a critical structural error (no header, no timestamps, no summary);
+- the file is a duplicate with the same timestamp as an existing canonical report.
 
-- `./start.sh --dry-run`: preview local sessions and config.
-- `./start.sh`: start tmux sessions and watchdog if dependencies exist.
-- `./coordinator.sh`: route queued work and process signals once.
-- `./watchdog.sh`: deliver dispatch files to live tmux sessions.
-- `./stop.sh`: stop local sessions owned by this runtime.
+To recover a file from quarantine:
+1. Rename it to canonical format: `YYYY-MM-DDTHHMMSSZ_<kind>.md`;
+2. Verify structure (summary, timestamp, conclusions present);
+3. Move it back to the appropriate `automation_reports/<kind>s/`;
+4. Run `./automation-report-status.sh` to confirm.
 
 ## GitHub Workflow
 

ROADMAP.md

@@ -1,19 +1,29 @@
 # Roadmap
 
+## Current Goal
+
+Make `multiagentsystem` the single working canon for multi-agent coordination and for connecting new target repositories.
+
 ## P0
 
 - Keep the framework product-neutral.
 - Keep runtime bootstrap idempotent.
-- Preserve fresh-agent continuity.
+- Preserve fresh-agent continuity without relying on hidden chat history.
 - Keep GitHub process artifacts aligned with local runtime rules.
+- Prevent the introduction of new legacy conflicts.
 
 ## P1
 
-- Add an end-to-end task lifecycle test.
+- Add an end-to-end task lifecycle test covering the full `dispatch -> review -> retry -> done` cycle.
+- Add a reusable template for target-packs for new projects.
+- Introduce an explicit lifecycle for `canonical / derived / legacy` documents.
 - Add optional GitHub Pages management dashboard only after an explicit issue.
 - Add richer recovery diagnostics for stale local sessions.
 
 ## P2
 
+- Add a human-readable dashboard diff for task/status/events.
+- Consider a lightweight index for archived disputes and events.
+- Add portable validation for target project contracts.
 - Add portable adapters for additional agent CLIs.
 - Add generated health reports for framework maintainers.

auditor_logs/README.md

@@ -1,5 +1,17 @@
 # Auditor Logs
 
-This directory holds local audit logs, dispute files and runtime events.
+This directory holds the institutional memory of the runtime layer.
 
 Committed examples should stay generic. Live `*.log` files are ignored.
+
+## Files
+
+- `events.log`
+  Critical events: final audit failures, stalls, blocked escalations.
+
+- `DISPUTE-NNN.md`
+  Formal disputes and their resolutions.
+
+## Rule
+
+`coordinator.log` may be read as an operational log. Files in `auditor_logs/` are institutional memory that must not be silently discarded.