microcoreos 0.2.0__tar.gz → 0.2.2__tar.gz

microcoreos-0.2.2/.agent/skills/microcoreos-architecture/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: microcoreos-architecture
+description: Ensures adherence to MicroCoreOS "Atomic Microkernel" architecture. Use when creating or modifying core, tools, plugins, or domains.
+---
+
+# MicroCoreOS Architecture Skill
+
+**Read `AGENTS.md` and follow the route for your role.** That table names the
+one or two files your role needs and, just as importantly, the ones it must not
+open — a Planner that also loads the plugin templates spends ~3,000 tokens on
+code it will never write.
+
+This file deliberately holds no rules, no reading path and no checklist of its
+own. It used to hold all three, and all three had drifted: its reading path
+sent plugin authors to `INSTRUCTIONS_FOR_AI.md` for templates that live in the
+generated manifest, and its checklist was a fifth partial copy of the 13
+Non-Negotiable Rules — one that never mentioned typed event payloads.
+
+| You need | It is in |
+|---|---|
+| The rules | `AGENTS.md` § Non-Negotiable Rules (13, canonical) |
+| Kernel/tool/event-bus laws | `AGENTS.md` § Core Architectural Laws |
+| The plugin template | `AI_CONTEXT.md` § Plugin Authoring Guide (regenerated every boot) |
+| What exists right now | `AI_CONTEXT.md` § Available Tools / § Domains |
+| The plan format and its 18 rules | `docs/PARALLEL_DEVELOPMENT.md` § Phase 1 |
+| Anti-patterns, testing, building a tool | `INSTRUCTIONS_FOR_AI.md` |
+
+Before you finish, the gates are commands, not a checklist to eyeball:
+
+```bash
+microcoreos plan validate     # the plan is a contract — zero errors
+uv run -m pytest              # green
+microcoreos status            # manifest still describes the code on disk
+```

{microcoreos-0.2.0 → microcoreos-0.2.2}/.agent/skills/microcoreos-architecture/agent.md

@@ -10,7 +10,7 @@ You are a **Systems Architect** specialized in high-performance, resilient micro
 ## Decision Framework
 - **Core First**: Is this change affecting the Core? If yes, look for an alternative in Plugins/Tools.
 - **Tool Isolation**: Does this Tool import another Tool? If so, REJECT the design and move the logic to a Plugin (Bridge).
-- **Sacred Rules Review**: Before implementation, verify against the "Three Golden Rules" in `SKILL.md`.
+- **Rules Review**: Before implementing, check the 13 Non-Negotiable Rules in `AGENTS.md`. (This line used to cite "Three Golden Rules in SKILL.md" — a document that never existed.)
 - **Resilience**: Will a failure here crash the entire system?
 - **Observability**: Can this be monitored via the `registry`?
 

{microcoreos-0.2.0 → microcoreos-0.2.2}/.agent/workflows/feature-plan.md

@@ -8,11 +8,36 @@ The smallest planning level: new plugins on a domain that already exists. No
 migrations, no new tools — if you need either, escalate to
 [new-domain.md](new-domain.md) or [multi-domain-plan.md](multi-domain-plan.md).
 
+## Before you plan — read these two, in this order
+
+1. **`plans/active_plan.yaml`** — the file you are about to overwrite. It ships
+   as a worked example of all three feature shapes. It **is** the format, not a
+   description of one, and it is the cheapest way to have it.
+2. **`AI_CONTEXT.md`**, down to `## 🧩 Plugin Authoring Guide` — the tables,
+   models, routes and events that already exist. Inherit their names exactly.
+
+Then write to **`plans/active_plan.yaml`** — that exact path, overwriting it —
+and run `microcoreos plan validate` until it reports zero errors. Errors carry
+the YAML that fixes them: paste it.
+
+**Write the file before you ask anything.** Checking in is fine — planning
+often is a conversation — but never *instead of* writing: a plan that exists
+only as prose in your reply is a plan the next phase cannot read, and the run
+may not be interactive at all. So write the YAML, validate it, and then raise
+whatever you wanted to raise; the operator answers against a real file instead
+of a description. Where a detail is genuinely undecidable, take what the
+existing vocabulary implies, put it in the YAML, and flag it in a comment.
+
+`docs/PARALLEL_DEVELOPMENT.md` § Phase 1 holds the rules behind the format.
+Read it when a validator error is unclear, not before — and never reach for
+plugin source under `domains/`, `tools/` or `extras/` to infer the shape. A
+planner that did produced a plan with every field renamed.
+
 ## Prerequisites
 
