docs: enrich core canon (README, MANIFEST, ARCHITECTURE, PRINCIPLES) — closes #3 batch 1

ARCHITECTURE.md

@@ -2,29 +2,58 @@
 
 ## Design Goal
 
-Build a self-contained framework that separates agent operating rules from target-project code.
+Build a self-contained framework that separates agent operating rules from target-project code, providing simultaneously:
+
+- a working runtime;
+- coherent canonical docs;
+- durable continuity;
+- generic target integration.
 
 ## Layer Model
 
-### Canonical Control Plane
+### 1. Canonical Control Plane
 
 Docs define roles, read order, lifecycle, dispute process and evidence rules.
 
-### Runtime Layer
+Files:
+
+- `AGENTS.md`
+- `MANIFEST.md`
+- `ARCHITECTURE.md`
+- `OPERATIONS.md`
+- `PRINCIPLES.md`
+- `DISPATCH_SPEC.md`
+- `DISPUTE.md`
+- `STATE.template.md`
+
+Role:
+
+- defines canon;
+- sets read-order;
+- records rules and the working model.
+
+### 2. Runtime Layer
 
 Portable bash scripts maintain local file-based IPC:
 
 - `lib/runtime.sh`
 - `start.sh`
-- `stop.sh`
 - `watchdog.sh`
 - `coordinator.sh`
+- `stop.sh`
 - `ws-status.sh`
 - `new-task.sh`
 - `set-target.sh`
 - `smoke-runtime.sh`
 
-### Continuity Layer
+Role:
+
+- creates and maintains the live IPC loop;
+- delivers dispatch;
+- updates state and queue;
+- leaves a runtime trail.
+
+### 3. Continuity Layer
 
 Local ignored files store live state:
 
@@ -36,10 +65,56 @@ Local ignored files store live state:
 - `auditor_logs/*.log`
 - `memory/`
 
-### GitHub-Native Layer
+Role:
+
+- stores task history;
+- records audit evidence;
+- provides recovery points after failures.
+
+### 4. Target Layer
+
+Files:
+
+- `targets/README.md`
+- `targets/TARGET_TEMPLATE.md`
+- `targets/*.md`
+
+Role:
+
+- connects any external repository without copying old conversations;
+- describes the active path, baseline, read-order and canon rules for a specific repo.
+
+### 5. GitHub-Native Layer
 
 GitHub issues, pull requests, labels and actions govern changes to this framework. They do not replace the local runtime for target work.
 
+## Runtime Flow
+
+```text
+orchestrator
+  -> creates TASK-XXX
+  -> coordinator extracts dispatch and writes inbox/for-executor.md
+  -> watchdog prepends executor role pack and delivers message into tmux
+  -> executor writes signals into outbox/for-orchestrator.md
+  -> coordinator updates state/task and routes to auditor when needed
+  -> watchdog delivers audit dispatch
+  -> auditor writes AUDIT PASS or AUDIT FAIL
+  -> coordinator closes, retries or escalates
+```
+
+## Why Bash + Files + tmux
+
+- routing and retry logic is deterministic, so it should not burn tokens;
+- file-based continuity survives crashes better than hidden in-chat state;
+- tmux keeps long-lived agent sessions inspectable;
+- target-packs separate "how agents work" from "what product they currently touch".
+
 ## Boundary
 
 Target repositories do not receive this runtime unless a human explicitly installs it there. A target product can have its own UI, issues and automation; this framework can later have a management UI, but those UIs must not be mixed.
+
+## Non-Goals
+
+- Do not store the full history of a target product inside the control plane.
+- Do not create a target-specific runtime for each repository.
+- Do not replace repository docs with old chat memory.

MANIFEST.md

@@ -1,15 +1,27 @@
 # MANIFEST — MultiAgentSystem
 
-## Purpose
+## 1. Purpose
 
 `multiagentsystem` is a portable Agentic OS for:
 
-- coordinating AI agents through explicit roles and artifacts;
-- preserving continuity without hidden chat state;
-- connecting any external repository through a target-pack;
-- developing the framework itself through GitHub-native workflow.
+- coordinating AI agents through file-based IPC and explicit roles;
+- preserving live task and audit continuity;
+- continuing work on any target repository through the target-pack mechanism;
+- developing the framework itself through a GitHub-native workflow;
+- evolving the system itself without fragmenting into inconsistent documents and scripts.
 
-## Canon
+## 2. Three-Layer Assembly
+
+The system is deliberately assembled from three layers:
+
+1. `continuity layer`
+   Live memory, task history, audit evidence and recovery anchors.
+2. `runtime/spec layer`
+   Formal rules, dispatch, watchdog, coordinator and task contract.
+3. `target layer`
+   Connecting external repositories through target-packs without copying old chat history.
+
+## 3. Canon
 
 Committed canon:
 
@@ -39,24 +51,101 @@ Local canon during a run:
 
 Local canon is ignored by git unless a human explicitly promotes an artifact into the framework.
 
