From d3d4dd5815ebab81a9e09969062c5ef8b31fa138 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 29 Apr 2026 16:19:48 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20enrich=20runtime-adjacent=20docs=20(OPE?= =?UTF-8?q?RATIONS,=20AGENTS,=20ROADMAP,=20logs)=20=E2=80=94=20batch=203?= =?UTF-8?q?=20of=20#3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adapt and translate local Russian versions into GitHub canonical English: - OPERATIONS.md: complete operations guide (setup, start/stop, tasks, targets, channels, stall recovery, automation guard, hygiene, quarantine) - AGENTS.md: add Startup Rule, Channels section, Legacy Boundary - ROADMAP.md: add P1/P2 items from local version - auditor_logs/README.md: clarify institutional memory rule - automation_reports/README.md: add coverage contract, naming rule examples - memory/README.md: add priority order on conflict Closes #3 (batch 3 of 3 — all enrichment batches now complete) Co-authored-by: Claude (coordinator agent) --- AGENTS.md | 15 ++- OPERATIONS.md | 248 ++++++++++++++++++++++++++++++++--- ROADMAP.md | 14 +- auditor_logs/README.md | 14 +- automation_reports/README.md | 50 ++++++- memory/README.md | 10 ++ 6 files changed, 327 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d676687..40e43c8 100644 --- a/AGENTS.md +++ b/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/.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. diff --git a/OPERATIONS.md b/OPERATIONS.md index 7d29987..5a24d6c 100644 --- a/OPERATIONS.md +++ b/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/.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/.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_.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 --require-status ok +trap './automation-run-guard.sh release ' 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 +``` + +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_.md`; +2. Verify structure (summary, timestamp, conclusions present); +3. Move it back to the appropriate `automation_reports/s/`; +4. Run `./automation-report-status.sh` to confirm. ## GitHub Workflow diff --git a/ROADMAP.md b/ROADMAP.md index ae97117..bee1f6f 100644 --- a/ROADMAP.md +++ b/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. diff --git a/auditor_logs/README.md b/auditor_logs/README.md index 7aff967..902f00a 100644 --- a/auditor_logs/README.md +++ b/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. diff --git a/automation_reports/README.md b/automation_reports/README.md index dbd9c84..6d0a246 100644 --- a/automation_reports/README.md +++ b/automation_reports/README.md @@ -1,3 +1,51 @@ # Automation Reports -Automation reports are local by default. Commit only reusable examples or framework-level summaries. +Automation reports record evidence for the autonomous operation cycle of `multiagentsystem`. + +Reports are local by default. Commit only reusable examples or framework-level summaries. + +## Streams + +- `execution/` + What agents actually did in the target repository. +- `audit/` + How closely the work matched the framework rules. +- `improvements/` + What changes were made to the framework itself after reading execution/audit reports. + +## Naming Rule + +Each run must create a new timestamped report rather than overwriting an existing one. + +Report filenames must follow UTC format: + +```text +YYYY-MM-DDTHHMMSSZ_.md +``` + +Example: + +```text +2026-04-23T134009Z_audit.md +``` + +Files that do not match this timestamp pattern do not participate in coverage decisions and are treated as a filename warning. + +## Coverage Check + +From the repository root: + +```bash +./automation-report-status.sh +./automation-report-status.sh --json +./automation-report-status.sh --strict +``` + +Coverage contract: + +- the latest audit report must reference the latest execution report; +- the latest improvement report must reference the latest audit report; +- a no-op improvement must still leave a timestamped improvement report; +- non-canonical filenames must be surfaced via `malformed_reports`. + +A `audit_lag` status means the improve loop must not pretend everything is closed: an audit loop over the new execution report must run first. diff --git a/memory/README.md b/memory/README.md index 0a5801a..644a709 100644 --- a/memory/README.md +++ b/memory/README.md @@ -1,5 +1,15 @@ # Memory +`memory/` stores short derived summaries that help agents recover context faster. + Use this directory for durable framework memory that is intentionally promoted into git. Local target-specific memory should use ignored files such as `memory/context/*.local.md`. + +This is a useful layer, but not the primary canon. + +## Priority Order on Conflict + +1. Canonical docs in the repository root; +2. Active target-pack; +3. Derived memory in this directory.