-- Read `AI_CONTEXT.md` — the live inventory (tools, domains, events, routes).
-- Check `GET /system/events/schemas` (or the "Events emitted" lines in
-  `AI_CONTEXT.md`) for the payload contracts of any event you will consume.
+Both files above. For an event you will consume, its payload contract is the
+"Events emitted" line of the publishing domain in `AI_CONTEXT.md` (or
+`GET /system/events/schemas` on a running system).
 
 ## Steps
 
@@ -37,7 +62,7 @@ plan:
           model: OrderCancelledPayload
           payload: { id: int, reason: str }
       consumes: []
-      mocks: [db, event_bus]
+      tools: [http, db, event_bus, logger]   # every tool __init__ takes
       test: tests/test_cancel_order.py
   flows:
     - name: order-cancellation
@@ -60,10 +85,10 @@ plan:
 
 ### 2. Validate before writing code
 
-`POST /system/plan/validate` with the plan (YAML or JSON) — it runs the 16
-validity rules of `docs/PARALLEL_DEVELOPMENT.md` against this plan AND the
-live system. Zero `errors` before any code; `warnings` are advisory. The main
-things it catches at this level:
+`microcoreos plan validate` — it runs the 18 validity rules of
+`docs/PARALLEL_DEVELOPMENT.md` against this plan AND what the repo already
+occupies, with no server running. Zero `errors` before any code; `warnings` are
+advisory. The main things it catches at this level:
 
 - The `route` and `file` collide with nothing live.
 - Every consumed event exists (live system or this plan) and provides the
@@ -82,7 +107,7 @@ Publish with `XxxPayload(...).model_dump()` — bare call, no arguments.
 
 - One test per plugin proving the black-box contract: input → output, DB
   effects on the declared tables, published payloads with the declared fields.
-  Mock exactly the tools the plan's `mocks:` lists; run the rest as real
+  Mock exactly the tools the plan's `tools:` lists; run the rest as real
   in-memory instances (`INSTRUCTIONS_FOR_AI.md` § Testing).
 - One double-delivery test per idempotent link (same envelope twice → same
   final state), at the path declared in `idempotency_test`.

microcoreos-0.2.2/.agent/workflows/multi-domain-plan.md

@@ -0,0 +1,88 @@
+---
+description: Plan and build a large spec spanning multiple domains (full formal plan, parallel execution)
+---
+
+# Multi-Domain Plan Workflow
+
+The largest planning level: a spec that creates or touches several domains,
+with event chains crossing domain boundaries. The methodology is fully
+specified in `docs/PARALLEL_DEVELOPMENT.md` — this workflow is its checklist.
+
+**Everything is decided before any code exists**: every migration, model,
+tool, plugin, route, event (with its payload model), and every chain with its
+happy path and sad paths. Code-time conflicts are structurally impossible;
+what remains is getting the plan right.
+
+## Before you plan — read these two, in this order
+
+1. **`plans/active_plan.yaml`** — the file you are about to overwrite. It ships
+   as a worked example of all three feature shapes. It **is** the format, not a
+   description of one, and it is the cheapest way to have it.
+2. **`AI_CONTEXT.md`**, down to `## 🧩 Plugin Authoring Guide` — the tables,
+   models, routes and events that already exist. Inherit their names exactly.
+
+Then write to **`plans/active_plan.yaml`** — that exact path, overwriting it —
+and run `microcoreos plan validate` until it reports zero errors. Errors carry
+the YAML that fixes them: paste it.
+
+**Write the file before you ask anything.** Checking in is fine — planning
+often is a conversation — but never *instead of* writing: a plan that exists
+only as prose in your reply is a plan the next phase cannot read, and the run
+may not be interactive at all. So write the YAML, validate it, and then raise
+whatever you wanted to raise; the operator answers against a real file instead
+of a description. Where a detail is genuinely undecidable, take what the
+existing vocabulary implies, put it in the YAML, and flag it in a comment.
+
+`docs/PARALLEL_DEVELOPMENT.md` § Phase 1 holds the rules behind the format.
+Read it when a validator error is unclear, not before — and never reach for
+plugin source under `domains/`, `tools/` or `extras/` to infer the shape. A
+planner that did produced a plan with every field renamed.
+
+## Phase 1 — The full plan (the contract, authored FIRST)
+
+Write the complete YAML plan of `docs/PARALLEL_DEVELOPMENT.md` ("Formal plan
+format") to `plans/active_plan.yaml`: `phase_0` (every migration with its
+`tables:` ownership AND its full `columns:` — phase 0 is built from the plan,
+nothing is improvised later), `features` (one per plugin, with
+`publishes.model` / `consumes.requires` / the `db:` persistence contract),
+and `flows` — each with
+its `durability` (may in-flight events die with the process? `durable` needs
+the sqlite/redis driver) and the sad-path checklist per link:
+
+- `retries` / `backoff` — re-delivery policy
+- `idempotent` — MANDATORY `true` where `retries > 0` OR the flow is `durable`
+  (durable transports re-deliver after a crash even with zero retries)
+- `idempotency_test` — the double-delivery proof for every idempotent link
+- `dlq_watcher` — who consumes `_dlq.<event>` (`null` = loss explicitly
+  accepted; a non-null watcher must exist in the plan or live)
+- `atomic_with_db` — `true` means this chain cannot lose the event between DB
+  commit and publish → it is the implementation trigger for the Transactional
+  Outbox (ROADMAP Issue 28); flag it, do not improvise one
+- `compensation` — the event that undoes upstream work if the chain dies
+  (saga); it must be published AND consumed within the plan
+- `sad_path_test` (flow-level) — mandatory when any link declares retries,
+  a DLQ watcher or a compensation
+- `rpc_links` (flow-level) — every `request()` call, with `timeout` and
+  `on_timeout`
+
+Then run the 18 validity rules mechanically: `microcoreos plan validate`
+(offline — nothing needs to be booted) — zero `errors` before building
+anything. An invalid plan is a task-allocation error — fix the plan,
+never patch it in code.
+
+## Phases 0, 2 and 3
+
+Identical to any other plan — `docs/PARALLEL_DEVELOPMENT.md` owns them, and
+restating them here is how this file once kept prescribing a boot command that
+had stopped regenerating the manifest.
+
+Two things are specific to multi-domain work and are the only reason this
+section exists:
+
+- **Migration ordering across domains.** One author for the numbering, and
+  `-- depends: other_domain/001_file.sql` wherever a table in one domain must
+  exist before another's. The db tool resolves the order and prints each file
+  as it applies it.
+- **Never assign two agents to the same feature**, and never let one agent
+  touch two domains. The wave is safe precisely because the write sets are
+  disjoint.