-## Working Cycle
+## 4. Roles and Responsibility
+
+### orchestrator
+
+Responsible for:
+
+- decomposing and creating tasks;
+- selecting and activating the target-pack;
+- updating `STATE.md`;
+- escalations, retries and `DISPUTE`;
+- preserving continuity so that a fresh agent can recover from files alone.
+
+### executor
+
+Responsible for:
+
+- completing the task;
+- local verification before handoff;
+- correct signal contract in `outbox/metrics.log` and `outbox/for-orchestrator.md`;
+- reading task artifacts and target context instead of waiting for hidden chat.
+
+### auditor
+
+Responsible for:
+
+- a verifiable audit;
+- PASS only on confirmed evidence;
+- FAIL only with a specific reason;
+- no unauthorized fixing in place of auditing.
+
+## 5. Working Cycle
 
 ```text
 orchestrator
-  -> creates task
-  -> coordinator dispatches to executor
-  -> watchdog delivers the message to a live session
-  -> executor works and emits DONE, NEEDS_REVIEW or BLOCKED
-  -> coordinator routes review or closes/escalates
-  -> auditor emits AUDIT PASS or AUDIT FAIL
+  -> creates TASK-XXX
+  -> coordinator dispatches envelope to inbox/for-executor.md
+  -> watchdog delivers it into executor tmux session
+  -> executor works and writes NEEDS_REVIEW / DONE / BLOCKED
+  -> coordinator updates task/state and routes to auditor when needed
+  -> watchdog delivers review context into auditor session
+  -> auditor writes AUDIT PASS / AUDIT FAIL
+  -> coordinator closes, retries or escalates
 ```
 
-## Success Definition
+## 6. Task Model
+
+Each task:
+
+- lives as a separate file `tasks/TASK-XXX.md`;
+- has a machine-readable metadata line `STATUS ...`;
+- contains a typed dispatch envelope;
+- contains enough human context for manual recovery after a failure.
+
+The task file must be simultaneously:
+
+- usable by an agent;
+- parseable by the coordinator;
+- sufficient for the next attempt without hidden chat memory.
+
+## 7. Target Integration Contract
+
+The system does not store the full history of a target repository internally.
+
+Instead, for each target the following must exist:
+
+- target name;
+- active repo path;
+- baseline/reference repo path if needed;
+- read-order for a fresh agent;
+- recovery anchors;
+- canon rules for that specific repo.
+
+The contract template is described in `targets/TARGET_TEMPLATE.md`.
+
+## 8. Success Definition
 
 The system works when:
 
-1. a fresh clone can create its missing local runtime files;
-2. scripts run without product-specific paths;
-3. a local target-pack can connect an external repository;
-4. a task can be created, dispatched and inspected from files;
-5. a fresh agent can recover by reading docs, local state, target-pack and task artifacts.
+1. `start.sh` brings up the runtime or correctly shows a dry-run;
+2. `watchdog.sh` delivers dispatch into live sessions;
+3. `coordinator.sh` can route, retry and leave an audit trail;
+4. `ws-status.sh` shows the health of the loop;
+5. a fresh agent can continue work from canonical system files and a target-pack without old chat history;
+6. a fresh clone can create its missing local runtime files;
+7. scripts run without product-specific paths;
+8. a task can be created, dispatched and inspected from files.
+
+## 9. Evolution Rule
+
+The following changes must not disappear into chat without an artifact.
+
+Permitted forms:
+
+- a new task;
+- an entry in `ROADMAP.md`;
+- an entry in `auditor_logs/events.log`;
+- a new `DISPUTE-XXX.md`;
+- a GitHub Issue or Pull Request for framework-level changes.

PRINCIPLES.md

@@ -1,41 +1,67 @@
-# PRINCIPLES
+# PRINCIPLES — Constitutional Rules
 
 ## P-01 Data Honesty
 
 Do not present unverified assumptions as facts.
 
 ## P-02 Credentials From Environment Only
 
-Tokens, keys and passwords must not appear in tasks, dispatch envelopes, logs or committed docs.
+Tokens, keys and passwords must not appear in task files, dispatch envelopes, logs or committed docs.
 
 ## P-03 Irreversible Actions Need Review
 
-Deletes, deploys, sends, price changes and other irreversible actions require a safety gate.
+Deletes, deploys, sends, price changes and any other irreversible actions require explicit approval and a safety gate.
 
 ## P-04 Build Only For Real Pain
 
-Do not add components because they are interesting. Add them because a real workflow needs them.
+Do not add a new component unless it is a response to a real workflow need.
 
 ## P-05 Simple And Inspectable First
 
-Files, bash, tmux and explicit contracts are preferred until scale proves otherwise.
+Files, bash, tmux and explicit contracts are preferred over "smart" magic until scale proves otherwise.
 
 ## P-06 Dispute As Artifact
 
-A conceptual disagreement is formal only when recorded as a dispute artifact.
+A conceptual disagreement is formal only when recorded as a dispute artifact in `DISPUTE-XXX.md` or another explicit artifact.
 
 ## P-07 Speak Only For Your Role
 
-Do not invent another role's position or approval.
+Do not invent another agent's position or attribute a stance to them without an explicit artifact.
 
 ## P-08 Fresh-Agent Continuity
 
-A new agent must be able to continue from committed docs plus local runtime artifacts. If hidden chat is required, the process is broken.
+A new agent must be able to continue work by reading only the canonical docs, `STATE.md`, a target-pack and task files.
+
+If hidden chat history is required to continue, the system is not well assembled.
 
 ## P-09 Target-Pack Over Chat History
 
-For target projects, store paths, read order, anchors and rules, not old conversations.
+For target projects, store:
+
+- the active path;
+- baseline/reference;
+- read-order;
+- recovery anchors;
+- canon criteria for the target project.
+
+Do not store old conversations.
 
 ## P-10 System Decisions Leave A Trace
 
-Changes to roles, lifecycle, runtime or policy must leave a task, issue, PR, dispute or roadmap entry.
+Changes to architecture, rules, roles or runtime must result in one of:
+
+- `TASK-XXX`
+- `DISPUTE-XXX.md`
+- an entry in `ROADMAP.md`
+- an audit event
+- a GitHub Issue or Pull Request for framework-level changes
+
+## Refusal With A Route
+
+An agent may refuse a useless or dangerous attempt, but may not disappear silently.
+
+Permitted outcomes:
+
+- `TASK-XXX BLOCKED: ...`
+- `TASK-XXX NEEDS_REVIEW: ...`
+- decomposition of the task into an achievable part