{microcoreos-0.2.0 → microcoreos-0.2.2}/.agent/workflows/new-domain.md

@@ -10,9 +10,36 @@ Creates a full domain from scratch: entity model, SQL migration, and one plugin
 > one new domain → this workflow · several domains / cross-domain chains →
 > [multi-domain-plan.md](multi-domain-plan.md) · new infrastructure → [new-tool.md](new-tool.md).
 
+## Before you plan — read these two, in this order
+
+1. **`plans/active_plan.yaml`** — the file you are about to overwrite. It ships
+   as a worked example of all three feature shapes. It **is** the format, not a
+   description of one, and it is the cheapest way to have it.
+2. **`AI_CONTEXT.md`**, down to `## 🧩 Plugin Authoring Guide` — the tables,
+   models, routes and events that already exist. Inherit their names exactly.
+
+Then write to **`plans/active_plan.yaml`** — that exact path, overwriting it —
+and run `microcoreos plan validate` until it reports zero errors. Errors carry
+the YAML that fixes them: paste it.
+
+**Write the file before you ask anything.** Checking in is fine — planning
+often is a conversation — but never *instead of* writing: a plan that exists
+only as prose in your reply is a plan the next phase cannot read, and the run
+may not be interactive at all. So write the YAML, validate it, and then raise
+whatever you wanted to raise; the operator answers against a real file instead
+of a description. Where a detail is genuinely undecidable, take what the
+existing vocabulary implies, put it in the YAML, and flag it in a comment.
+
+`docs/PARALLEL_DEVELOPMENT.md` § Phase 1 holds the rules behind the format.
+Read it when a validator error is unclear, not before — and never reach for
+plugin source under `domains/`, `tools/` or `extras/` to infer the shape. A
+planner that did produced a plan with every field renamed.
+
 ## Prerequisites
-- Read `AI_CONTEXT.md` for available tools.
-- Read `INSTRUCTIONS_FOR_AI.md` for rules and templates.
+
+Both files above. Nothing else: the plugin template lives in `AI_CONTEXT.md`
+§ Plugin Authoring Guide, generated on every boot, and the rules are the 13
+Non-Negotiable Rules in `AGENTS.md`.
 
 ## Steps
 
@@ -28,7 +55,8 @@ persistence contract), and — ONLY if any plugin publishes or consumes events
 the `atomic_with_db` outbox question — and the declared `idempotency_test` /
 `sad_path_test` files). A pure-CRUD domain has no `flows` section at all; a
 domain whose delete cascades through one event has exactly one flow.
-Validate with `POST /system/plan/validate` before writing code. Build in that
+Validate with `microcoreos plan validate` before writing code (offline —
+nothing needs to be booted). Build in that
 order — tools first if any, then migrations + models, then plugins with their
 events. Nothing below this line should require a decision the plan did not
 already make. Expected size for a CRUD domain with one event chain: ~80-120
@@ -77,75 +105,14 @@ CREATE TABLE IF NOT EXISTS {name}s (
 
 ### 4. Create plugins (1 file = 1 use case)
 
-For each operation (create, get_all, get_by_id, update, delete), create a separate plugin file in `domains/{name}/plugins/`.
-
-**Critical rules**:
-- Define the **request schema** (what the HTTP client sends) at the **top of the plugin file**, NOT in the models folder.
-- Define the **response schema** (what the HTTP client receives) at the **top of the plugin file** too — never import the Entity for this; only expose the fields you actually return.
-- Define the **event payload schema** for every event this plugin publishes, also at the top of the file: `{Name}CreatedPayload(BaseModel)`. Publish with `.model_dump()` (bare call, no arguments). The publisher owns the event contract — consumers in other domains never import it; they declare their own model with only the fields they need (tolerant reader).
-- Always pass `response_model=` to `add_endpoint` — this generates complete OpenAPI docs.
-
-Example for create:
-
-File: `domains/{name}/plugins/create_{name}_plugin.py`
-
-```python
-from typing import Optional
-from pydantic import BaseModel
-from microcoreos import BasePlugin
-
-# ── Request schema lives HERE ──────────────────────
-class Create{Name}Request(BaseModel):
-    # Only input fields — no id, no internal fields
-    field1: str
-    field2: int
-
-# ── Response schema lives HERE ─────────────────────
-class {Name}Data(BaseModel):
-    id: int
-    field1: str
-    field2: int
-
-class Create{Name}Response(BaseModel):
-    success: bool
-    data: Optional[{Name}Data] = None
-    error: Optional[str] = None
-
-# ── Event payload schema lives HERE (publisher owns the contract) ──
-class {Name}CreatedPayload(BaseModel):
-    id: int
-
-class Create{Name}Plugin(BasePlugin):
-    def __init__(self, http, db, event_bus, logger):
-        self.http = http
-        self.db = db
-        self.bus = event_bus
-        self.logger = logger
-
-    async def on_boot(self):
-        self.http.add_endpoint(
-            "/{name}s", "POST", self.execute,
-            tags=["{Name}s"], request_model=Create{Name}Request,
-            response_model=Create{Name}Response,
-        )
-
-    async def execute(self, data: dict, context=None):
-        try:
-            req = Create{Name}Request(**data)
-            new_id = await self.db.execute(
-                "INSERT INTO {name}s (field1, field2) VALUES ($1, $2) RETURNING id",
-                [req.field1, req.field2]
-            )
-            self.logger.info(f"{Name} created with ID {new_id}")
-            await self.bus.publish("{name}.created", {Name}CreatedPayload(id=new_id).model_dump())
-            return {"success": True, "data": {"id": new_id, "field1": req.field1, "field2": req.field2}}
-        except Exception as e:
-            # Safe Error Reporting: log technically, respond safely (never str(e)).
-            self.logger.error(f"Failed to create {name}: {e}")
-            return {"success": False, "error": "Database operation failed"}
-```
+One plugin file per operation in `domains/{name}/plugins/`. The template — with
+request, response and event-payload schemas inline, and the rules that go with
+them — is `AI_CONTEXT.md` § **Plugin Authoring Guide**, regenerated on every
+boot and already inside every executor prompt. A fourth copy lived here.
 
-Repeat for: `get_{name}s_plugin.py`, `get_{name}_by_id_plugin.py`, `update_{name}_plugin.py`, `delete_{name}_plugin.py`.
+The one thing that is this workflow's own decision: which operations exist.
+A CRUD domain is create / get_all / get_by_id / update / delete, one file each,
+each declared in the plan before any of them is written.
 
 ### 5. Verify
 
@@ -160,13 +127,14 @@ Check that:
 - `GET /system/lint` has no warnings and no `UNTYPED_PAYLOAD` for your events
 - `GET /system/events/schemas` lists every event the plan declared
 - `AI_CONTEXT.md` was regenerated with the new domain — **done when it matches the plan**
+- `microcoreos schema` shows the new tables with the columns the plan declared
 
 ### 6. Generate tests
 
 Create `tests/test_{name}_plugin.py` with one test per plugin. Mock exactly
-the tools the plan's `mocks:` field lists; run the rest as real in-memory
+the tools the plan's `tools:` field lists; run the rest as real in-memory
 instances (`INSTRUCTIONS_FOR_AI.md` § Testing). Example with everything
-mocked (`mocks: [http, db, event_bus, logger]`):
+mocked (`tools: [http, db, event_bus, logger]`):
 
 ```python
 import pytest

{microcoreos-0.2.0 → microcoreos-0.2.2}/AGENTS.md

@@ -4,21 +4,79 @@ This file is the single, absolute entry point for any AI agent (Gemini, Claude,
 
 ---
 
-## 📖 Reading Path (minimize token usage)
+## 🚦 Start here: `microcoreos status`
 
-1. **`plans/active_plan.md`** — The checklist for your assigned task (the formal contract lives in `plans/active_plan.yaml`).
-2. **`AI_CONTEXT.md`** — Contains the live inventory of active tools (with exact signatures) and domain tables/endpoints. **Read only the tools and tables you need.**
-3. **`domains/{domain}/models/{name}.py`** — Entity model (DB mirror). *Advisory: Table structures are already mirrored in AI_CONTEXT.md.*
-4. **`INSTRUCTIONS_FOR_AI.md`** — Read ONLY for advanced tasks (building new tools, testing in-depth, or changing kernel internals).
-5. **`docs/TECH_DEBT.md`** — What is knowingly unfinished and what it would cost to finish. Read ONLY when scoping work that might overlap an open item.
+One command, before anything else. It answers the three questions that
+silently derail a session: **which plan is actually active** (and whether it is
+still the shipped template), **how much of it is done**, and **whether
+`AI_CONTEXT.md` still describes the code on disk**.
+
+There is exactly one plan path: **`plans/active_plan.yaml`**. The workflows,
+the executor prompts and the checklist cross-check read that path and no other.
+A plan written to `plans/my_feature.yaml` is a plan nothing will ever execute —
+and because the shipped template is itself a valid plan, an agent that opens
+`active_plan.yaml` and finds it untouched will build the *example* domain and
+report success. That is why the template carries `template: true` and fails
+validation until you delete the line.
 
 ---
 
-## 🧭 Pick the Right Workflow (scale ladder)
+## 📖 Your reading route — find your role, read those files, stop
+
+Four roles do the work, and **each needs a different slice**. Reading outside
+your slice is not thoroughness, it is budget: the Planner that also loads the
+plugin templates spends ~3,000 tokens on code it will never write.
+
+| You are… | Read exactly this | **Write exactly this** | Not this |
+|---|---|---|---|
+| **Planner** — turning a request into a plan | **1.** `plans/active_plan.yaml` — the file you are about to overwrite. It ships as a worked example of all three feature shapes, and it is the cheapest, densest statement of the format there is. **2.** `AI_CONTEXT.md` **down to `## 🧩 Plugin Authoring Guide`** (existing tools, tables, models, routes, events). **3.** `docs/PARALLEL_DEVELOPMENT.md` **§ Phase 1** for the rules behind it | **`plans/active_plan.yaml` + `plans/active_plan.md`, overwriting them.** Never a new filename — `plans/twitter_plan.yaml` is a plan nothing will execute | The Authoring Guide, Phases 2-3, `domains/`, `tools/`, `tests/`, `extras/` |
+| **Phase 0 Builder** — migrations, models, tools | `plans/active_plan.yaml` **§ phase_0** only | Exactly the files `phase_0` names: its migrations, its models, its tools | Everything else. The plan already decided every column |
+| **Executor** — one plugin + its test | **Nothing.** Your prompt already contains `AI_CONTEXT.md` + the plan + your one task line | Exactly two files: the `file:` and `test:` your task declares | Any file at all — opening one only invites guessed paths |
+| **Coordinator** — dispatch, verify, reconstruct | `plans/active_plan.md` (the checklist/state machine) + `docs/PARALLEL_DEVELOPMENT.md` **§ Phases 2-3** | Only the checkboxes in `plans/active_plan.md` | The plan's internals; the checklist is the state |
+
+If you are the Planner, the first thing you write is `plans/active_plan.yaml`
+itself — not a draft under another name that someone copies later. The copy
+step is where the plan gets lost: a validated plan sat in `plans/twitter_plan.yaml`
+while two sessions in a row built the template's example domain instead.
+
+And write it **before you ask anything**. Planning is usually a conversation,
+and checking in is welcome — but never *instead of* writing. A plan that ends
+as prose in your reply and a *"shall I proceed?"* produced nothing: the next
+phase reads files, not answers, and the session may not be interactive at all.
+Write the YAML, run `microcoreos plan validate`, and then ask — the operator
+reviews a real file rather than a description of one.
 
-Match the request to its workflow BEFORE planning. Over-planning a small
-request is a failure mode: **a plan must be proportional to its request**
-(see "Plan sizing" in `docs/PARALLEL_DEVELOPMENT.md`).
+**And the commands your role may run — nothing else boots the system:**
+
+| Role | May run |
+|---|---|
+| Planner | `microcoreos status`, `microcoreos plan validate` |
+| Phase 0 Builder | `microcoreos migrate`, `microcoreos schema` |
+| Executor | none — write your two files and stop |
+| Coordinator | `uv run -m pytest`, `microcoreos status`, and `microcoreos` (the real boot) for the final lint |
+
+**Never `microcoreos run` / `uv run main.py` outside that last row.** It serves
+forever: in the foreground it hangs your session, in the background it leaves a
+process holding the port that makes the next `microcoreos migrate` refuse to
+run. `migrate` is the boot that ends; `status` and `schema` answer everything
+you would have booted to find out.
+
+**No `AI_CONTEXT.md` in the project?** It is generated, not shipped — a freshly
+scaffolded project has none until something boots. Run `microcoreos migrate`
+once and it appears. Do not go exploring `domains/` and `tools/` to reconstruct
+what it would have said: that is the search the manifest exists to replace, and
+it costs an order of magnitude more to arrive at less.
+
+Read on demand, never up front: `INSTRUCTIONS_FOR_AI.md` (building tools,
+testing in depth, kernel internals) · `docs/internal/TECH_DEBT.md` (only when scoping
+work that may overlap an open item) · `domains/{domain}/models/{name}.py` (its
+fields are already in `AI_CONTEXT.md`).
+
+**Size the plan to the request** — over-planning a small one is a failure mode.
+Every workflow below opens with the **same** two-file route as the Planner row
+above, so following the ladder and following the table land in the same place;
+each then adds only what is specific to its size. The phases themselves are in
+`docs/PARALLEL_DEVELOPMENT.md` and are not repeated in any of them.
 
 | Request | Workflow | Expected plan size |
 |---|---|---|
@@ -42,6 +100,21 @@ uv run -m pytest tests/test_file.py                     # Run a single test
 docker compose -f dev_infra/docker-compose.yml up -d    # Start dev infrastructure (PostgreSQL)
 ```
 
+The plan pipeline — prefix with `uv run` if the package is installed in a venv:
+
+```bash
+microcoreos status                  # Active plan, progress, manifest freshness
+microcoreos plan validate           # The 18 plan rules, OFFLINE (no server, no jq, no curl)
+microcoreos migrate                 # Apply migrations AND regenerate AI_CONTEXT.md
+microcoreos schema                  # The live tables and columns, read by the db tool itself
+```
+
+`microcoreos schema` is how you verify a migration. Do not reach for `sqlite3`
+(not installed) or `import aiosqlite` from the system interpreter (it lives in
+`.venv`) — and do not read the DB file directly: `describe_schema()` normalizes
+types to the closed vocabulary every engine shares, so it reports what a swap
+must preserve.
+
 ---
 
 ## 🛡️ Non-Negotiable Rules
@@ -81,63 +154,29 @@ The Kernel (ToolProxy & Container) is infrastructure-blind:
 
 ---
 
-## 🔄 Batch Parallel Execution Workflow (Coordinator Guidelines)
-
-The canonical methodology (and its phase numbering) is `docs/PARALLEL_DEVELOPMENT.md`.
-This is the coordinator's operational summary:
+## 🔄 The pipeline, in five lines
 
-1. **Phase 1 — The Plan (contract)**: The formal YAML plan lives in `plans/active_plan.yaml`; the execution checklist (all tasks `[ ]`) in `plans/active_plan.md`. Validate with `POST /system/plan/validate` — **zero `errors` before anything else runs**. An invalid plan is fixed in the plan, never patched in code.
-2. **Phase 0 — Foundation (Serial)**: Write the tools (if any), then all domain models and SQL migrations sequentially, exactly as the plan's `columns:` declare them. Run `uv run main.py --boot-tool db` (or `microcoreos run --boot-tool db` if installed) to migrate and regenerate `AI_CONTEXT.md`.
-3. **Phase 2 — Parallel Write Wave**: Spawn N subagents (one per plugin), each with the **canonical executor prompt**: a byte-identical shared prefix (`AI_CONTEXT.md` → `plans/active_plan.yaml`, in that order — the manifest embeds the executor rules and templates as its "Plugin Authoring Guide" section) followed by ONE per-agent line at the end ("Implement feature `<PluginName>` from the plan above"). Subagents never open the plan or `AI_CONTEXT.md` themselves — dispatch them **write-only, scoped to their two files** (write capability restricted to the exact paths the plan declares for the task — `file:` + `test:`, or the flow's two test paths; no read/search/shell tools): the prefix is self-sufficient by construction (one complete template per deliverable type in `AI_CONTEXT.md` § Authoring Templates), so reading capability only invites redundant verification and guessed paths. The identical prefix lets any engine with prefix caching (local KV cache, hosted prompt caching) process the shared block once and reuse it for the whole wave — dispatch the first agent, let it start responding, then fire the rest. Each agent writes exactly two files: its plugin and its unit test.
-4. **Phase 3 — Bulk Verification**: Once all subagents finish writing, run the entire test suite in a single execution (`uv run -m pytest`), then boot and check `GET /system/lint`.
-5. **Cleanup & Reconstruct**:
-   * For passing plugins: Mark their checkbox as `[x]` in `plans/active_plan.md`.
-   * For failing plugins: **Delete** the created plugin and unit test files, keep their checkbox as `[ ]`, and spawn a new wave of clean agents to rewrite them from scratch.
-   * Repeat until all checkboxes are `[x]`.
+The methodology, the phase numbering and the executor-prompt mechanics live in
+`docs/PARALLEL_DEVELOPMENT.md` — **canonically, and only there**. This used to
+be a second copy of it, which is precisely how the copy drifted: it prescribed
+`--boot-tool db` for phase 0 long after that stopped regenerating the manifest,
+and no one compares two documents to notice.
 
----
-
-## ⚡ Minimal Plugin Template
-
-```python
-from typing import Optional
-from pydantic import BaseModel, Field
-from microcoreos import BasePlugin
-
-class CreateThingRequest(BaseModel):
-    name: str = Field(min_length=1, max_length=100)
-
-class ThingData(BaseModel):
-    id: int
-    name: str
-
-class CreateThingResponse(BaseModel):
-    success: bool
-    data: Optional[ThingData] = None
-    error: Optional[str] = None
-
-class CreateThingPlugin(BasePlugin):
-    def __init__(self, http, db, logger):
-        self.http = http
-        self.db = db
-        self.logger = logger
-
-    async def on_boot(self):
-        self.http.add_endpoint("/things", "POST", self.execute,
-                               tags=["Things"], request_model=CreateThingRequest,
-                               response_model=CreateThingResponse)
-
-    async def execute(self, data: dict, context=None):
-        try:
-            req = CreateThingRequest(**data)
-            new_id = await self.db.execute(
-                "INSERT INTO things (name) VALUES ($1) RETURNING id", [req.name]
-            )
-            return {"success": True, "data": {"id": new_id, "name": req.name}}
-        except Exception as e:
-            self.logger.error(f"Failed to create thing: {e}")
-            return {"success": False, "error": "Database error"}
-```
+| Phase | Command | Gate |
+|---|---|---|
+| 1 — Plan | *(the Planner writes `plans/active_plan.yaml` + `.md`)* | `microcoreos plan validate` → **zero errors** |
+| 0 — Foundation | *(migrations + models, 1:1 from `phase_0`)* | `microcoreos migrate` then `microcoreos schema` |
+| 2 — Wave | *(N executors, one plugin + one test each)* | every declared file exists |
+| 3 — Verify | `uv run -m pytest` | green, then `GET /system/lint` clean |
+| — Reconstruct | delete the failures, respawn fresh executors | all `[x]` in `plans/active_plan.md` |
+
+Two rules the phases do not state on their own:
+
+- **An invalid plan is fixed in the plan, never patched in code.** Errors carry
+  the YAML that fixes them — paste it, do not re-derive it.
+- **A plan is only ever `plans/active_plan.yaml`.** Any other filename is a plan
+  nothing will execute, and the shipped template is itself valid, so nothing but
+  its `template: true` marker can tell it apart from yours.
 
 ---
 

{microcoreos-0.2.0 → microcoreos-0.2.2}/AI_CONTEXT.md

@@ -293,13 +293,10 @@ Async SQLite Persistence Tool (sqlite):
     - **res**: EventSchemasData(schemas: dict)
   - `GET /system/lint`
     - **res**: SystemLintData(arch_violations: list[str], drift_warnings: list[str], event_contract_violations: list[LintFinding(code: str, severity: str, event: Optional[str], publisher: Optional[str], consumer: Optional[str], detail: str)], route_collisions: list[str], table_ownership_warnings: list[str], field_divergence_warnings: list[str])
-  - `POST /system/plan/validate`
-    - **req**: plan: Optional[dict], plan_yaml: Optional[str]
-    - **res**: ValidatePlanData(valid: bool, errors: list[PlanViolation(rule: int, severity: str, where: str, detail: str)], warnings: list[PlanViolation(rule: int, severity: str, where: str, detail: str)])
 - **Events emitted**: none
 - **Events consumed**: none
 - **Dependencies**: container, http, logger
-- **Plugins**: devtools.DiscoveryNamingLinterPlugin, devtools.DomainIsolationLinterPlugin, devtools.EventContractLinterPlugin, devtools.EventSchemasPlugin, devtools.FieldDivergenceLinterPlugin, devtools.PlanValidatorPlugin, devtools.RouteCollisionLinterPlugin, devtools.TableOwnershipLinterPlugin, devtools.ToolDocDriftLinterPlugin
+- **Plugins**: devtools.DiscoveryNamingLinterPlugin, devtools.DomainIsolationLinterPlugin, devtools.EventContractLinterPlugin, devtools.EventSchemasPlugin, devtools.FieldDivergenceLinterPlugin, devtools.RouteCollisionLinterPlugin, devtools.TableOwnershipLinterPlugin, devtools.ToolDocDriftLinterPlugin
 
 ### `system`
 - **Tables**: none
@@ -344,8 +341,10 @@ Your task line names either a **feature** or a **flow's tests**:
 - Flow-tests task → 1. the flow's `e2e_test` (trigger the happy path, assert
   the causal chain with `tests/helpers/trace_chains.py`:
   `assert_chain(build_tree(bus.get_trace_history()), [...])`) and 2. its
-  `sad_path_test` (force the consumer to fail with a mock that raises, assert
-  `_dlq.<event>` appears as a child of the failed event in the same tree).
+  `sad_path_test` (force the consumer to fail — the mock must raise on the
+  FIRST tool call the handler makes, since an idempotency guard runs before
+  the effect — and assert `_dlq.<event>` appears as a child of the failed
+  event in the same tree).
 
 Nothing else: no migrations, no entity models, no edits to `main.py`, no
 touching other domains or other tasks' files. When both files are written,
@@ -357,8 +356,11 @@ follow-ups.
 1. **Schemas inline** — request, response AND event payload models at the top
    of the plugin file. Never import them from `models/` or other domains.
 2. **DI by parameter name** — `__init__(self, http, db, logger)` receives the
-   tools named `http`, `db`, `logger`. Inject exactly the tools your feature
-   uses. No hardcoded imports from `tools/`.
+   tools named `http`, `db`, `logger`. No hardcoded imports from `tools/`.
+   **Your parameters are exactly your feature's `tools:` list in the plan, in
+   that order** — not what a template happens to show. The plan is the
+   contract, and the test is written against that same list: add a `logger`
+   nobody declared and the two no longer fit.
 3. **Return envelope** — `{"success": bool, "data": ..., "error": ...}`:
    `success` always present, `data` on success, `error` on failure. Responses
    serialize AS-IS — `response_model` does NOT backfill omitted keys, so an
@@ -398,6 +400,26 @@ follow-ups.
     coherent without any of you coordinating: your feature is written in
     isolation, but its vocabulary is shared.
 
+11. **Idempotent consumer** — when the plan's flow link says
+    `idempotent: true`, guard on `event.id` (the envelope is frozen, so a
+    redelivery carries the same one) and mark it **after** the effect:
+
+    ```python
+    if await self.state.has(event.id, namespace="thing-seen"):
+        return                                    # duplicate: already applied
+    await self.state.increment(...)               # the effect
+    await self.state.set(event.id, True, namespace="thing-seen", ttl=3600)
+    ```
+
+    Marking first drops the event: the effect raises, the retry hits the guard,
+    returns "already seen" — no work, no error, no DLQ. Write the
+    double-delivery test under the exact name `idempotency_test` gives, with a
+    real `StateTool()`: an `AsyncMock` returns truthy from `has()`, so the guard
+    swallows everything and the test proves nothing. Rule 6 says a *plugin*
+    never imports the envelope; a *test* has to build one —
+    `from tools.event_bus.envelope import EventEnvelope` — and deliver the same
+    instance twice.
+
 ### Templates — one per deliverable type, copy the one your task matches
 
 Each is a whole file, imports to last line; nothing a feature or flow-tests
@@ -600,7 +622,8 @@ x = tool.method.return_value.__aenter__.return_value  # bound by `as x:`
   PLAN (route, envelope shape, declared tables, declared payload keys) —
   never from your own implementation. The test is the contract's proof; a
   test that mirrors the code proves nothing.
-- Mock exactly the tools your feature's `mocks:` lists
+- Mock exactly the tools your feature's `tools:` lists — all of them; an
+  omitted `logger` is still a required positional argument
   (`unittest.mock.AsyncMock` / `MagicMock`); run every other injected tool as
   a real in-memory instance (SQLite `:memory:` with your domain's migration
   applied, in-process event bus).